Terraformのbackendブロックはinit時にしか評価されない｜s3・gcs・httpで必須キーと認証情報の渡し方が変わる仕組み

この記事のポイント

・backendブロックはterraform init時にしか評価されない（planでは読まれない）
・backendブロックで変数は使えない。-backend-configで外から渡す
・s3はbucket/key/region、gcsはbucket、httpはaddressが必須キー
・認証情報はbackendに書かず環境変数かIAMロールで渡すのが標準

# backendブロックを変更した後は必ずinitを再実行する
$ terraform init

Initializing the backend...

Do you want to copy existing state to the new backend?
  Pre-existing state was found while migrating the previous "s3" backend to the
  newly configured "gcs" backend. No existing state was found in the newly
  configured "gcs" backend. Do you want to copy this state to the new backend?
  Enter "yes" to copy and "no" to start with an empty state.

  Enter a value: yes

# NG: backendブロックでvar.xxxを使おうとした場合
terraform {
  backend "s3" {
    bucket = var.state_bucket   # これはエラーになる
    key    = "prod/terraform.tfstate"
    region = var.aws_region     # これもエラーになる
  }
}

$ terraform init
╷
│ Error: Variables may not be used here
│
│   on main.tf line 3, in terraform:
│    3:     bucket = var.state_bucket
│
│ Variables may not be used here.
╵

# -backend-configで環境ごとにbucketとkeyを切り替える例
$ terraform init \
  -backend-config="bucket=mycompany-tfstate-prod" \
  -backend-config="key=prod/terraform.tfstate" \
  -backend-config="region=ap-northeast-1"

# GitHub Actionsでの例（リポジトリ変数から値を展開）
- name: Terraform Init
  run: |
    terraform init \
      -backend-config="bucket=$TF_STATE_BUCKET" \
      -backend-config="key=$TF_STATE_KEY" \
      -backend-config="region=$AWS_REGION"
  env:
    TF_STATE_BUCKET: ${{ vars.TF_STATE_BUCKET }}
    TF_STATE_KEY: ${{ vars.TF_STATE_KEY }}
    AWS_REGION: ${{ vars.AWS_REGION }}

# backend.tf - 型だけを宣言。必須キーは書かない
terraform {
  backend "s3" {}
}

# backend-prod.tfvars - 値だけを別ファイルに切り出す
bucket         = "mycompany-tfstate-prod"
key            = "prod/terraform.tfstate"
region         = "ap-northeast-1"
dynamodb_table = "terraform-lock-prod"
encrypt        = true

# initでファイルごと渡す
$ terraform init -backend-config=backend-prod.tfvars

terraform {
  backend "s3" {
    bucket         = "mycompany-tfstate"         # 必須: S3バケット名
    key            = "prod/ec2/terraform.tfstate" # 必須: バケット内のパス
    region         = "ap-northeast-1"             # 必須: バケットのリージョン
    dynamodb_table = "terraform-lock"             # 推奨: stateロック用
    encrypt        = true                          # 推奨: サーバーサイド暗号化
  }
}

# ローカル開発: 環境変数で渡す
$ export AWS_ACCESS_KEY_ID="AKIA..."
$ export AWS_SECRET_ACCESS_KEY="..."
$ export AWS_DEFAULT_REGION="ap-northeast-1"
$ terraform init

Initializing the backend...

Successfully configured the backend "s3"! Terraform will automatically
use this backend unless the backend configuration changes.

# GitHub Actions: aws-actions/configure-aws-credentialsでIAMロールを引き受ける
- uses: aws-actions/configure-aws-credentials@v4
  with:
    role-to-assume: arn:aws:iam::123456789012:role/terraform-state-role
    aws-region: ap-northeast-1

terraform {
  backend "gcs" {
    bucket = "mycompany-tfstate"    # 必須: GCSバケット名
    prefix = "prod/terraform/state" # 推奨: バケット内のパスプレフィックス
  }
}

# ローカル開発: gcloudでADCを設定する
$ gcloud auth application-default login

Credentials saved to file: [/home/user/.config/gcloud/application_default_credentials.json]

# または: サービスアカウントキーをJSONファイルで指定する場合
$ export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account.json"
$ terraform init

# CI/CD: サービスアカウントのJSONをGOOGLE_CREDENTIALSに直接渡す場合
$ export GOOGLE_CREDENTIALS='{ "type": "service_account", "project_id": "myproject", ... }'
$ terraform init

terraform {
  backend "http" {
    address        = "https://gitlab.example.com/api/v4/projects/42/terraform/state/prod"
    lock_address   = "https://gitlab.example.com/api/v4/projects/42/terraform/state/prod/lock"
    unlock_address = "https://gitlab.example.com/api/v4/projects/42/terraform/state/prod/lock"
    lock_method    = "POST"    # デフォルト: LOCK
    unlock_method  = "DELETE"  # デフォルト: UNLOCK
  }
}

# TF_HTTP_*環境変数で渡す（backendブロックには書かない）
$ export TF_HTTP_USERNAME="myuser"
$ export TF_HTTP_PASSWORD="mytoken"  # GitLabならPersonal Access Token
$ terraform init

# GitLab CI/CDの場合: CI変数を展開して渡す
$ export TF_HTTP_ADDRESS="${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/terraform/state/${TF_STATE_NAME}"
$ export TF_HTTP_LOCK_ADDRESS="${TF_HTTP_ADDRESS}/lock"
$ export TF_HTTP_UNLOCK_ADDRESS="${TF_HTTP_ADDRESS}/lock"
$ export TF_HTTP_USERNAME="gitlab-ci-token"
$ export TF_HTTP_PASSWORD="${CI_JOB_TOKEN}"
$ terraform init

$ terraform plan
╷
│ Error: Backend initialization required, please run "terraform init"
│
│ Reason: Backend configuration changed for "s3"
╵

# 対処: terraform initを再実行する
$ terraform init