Terraformで環境ごとにstateの保管先を切り替える設計｜部分設定ファイルと環境変数によるinit時の分岐

この記事のポイント

・-backend-config fileはinit時に部分設定ファイルでbackendの向き先を切り替える仕組み
・backend.tfはtype宣言のみの空定義、バケット名等の実値は環境別.hclに分離する
・TF_CLI_ARGS_initで-backend-configを環境変数化するとCIパイプラインと連携しやすい
・initを再実行する時は-reconfigureを付けないと前回のbackend情報が残り失敗する

# backend.tf（従来の直書き形式 — 環境ごとに書き換えが必要で管理しにくい）
terraform {
  backend "s3" {
    bucket = "myapp-dev-tfstate"
    key    = "env/dev/terraform.tfstate"
    region = "ap-northeast-1"
  }
}

# backend.tf（部分定義 — 環境別の値は外から -backend-config で渡す）
terraform {
  backend "s3" {}
}

project/
├── backend.tf          # 型のみ（s3・azurerm等）
├── main.tf
├── variables.tf
└── envs/
    ├── dev.hcl         # dev環境のbackend実値
    ├── stg.hcl         # stg環境のbackend実値
    └── prod.hcl        # prod環境のbackend実値

# envs/dev.hcl
bucket = "myapp-dev-tfstate"
key    = "env/dev/terraform.tfstate"
region = "ap-northeast-1"

# envs/stg.hcl
bucket = "myapp-stg-tfstate"
key    = "env/stg/terraform.tfstate"
region = "ap-northeast-1"

# envs/prod.hcl
bucket = "myapp-prod-tfstate"
key    = "env/prod/terraform.tfstate"
region = "ap-northeast-1"

# dev環境でinitする場合
$ terraform init -backend-config=envs/dev.hcl

Initializing the backend...

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

Initializing provider plugins...
- Finding hashicorp/aws versions matching "~> 5.0"...
- Installing hashicorp/aws v5.65.0...
- Installed hashicorp/aws v5.65.0 (signed by HashiCorp)

Terraform has been successfully initialized!

# prod環境でinitする場合（別端末・別CIジョブ等）
$ terraform init -backend-config=envs/prod.hcl

Initializing the backend...

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

$ cat .terraform/terraform.tfstate
{
  "version": 3,
  "serial": 1,
  "lineage": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "backend": {
    "type": "s3",
    "config": {
      "bucket": "myapp-dev-tfstate",
      "key": "env/dev/terraform.tfstate",
      "region": "ap-northeast-1"
    },
    "hash": 123456789
  }
}

# GitHub Actionsでの例（envブロックで環境に応じて切り替える）
env:
  TF_CLI_ARGS_init: "-backend-config=envs/dev.hcl"

steps:
  - run: terraform init   # 上記 env が自動的に適用される

# KEY=VALUE形式でbackend値を直接渡す例（ファイルなしで渡す方法）
$ terraform init \
  -backend-config="bucket=myapp-prod-tfstate" \
  -backend-config="key=env/prod/terraform.tfstate" \
  -backend-config="region=ap-northeast-1"

$ terraform init -backend-config=envs/prod.hcl

Error: Backend configuration changed

A change in the backend configuration has been detected, which may require
migrating existing state.

If you wish to attempt automatic migration of the state, use "terraform init -migrate-state".
If you wish to store the current configuration with no changes to the state,
use "terraform init -reconfigure".

# -reconfigureで再初期化（stateは移行しない）
$ terraform init -reconfigure -backend-config=envs/prod.hcl

Initializing the backend...

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

Terraform has been successfully initialized!

$ terraform init

Initializing the backend...
bucket
  The name of the S3 bucket.

  Enter a value:

# .gitignore
.terraform/
*.tfstate
*.tfstate.backup
# .terraform.lock.hcl はチームの合意次第でコミットするか決める
# （プロバイダーバージョン固定のためコミット推奨）