Terraform Cloud の全体像: VCS・Runs・ワークスペースの実務整理

Terraform Cloud は、VCS 連携でトリガーされるリモート実行、ワークスペース単位の状態管理と権限制御、ポリシー/コスト推定/Run Tasks などのガードレールを提供します。

この記事では、VCS・Runs・ワークスペースにフォーカスし、設計の勘所と試験で問われやすいポイントを実例と併せて解説します。

全体像: VCS → Workspace → Run の基本フロー

Terraform Cloud の中核は「ワークスペース」で、各ワークスペースは単一の Terraform ステートと設定を持ちます。VCS と紐付けると、ブランチ更新や PR に応じて Run が自動生成され、Plan → (ポリシー/コスト) → Apply という流れで実行されます。

リモート実行は Terraform Cloud のマネージド実行環境またはエージェントを用い、結果はワークスペースに記録されます。PR 上では推測プラン (speculative plan) が実行され、ステート変更は行われません。

• VCS 連携: GitHub/GitLab/Bitbucket などを OAuth で接続。ブランチ/ディレクトリ/トリガープレフィックスを指定可能。
• Run ライフサイクル: Plan → Policy Check → Cost Estimation → (承認) → Apply。PR では推測プランのみ。
• ステート管理: ワークスペースごとにリモートステートを保持。ロック/ロールバック/履歴参照が可能。

Terraform Cloud の論理アーキテクチャ (VCS → Workspace → Run)

VCS 連携前提のリポジトリ構成例 (モノレポ)

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

ワークスペース設計と VCS 連携のコツ

ワークスペースは環境や責務で分けるのが基本です。例えば prod/staging ごと、あるいはコンポーネント (network/app/db) ごとに分離します。モノレポでは working directory を使い、マルチレポでは各リポジトリを 1:1 で紐付けると管理しやすくなります。

VCS 連携では、対象ブランチとワーキングディレクトリを明確にし、不要な変更で Run を発火させないようにトリガープレフィックスを設定します。計画的なタグ運用やチーム/プロジェクトの境界に合わせた分離が、権限・監査・可観測性の確保に直結します。

• 環境分離: prod と非 prod はワークスペースを分け、ロール/承認フローも区別する。
• VCS 連携: 対象ブランチ固定、working directory 指定、トリガープレフィックスでノイズ削減。
• 命名規則: <env>-<component> などで検索性と監査性を担保。

CLI から Terraform Cloud ワークスペースへ接続 (cloud ブロック)

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

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

Run ライフサイクルとキュー/承認/権限

Run はワークスペース単位で直列実行され、同一ワークスペースで複数のトリガーが同時に発生するとキューに積まれます。不要な古い Run はキャンセルやディスカードで整理しましょう。

Apply には適切な権限 (通常はワークスペースの書き込み以上) が必要で、Auto apply を有効化していない場合は手動承認が挟まります。PR での推測プランはステートを書き換えないため、誤適用の心配はありませんが、ポリシー/コストのチェック対象にはできます。

• 推測プラン: PR/ドラフト変更の安全な可視化。ステート更新なし。
• キュー制御: 最新コミットの Run を優先し、古い Run をキャンセルして待ち行列を短縮。
• 承認フロー: Auto apply の可否とロール設計 (Plan/Apply 権限) を明確に。

Terraform Cloud ワークスペース設定 (tfe プロバイダ例)

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          # 手動承認フロー
}

実行モードの比較: Remote / Agent / Local

Terraform Cloud の標準は Remote 実行で、Terraform バイナリとプラグイン、ログ収集を SaaS 側が担います。プライベートネットワーク内のリソースにしか到達できない場合はエージェントを用意し、Terraform Cloud からジョブをプルして実行します。CLI 主導でリモートステートと変数管理のみを使いたい場合は Local 実行 (CLI-driven run) を選びます。

ネットワーク要件、監査要件、実行の再現性のどれを優先するかで選択が変わります。

• Remote: 最もシンプル。SaaS 側で完結。
• Agent: プライベート到達性と監査要件を両立。
• Local: 開発者の手元で実行しつつ、ステート/変数は TFC で集中管理。

エージェントプールの作成 (tfe プロバイダ例)

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

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

ガードレール: ポリシー、コスト推定、Run Tasks

Sentinel などのポリシー適用により、Plan 結果から危険な変更をブロックできます。コスト推定は主要プロバイダで概算コストを提示し、しきい値超過を検知します。Run Tasks はサードパーティのセキュリティ/コンプライアンスチェックを Run に組み込みます。

本番系ワークスペースでは、最低限のポリシー (タグ必須、指定リージョン外禁止、サイズ上限など) とコスト上限の組み合わせが実務・試験の双方で重要な論点です。

• Policy Check: Plan 後に評価。強制/ソフトフォースを使い分ける。
• Cost Estimation: 変化点のコスト影響を可視化。
• Run Tasks: セキュリティスキャンや CMDB 連携を Run に統合。

Sentinel の簡易ポリシー例 (インスタンスタイプ制限)

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"])  # 例: 特定タイプを禁止
  }
}

実務導線: 環境分離・モノレポ/マルチレポと Run Triggers

インフラの依存関係がある場合、上流ワークスペースの Apply 成功をトリガーに下流ワークスペースの Plan/Apply を起動できます。これにより疎結合を保ちながら、環境間・コンポーネント間の整合を自動化できます。

モノレポでは working directory とトリガープレフィックスを厳密に設定し、意図しないディレクトリ変更で Run が走らないようにします。マルチレポではリポジトリごとのレビュー/権限/監査を独立させられます。

• Run Triggers: 上流→下流の順序制御。サイクル依存に注意。
• 環境分離: prod は手動承認/ポリシー強化、非 prod は高速なフィードバックを優先。
• State 分離: ブランチごとではなくワークスペースごとに分ける。

Run Trigger の作成 (上流の適用後に下流を実行)

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

問題で確認

よくある質問