Terraformのtfstate管理とS3バックエンド設定｜チーム運用で壊さないための基礎

この記事のポイント

・tfstateはTerraformがインフラの「現在の状態」を記録するJSONファイル
・S3バックエンド設定でtfstateをチーム共有・バージョン管理できる
・DynamoDB State Lockingで同時実行によるstate破損を防ぐ
・state破損・ロック残留はterraform force-unlockで対処できる

# terraform.tfstate の内容（抜粋）
{
  "version": 4,
  "terraform_version": "1.8.0",
  "serial": 12,
  "lineage": "a1b2c3d4-...",
  "outputs": {},
  "resources": [
    {
      "mode": "managed",
      "type": "aws_instance",
      "name": "web",
      "provider": "provider[\"registry.terraform.io/hashicorp/aws\"]",
      "instances": [
        {
          "attributes": {
            "id": "i-0123456789abcdef0",
            "ami": "ami-0c02fb55956c7d316",
            "instance_type": "t3.micro",
            ...
          }
        }
      ]
    }
  ]
}

# .gitignore に必ず追加すること
# tfstateはローカル管理の場合でもgitに含めない
*.tfstate
*.tfstate.*
.terraform/
.terraform.lock.hcl  # こちらはコミット推奨（プロバイダーバージョン固定のため）

# bootstrap/main.tf
# このファイルだけはローカルbackendで実行し、S3とDynamoDBを作成する

terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.0"
    }
  }
}

provider "aws" {
  region = "ap-northeast-1"
}

# tfstate保存用S3バケット
resource "aws_s3_bucket" "tfstate" {
  bucket = "mycompany-terraform-tfstate"

  lifecycle {
    prevent_destroy = true  # 誤削除防止
  }
}

# バージョニング有効化（tfstateの変更履歴を保持）
resource "aws_s3_bucket_versioning" "tfstate" {
  bucket = aws_s3_bucket.tfstate.id
  versioning_configuration {
    status = "Enabled"
  }
}

# 暗号化設定（SSE-S3）
resource "aws_s3_bucket_server_side_encryption_configuration" "tfstate" {
  bucket = aws_s3_bucket.tfstate.id
  rule {
    apply_server_side_encryption_by_default {
      sse_algorithm = "AES256"
    }
  }
}

# パブリックアクセスを完全ブロック
resource "aws_s3_bucket_public_access_block" "tfstate" {
  bucket                  = aws_s3_bucket.tfstate.id
  block_public_acls       = true
  block_public_policy     = true
  ignore_public_acls      = true
  restrict_public_buckets = true
}

# State Locking用DynamoDBテーブル
resource "aws_dynamodb_table" "tfstate_lock" {
  name         = "terraform-state-lock"
  billing_mode = "PAY_PER_REQUEST"
  hash_key     = "LockID"

  attribute {
    name = "LockID"
    type = "S"
  }
}

# bootstrapディレクトリで実行
$ cd bootstrap
$ terraform init
$ terraform apply

# 実行結果（抜粋）
aws_s3_bucket.tfstate: Creating...
aws_s3_bucket.tfstate: Creation complete after 2s [id=mycompany-terraform-tfstate]
aws_s3_bucket_versioning.tfstate: Creating...
aws_dynamodb_table.tfstate_lock: Creating...
aws_s3_bucket_versioning.tfstate: Creation complete after 1s
aws_dynamodb_table.tfstate_lock: Creation complete after 5s [id=terraform-state-lock]

Apply complete! Resources: 5 added, 0 changed, 0 destroyed.

# main.tf（または backend.tf として独立させるのが慣習）
terraform {
  required_version = ">= 1.5"

  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.0"
    }
  }

  backend "s3" {
    bucket         = "mycompany-terraform-tfstate"
    key            = "production/terraform.tfstate"  # S3内のパス
    region         = "ap-northeast-1"
    encrypt        = true

    # DynamoDB State Locking
    dynamodb_table = "terraform-state-lock"
  }
}

$ 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 "local" backend to the
  newly configured "s3" backend. No existing state was found in the newly
  configured "s3" backend. Do you want to copy this state to the new "s3" backend?
  Enter "yes" to copy and "no" to start with an empty state.

  Enter a value: yes

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

Initializing provider plugins...
- Reusing previous version of hashicorp/aws from the lock file

Terraform has been successfully initialized!

# BさんがロックされているときにApplyしようとした場合の出力例
$ terraform apply

Acquiring state lock. This may take a few moments...

Error: Error acquiring the state lock

Error message: ConditionalCheckFailedException: The conditional request failed
Lock Info:
  ID:        a1b2c3d4-e5f6-7890-abcd-ef1234567890
  Path:      mycompany-terraform-tfstate/production/terraform.tfstate
  Operation: OperationTypeApply
  Who:       alice@mycompany.com
  Version:   1.8.0
  Created:   2026-06-27 09:00:00.123456 +0000 UTC
  Info:

Terraform acquires a state lock to protect the state from being written
by multiple users at the same time. Please resolve the issue above and try
again. For most commands, you can disable locking with the "-lock=false"
flag, but this is not recommended.

# AWS CLIでDynamoDBのロック状態を確認する
$ aws dynamodb scan \
  --table-name terraform-state-lock \
  --region ap-northeast-1

