Terraform Cloud Overview: VCS, Runs, and Workspaces in Practice

Terraform Cloud provides VCS-triggered remote execution, per-workspace state management and access control, and guardrails like policies, cost estimation, and Run Tasks.

This article focuses on VCS, Runs, and workspaces, walking through the key design considerations and the points most often tested on the exam, with concrete examples.

The Big Picture: VCS → Workspace → Run Flow

The core unit of Terraform Cloud is the workspace — each one holds a single Terraform state and configuration. When linked to a VCS, branch updates and PRs automatically generate Runs, which proceed through Plan → (Policy/Cost) → Apply.

Remote execution uses Terraform Cloud's managed runtime or an agent, and results are recorded on the workspace. PRs trigger a speculative plan that does not modify state.

• VCS integration: connect GitHub, GitLab, Bitbucket, etc. via OAuth. You can specify the branch, working directory, and trigger prefixes.
• Run lifecycle: Plan → Policy Check → Cost Estimation → (approval) → Apply. PRs run a speculative plan only.
• State management: each workspace holds its own remote state, with locking, rollback, and history.

Terraform Cloud's logical architecture (VCS → Workspace → Run)

Example repository layout for VCS integration (monorepo)

repo-root/
  ├── envs/
  │   ├── prod/network/        # Workspace: prod-network
  │   └── staging/network/     # Workspace: stg-network
  └── modules/
      └── vpc/

Workspace Design and VCS Integration Tips

Split workspaces by environment or responsibility — for example, per prod/staging tier, or per component (network/app/db). In a monorepo, use the working directory setting; in a multi-repo layout, mapping each repository 1:1 to a workspace keeps things manageable.

For VCS integration, pin the target branch and working directory, and use trigger prefixes so unrelated changes don't fire Runs. Deliberate tagging and separation along team/project boundaries directly translates into stronger access control, auditability, and observability.

• Environment separation: split prod and non-prod into separate workspaces, with distinct roles and approval flows.
• VCS integration: pin the target branch, set a working directory, and use trigger prefixes to cut noise.
• Naming convention: something like <env>-<component> keeps workspaces searchable and auditable.

Connecting a Terraform Cloud workspace from the CLI (cloud block)

terraform {
  cloud {
    organization = "acme"
    workspaces {
      name = "prod-network"
    }
  }
}

# 以降は通常の Terraform 設定
module "vpc" {
  source = "./modules/vpc"
  cidr_block = "10.0.0.0/16"
}

Run Lifecycle, Queues, Approvals, and Permissions

Runs execute serially per workspace; when multiple triggers fire against the same workspace, they queue up. Keep the queue clean by cancelling or discarding stale Runs.

Apply requires sufficient permissions (typically write or higher on the workspace), and unless Auto apply is enabled, a manual approval step is inserted. Speculative plans on PRs don't mutate state, so there's no risk of an accidental apply, but they can still be evaluated by policy and cost checks.

• Speculative plan: safely visualize PR/draft changes. No state update.
• Queue control: prioritize the latest commit's Run and cancel older Runs to shorten the queue.
• Approval flow: be explicit about whether Auto apply is allowed, and design Plan/Apply roles accordingly.

Terraform Cloud workspace configuration (tfe provider example)

provider "tfe" {
  hostname = "app.terraform.io"
  token    = var.tfc_token
}

resource "tfe_workspace" "prod_network" {
  name           = "prod-network"
  organization   = "acme"
  execution_mode = "remote"      # リモート実行
  auto_apply     = false          # 手動承認フロー
}

Comparing Execution Modes: Remote / Agent / Local

The Terraform Cloud default is Remote execution, where the SaaS handles the Terraform binary, plugins, and log collection. If you can only reach resources inside a private network, deploy an agent that pulls jobs from Terraform Cloud and runs them locally. If you want CLI-led runs while still using TFC just for remote state and variables, choose Local execution (CLI-driven run).

Your choice depends on whether you prioritize network reach, audit requirements, or execution reproducibility.

• Remote: the simplest option. Everything runs in the SaaS.
• Agent: combines private-network reachability with strict audit requirements.
• Local: run on the developer's machine while centralizing state and variables in TFC.

Creating an agent pool (tfe provider example)

resource "tfe_agent_pool" "priv" {
  name         = "prod-private-pool"
  organization = "acme"
}

# 生成されたトークンでエージェントを起動し、ワークスペースの実行モード=agent/プール=上記を割当

Guardrails: Policies, Cost Estimation, and Run Tasks

Policies (e.g., Sentinel) let you block dangerous changes based on the Plan output. Cost estimation surfaces a rough cost forecast for major providers and flags threshold breaches. Run Tasks embed third-party security and compliance checks into the Run.

For production workspaces, the combination of baseline policies (mandatory tags, region allow-listing, size caps, etc.) and a cost ceiling is a key topic both on the exam and in real-world operations.

• Policy Check: evaluated after Plan. Mix hard-mandatory and soft-mandatory enforcement as needed.
• Cost Estimation: surface the cost impact of each change.
• Run Tasks: integrate security scans or CMDB integrations into the Run.

Simple Sentinel policy example (restricting instance types)

import "tfplan/v2" as tfplan

main = rule {
  all tfplan.resource_changes as rc {
    rc.type != "aws_instance" or
    (rc.change.after != null and rc.change.after.instance_type not in ["t2.micro"])  # 例: 特定タイプを禁止
  }
}

Operational Patterns: Environment Separation, Mono/Multi-Repo, and Run Triggers

When infrastructure has dependencies, you can use a successful Apply on an upstream workspace as a trigger to start Plan/Apply on a downstream workspace. This keeps things loosely coupled while automating consistency across environments and components.

In a monorepo, carefully configure working directory and trigger prefixes so that unrelated directory changes don't fire Runs. With a multi-repo layout, you get review, permission, and audit isolation per repository.

• Run Triggers: control upstream → downstream ordering. Watch out for cyclic dependencies.
• Environment separation: enforce manual approvals and stricter policies in prod; prioritize fast feedback in non-prod.
• State separation: split per workspace, not per branch.

Creating a Run Trigger (run downstream after the upstream applies)

resource "tfe_run_trigger" "app_after_network" {
  workspace_id  = tfe_workspace.app.id      # 下流 (起動される側)
  sourceable_id = tfe_workspace.network.id  # 上流 (トリガー側)
}

Check Your Understanding

Frequently Asked Questions