Terraform GCS バックエンド徹底ガイド: GCP での遠隔状態管理

Terraform の状態ファイルはチーム開発ではリモート保管が前提です。GCP 環境なら、GCS バケットをバックエンドにするのがもっともシンプルで運用しやすい選択肢です。

本記事では、GCS バックエンドの基本、セキュリティ設計、初期化と移行、認証と CI/CD、運用とトラブル対応、試験対策チェックリストまでを実務目線で解説します。

GCS バックエンドの概要

Terraform の GCS バックエンドは、状態ファイルを Google Cloud Storage に保管し、チームでの同時編集をロックで防ぎます。GCS のオブジェクト版管理と強整合性により、安全な読み書きが可能です。

バックエンド自体は単純で、必要なのはバケット名、任意のプレフィックス、そして認証だけ。復旧性を高めるためにバケットのオブジェクトバージョニングを必ず有効化しましょう。

• 状態ロック: GCS バックエンドはロックをサポート。競合更新を防止
• 復旧性: GCS のオブジェクトバージョニングでロールバックが容易
• 暗号化: バケット側のデフォルト暗号化（CMEK 含む）に従う。バックエンドでKMSキーを直接指定するオプションはない
• 認証: ADC（Application Default Credentials）推奨。必要に応じてサービスアカウント鍵ファイルも可
• 注意: backend ブロックでは変数や参照は使えない。静的設定または -backend-config で注入

GCS バックエンドのデータフロー（ロック含む）

最小の backend 設定例（静的定義）

terraform {
  backend "gcs" {
    bucket = "my-tfstate-bucket"
    prefix = "envs/prod"
    # credentials は省略可（ADC を利用）。鍵ファイルを使うなら以下：
    # credentials = "/secure/path/sa-key.json"
  }
}

設計とセキュリティ設計

状態は最重要機密のひとつです。バケット設計は環境・プロジェクト境界に沿わせ、アクセス境界を明確に分離します。一般的には環境ごと（prod/stg/dev）にバケットを分け、内部で prefix と workspace を使ってディレクトリ風に整理します。

セキュリティはバケット設定で担保します。Uniform bucket-level access を有効化し、Public Access Prevention を有効化。オブジェクトバージョニングとデフォルト CMEK を設定して復旧性と暗号化を両立します。IAM は最小権限で、Terraform 実行サービスアカウントにオブジェクトの読み書きとロック用の作成/削除ができるロールを付与します。

• 命名と階層: バケット my-org-tfstate-prod、prefix は team/app 単位（例: team1/appA）
• Uniform bucket-level access: 有効化して ACL を無効化し IAM に統一
• Public Access Prevention: enforced を推奨
• オブジェクトバージョニング: on（誤更新からの復旧に必須）
• 暗号化: バケットにデフォルト CMEK（Cloud KMS）を設定
• IAM 最小権限: storage.objects.get/list/create/delete、buckets.get

バケットのベース設定（例: gsutil / gcloud）

# バケット作成（リージョンはチームの実行場所に近いものを）
gsutil mb -p ${PROJECT_ID} -l ${REGION} gs://${BUCKET}

# Uniform bucket-level access を有効化
gsutil uniformbucketlevelaccess set on gs://${BUCKET}

# Public Access Prevention を有効化
gcloud storage buckets update gs://${BUCKET} --public-access-prevention

# オブジェクトバージョニングを有効化
gsutil versioning set on gs://${BUCKET}

# デフォルト CMEK を設定（事前に KMS キーを用意しておく）
# projects/PRJ/locations/LOC/keyRings/RING/cryptoKeys/KEY を指定
gcloud storage buckets update gs://${BUCKET} \
  --default-encryption-key=${KMS_KEY_RESOURCE}

# IAM 付与（例: 実行 SA にオブジェクト管理権限を付与）
gsutil iam ch serviceAccount:${TF_SA}:roles/storage.objectAdmin gs://${BUCKET}

実装と初期化（移行を含む）

backend ブロックは Terraform の構文上、変数や参照を使えません。値の差し替えは terraform init の -backend-config で行います。部分的にコードへハードコードし、機密や環境差分のみ -backend-config で注入するのが現実的です。

既存のローカル状態からの移行は terraform init -migrate-state で安全に実施できます。初回 init 時、既存 state があればコピー確認のプロンプトが出ます。

• backend の静的性: 変数/locals/モジュール参照は不可
• 環境差分は -backend-config=... で注入（CLI あるいはファイル）
• 状態移行は terraform init -migrate-state を使用
• workspace ごとに state ファイルは prefix 配下に分割保存される

backend の部分定義と初期化コマンド例