{
    "Items": [
        {
            "LockID": {
                "S": "mycompany-terraform-tfstate/production/terraform.tfstate"
            },
            "Info": {
                "S": "{\"ID\":\"a1b2c3d4...\",\"Operation\":\"OperationTypeApply\",\"Who\":\"alice@mycompany.com\",\"Version\":\"1.8.0\",\"Created\":\"2026-06-27T09:00:00.123456Z\"}"
            }
        }
    ],
    "Count": 1,
    "ScannedCount": 1
}

# terraform-backend-policy.json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:GetObject",
        "s3:PutObject",
        "s3:DeleteObject",
        "s3:ListBucket"
      ],
      "Resource": [
        "arn:aws:s3:::mycompany-terraform-tfstate",
        "arn:aws:s3:::mycompany-terraform-tfstate/*"
      ]
    },
    {
      "Effect": "Allow",
      "Action": [
        "dynamodb:GetItem",
        "dynamodb:PutItem",
        "dynamodb:DeleteItem"
      ],
      "Resource": "arn:aws:dynamodb:ap-northeast-1:123456789012:table/terraform-state-lock"
    }
  ]
}

# ロック残留の確認（エラーメッセージのIDを使う）
$ terraform force-unlock a1b2c3d4-e5f6-7890-abcd-ef1234567890

Do you really want to force-unlock?
  Terraform will remove the lock on the remote state.
  This will allow local Terraform commands to modify this state, even though it
  may be still be in use. Only 'yes' will be accepted to confirm.

  Enter a value: yes

Terraform state has been successfully unlocked!
The state has been unlocked, and Terraform commands should now be able to
run successfully.

# S3バージョン一覧を確認する
$ aws s3api list-object-versions \
  --bucket mycompany-terraform-tfstate \
  --prefix production/terraform.tfstate \
  --region ap-northeast-1 \
  --query 'Versions[*].{VersionId:VersionId,LastModified:LastModified,IsLatest:IsLatest}' \
  --output table

-----------------------------------------------------------------
| ListObjectVersions                                             |
+----------+-----------+-------------------------------------+---+
|IsLatest  |LastModified              |VersionId              |
+----------+-----------+-------------------------------------+---+
|True      |2026-06-27T09:15:00.000Z  |K3d8Kf2xNpY.rWabcd... |
|False     |2026-06-27T09:00:00.000Z  |2Mf7Jk9qRsT.vXwxyz... |
|False     |2026-06-26T18:00:00.000Z  |1La6Ij8pQrS.uWvwxy... |
+----------+-----------+-------------------------------------+---+

# 特定バージョンのtfstateをダウンロードして確認する
$ aws s3api get-object \
  --bucket mycompany-terraform-tfstate \
  --key production/terraform.tfstate \
  --version-id 2Mf7Jk9qRsT.vXwxyz... \
  --region ap-northeast-1 \
  terraform.tfstate.backup

# 問題がなければそのバージョンを最新に戻す（上書きアップロード）
$ aws s3 cp terraform.tfstate.backup \
  s3://mycompany-terraform-tfstate/production/terraform.tfstate \
  --region ap-northeast-1

# ドリフトの検出（-refresh-onlyオプションで安全に確認）
$ terraform plan -refresh-only

aws_instance.web: Refreshing state... [id=i-0123456789abcdef0]

Note: Objects have changed outside of Terraform

Terraform detected the following changes made outside of Terraform since the
last "terraform apply":

  # aws_instance.web has been changed
  ~ resource "aws_instance" "web" {
        id                    = "i-0123456789abcdef0"
      ~ instance_type         = "t3.micro" -> "t3.small"  # コンソールで変更された
        ...
    }

This is a refresh-only plan, so Terraform will not take any actions to
undo these. If you were expecting these changes then you can apply this plan
to record the updated values in the Terraform state without changing any
remote objects.

# ワークスペースの作成と切り替え
$ terraform workspace new dev
Created and switched to workspace "dev"!

$ terraform workspace new staging
Created and switched to workspace "staging"!

$ terraform workspace list
  default
  dev
* staging  ← 現在のワークスペース

$ terraform workspace select production
Switched to workspace "production".

# workspace名をtfstate pathに自動反映（S3バックエンドの場合）
# デフォルトでは env://production/terraform.tfstate に保存される

# .github/workflows/terraform.yml
name: Terraform

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

permissions:
  contents: read
  id-token: write  # OIDC認証用

jobs:
  terraform:
    runs-on: ubuntu-latest
    environment: production

    steps:
      - uses: actions/checkout@v4

      # OIDC経由でAWSに認証（アクセスキーを使わない安全な方法）
      - name: Configure AWS Credentials
        uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::123456789012:role/GitHubActionsRole
          aws-region: ap-northeast-1

      - uses: hashicorp/setup-terraform@v3
        with:
          terraform_version: "1.8.0"

      - name: Terraform Init
        run: terraform init

      - name: Terraform Format Check
        run: terraform fmt -check

      - name: Terraform Validate
        run: terraform validate

      # PRの場合はPlanのみ（Applyはmainマージ後のみ）
      - name: Terraform Plan
        if: github.event_name == 'pull_request'
        run: terraform plan -no-color
        continue-on-error: true

      - name: Terraform Apply
        if: github.ref == 'refs/heads/main' && github.event_name == 'push'
        run: terraform apply -auto-approve -no-color