Terraform Cloud バックエンド徹底ガイド: ワークスペース連携の設計と運用

本稿は Terraform Cloud のバックエンド（cloud ブロック）を使い、ワークスペースとコードベースを無理なく連携させる方法を、Associate / Pro レベルの出題傾向を踏まえて整理します。

ローカルやS3等との違い、CLI/VCS駆動の使い分け、変数と権限のベストプラクティス、トラブル時の確認観点まで、試験と実務の両面で迷いがちな点を具体化します。

Terraform Cloud バックエンドの要点とワークスペースの役割

Terraform Cloud のバックエンドは、state の保管・ロック、実行の記録、ポリシー適用、RBAC をサービス側で担保します。ローカルバックエンドと比べ、並行実行時の衝突や state 配布の手間が抑えられ、監査性が上がります。

Terraform Cloud の最小単位はワークスペースです。1ワークスペース = 1 state と考え、コードベース（ディレクトリ）をワークスペースに結び付けます。cloud ブロックで organization と対象ワークスペース名を明示しておくと、誤った state へ apply する事故を防げます。

• cloud ブロックは推奨の設定方法（従来の remote バックエンド指定より簡潔）。
• 1ワークスペース1状態（state）の原則。環境（dev/stg/prod）ごとに分離すると衝突やドリフト調査が容易。
• 実行モード（CLI/VCS/API）はワークスペース単位で選べる。監査ログやキュー、ロールバックはサービス側で管理。

cloud ブロックの設計: ディレクトリとワークスペースの結合

最も衝突が少ないのは「ディレクトリ（スタック）単位で cloud.workspaces.name を固定」する方法です。これにより terraform apply が常に同じワークスペースへ向かい、意図しない state の上書きを避けられます。

Terraform Cloud の実行はワークスペースに設定した Terraform バージョンで行われます。ローカル CLI はジョブの提出役です。ローカルとサービス側でバージョン差があっても基本的に動作しますが、言語機能差によるパースエラーを避けるため、極端な乖離は避けましょう。

• organization は必須。TFE（Private）利用時は hostname も指定。
• workspaces.name を明示して1:1対応を作る。切替はブロックの値を変更（もしくはディレクトリを分ける）。
• VCS 駆動ならブランチやパスでワークスペースを分ける設計が安定。CLI 駆動は手元で plan してからリモート実行できる。

cloud ブロックとリモート実行、リモート state 参照の例

# terraform/main.tf
terraform {
  cloud {
    organization = "acme"
    workspaces {
      name = "network-prod"
    }
    # TFE を使う場合:
    # hostname = "tfe.example.com"
  }
  # Terraform CLI はジョブを提出。実行はワークスペースに設定されたバージョンで行われる。
}

provider "aws" {
  region = var.region
}

module "vpc" {
  source = "terraform-aws-modules/vpc/aws"
  name   = "core-prod"
  cidr   = "10.0.0.0/16"
}

# 別ワークスペースの state を安全に参照（読み取り専用）
data "terraform_remote_state" "shared" {
  backend = "remote"
  config = {
    organization = "acme"
    workspaces = {
      name = "shared-services-prod"
    }
  }
}

output "shared_vpc_id" {
  value = data.terraform_remote_state.shared.outputs.vpc_id
}

ワークスペース設計: 命名・分割・状態の隔離

誤適用を減らすには、環境やリージョン、プロダクト軸でワークスペースを分けます。1 ワークスペースが管理する範囲は「変更単位」で決めると保守しやすく、計画の可視性も上がります。

モノレポ運用では、ディレクトリ構造とワークスペース名規約を一致させると、VCS 駆動の自動トリガ設定が容易になります。

• 命名例: appA-prod-tokyo、appA-stg-tokyo のように環境とリージョンを明示。
• ネットワークや共有基盤は独立ワークスペースに切り出し、上位から terraform_remote_state で参照。
• 1 ワークスペースの計画/適用時間が長すぎる場合は、論理境界（例: VPC、DB、アプリ）でスタック分割を検討。

変数・秘密情報の扱い: Workspace Variables と Variable Sets

Terraform Cloud にはワークスペース変数（Terraform 変数と環境変数）と、組織またはプロジェクトにまたがる Variable Set があります。共通値は Variable Set、差分はワークスペース側に置くと管理が単純になります。

機密値は Sensitive として登録し、.tfvars やVCSには置かないのが原則です。プロバイダ認証に使う環境変数（例: AWS_ACCESS_KEY_ID など）も Sensitive 指定にします。

• 同名の変数が Variable Set とワークスペース両方にある場合、ワークスペースの値が優先。
• Terraform 変数と環境変数は別系統。プロバイダ認証は環境変数、構成パラメータは Terraform 変数に分離。
• 計画差分が環境変数で揺れないよう、必要な環境変数はすべてワークスペース/Variable Set に明示。

ガードレールと統合: RBAC、ポリシー、Run Tasks

Terraform Cloud はチーム/ユーザ権限でワークスペース操作を制御できます。Plan の閲覧は可だが Apply は不可といった粒度で分け、誤操作を抑制します。

ポリシー（Sentinel）や Run Tasks（セキュリティ/コストチェック連携）を挟むことで、apply 前に組織の基準を自動検証できます。

• State のロック・バージョニングはサービス側で自動。手動ロールバックも可能。
• キュー/承認フローにより、並行変更やレビュー抜けを防止。
• Cost Estimation でコストインパクトを見える化（対応プロバイダに限る）。

認証・実行フローとトラブルシュート

CLI 駆動では terraform login で作成される ~/.terraform.d/credentials.tfrc.json のトークンが利用されます。ワークスペースで設定した Terraform バージョンと実行モードに従い、計画と適用はリモートで行われ、ログはストリーム表示されます。

よくある失敗は、ワークスペース名の不一致、認証トークン不備、プロバイダ認証環境変数の未設定、実行バージョン差による構文エラーです。まず init の出力、Remote Runs のジョブログ、Variables 画面を確認すると切り分けが速いです。

• 401/403: terraform login 実施・トークン有効性を確認。TFE は hostname の指定漏れに注意。
• 404: workspaces.name のタイポ/存在確認。権限不足でも不可視に見えることがある。
• プロバイダ認証: 環境変数をワークスペース/Variable Set に登録し、Sensitive 指定。

CLI 駆動の実行フロー（Terraform Cloud バックエンド）

 [Dev Laptop]
      |
      | terraform plan/apply (CLI submits run)
      v
 [Terraform Cloud Workspace]
      |  (remote plan/apply, state lock/versioning)
      v
 [Providers/Cloud APIs]
      |
      v
 [Managed Resources]

 State path: Managed in Terraform Cloud (per workspace)
 Logs/Policies: Stored/enforced in Terraform Cloud

問題で確認

よくある質問