# main.tf（部分的に固定）
terraform {
  backend "gcs" {
    bucket = "my-tfstate-bucket"
    prefix = "team1/appA"
    # credentials は CLI 側で渡す想定（ADC 利用なら不要）
  }
}

# CLI で環境差分を注入して初期化（ADC を使わない場合の例）
terraform init \
  -backend-config="credentials=/secure/path/sa-key.json"

# 既存ローカル state からの移行
terraform init -migrate-state

# backend.hcl を使う場合（CI 向け）
# backend.hcl
# bucket = "my-tfstate-bucket"
# prefix = "team1/appA"
# credentials = "/secure/path/sa-key.json"
terraform init -backend-config=backend.hcl

認証と CI/CD（ADC と鍵管理）

推奨は ADC（Application Default Credentials）。ローカルでは gcloud auth application-default login、GCE/Cloud Run/Cloud Build では実行サービスアカウントに必要最小権限を付与すれば、backend の credentials を省略できます。

CI/CD で鍵ファイルを埋め込むのは避け、Workload Identity Federation もしくはサービスアカウントの直接実行を用います。やむを得ず鍵ファイルを使う場合は、保管を Secret Manager 等で行いローテーション計画を用意します。

• ADC 優先: backend で credentials を省略し、環境側で認証を解決
• サービスアカウントは最小権限付与（objects.* と buckets.get）
• CI では Workload Identity を利用し鍵レス運用を志向
• 鍵を使う場合は -backend-config=credentials=... で注入、リポジトリ直置きは避ける

ローカル/CI での代表的な認証例

# ローカル（ADC）
# ブラウザで認証し ADC を設定
gcloud auth application-default login
# credentials を省略して init
terraform init

# サービスアカウント鍵ファイルを使う場合（非推奨だが例示）
export GOOGLE_APPLICATION_CREDENTIALS=/secure/path/sa-key.json
terraform init -backend-config="credentials=${GOOGLE_APPLICATION_CREDENTIALS}"

# Cloud Build（サービスアカウントに権限付与済み / ADC 利用）
# cloudbuild.yaml のステップ内でそのまま実行可能
- name: hashicorp/terraform:light
  entrypoint: bash
  args:
    - -c
    - |
      terraform init -backend-config=backend.hcl
      terraform plan -input=false

運用とトラブルシュート

ロックは通常自動で解放されますが、プロセス異常終了で残ることがあります。エラーにはロック ID が表示されるため、正当性を確認のうえ force-unlock を実行します。

誤更新時は GCS のオブジェクトバージョニングから過去版を取得して復旧可能です。直接上書きせず、別名へ退避してから terraform state push/pull を検討しましょう（push は通常無効化されているため、復旧は慎重に）。

• 403/404 エラー: SA の roles/storage.objectAdmin（または最小権限）と buckets.get を確認
• ロック競合: 並列実行を避け、CI ではジョブ直列化も検討
• 復旧手順: 古い世代を別キー名へコピーしてから差分確認
• リージョン設計: 低レイテンシなリージョン/マルチリージョンを選択

ロック解除とバージョン復旧の例

# ロック解除（エラーメッセージにある ID を使用）
terraform force-unlock 12345678-90ab-cdef-1234-567890abcdef

# 既存 state の取得
terraform state pull > current.tfstate

# オブジェクトの全バージョンを確認（-a オプション）
gsutil ls -a gs://${BUCKET}/${PREFIX}/default.tfstate

# 特定世代(#NUM)を別名へコピーして比較
gsutil cp gs://${BUCKET}/${PREFIX}/default.tfstate#NUM ./recovered.tfstate

# 差分を目視確認後、慎重に復旧手順を選択（例: 手動で必要エントリを移植）

試験対策チェックリスト（Associate / Pro）

出題はバックエンドの不変性、ロック、復旧、認証の基本に集中します。設計選択肢問題では、バージョニングと最小権限、鍵レス運用（ADC/Workload Identity）を選べるかがポイントです。

移行や再初期化フラグの正誤（-migrate-state と -reconfigure）、backend で変数が使えないこと、workspaces と prefix の関係は頻出です。

• backend ブロックは静的。変数/参照は不可
• GCS バックエンドはロックをサポート。DynamoDB は S3 の話
• 復旧は GCS のバージョニングで。バケット側で有効化が前提
• ADC 優先、鍵ファイルは例外的対応。CI は Workload Identity が望ましい
• 移行は terraform init -migrate-state、設定差し替えは -reconfigure
• workspace ごとに state は分割保存（prefix/workspace 組み合わせ）

再初期化と backend 構成差し替え（試験頻出）

# backend 設定を変更した場合（例: prefix 変更）は再初期化を明示
terraform init -reconfigure -backend-config=backend.hcl

# 既存ローカル state を GCS に移行
terraform init -migrate-state

問題で確認

よくある質問