Terraformモジュール設計パターンとState管理運用プレイブック 2026

# 標準モジュールディレクトリ構造
modules/
  networking/
    main.tf          # VPC、Subnet、Route Tableなどコアリソース
    variables.tf     # 入力変数定義（CIDR、AZ、タグなど）
    outputs.tf       # 出力値：VPC ID、Subnet IDなど
    versions.tf      # required_providers、required_version
    README.md        # モジュール使用方法のドキュメント
    tests/           # terraform testまたはTerratestコード
      networking_test.go
  compute/
    main.tf
    variables.tf
    outputs.tf
    versions.tf
    iam.tf           # コンピュート専用IAM Role/Policy
    userdata.tf      # Launch Template、User Data
  database/
    main.tf
    variables.tf
    outputs.tf
    versions.tf
    security_group.tf  # DB専用Security Group

# variables.tf - 変数バリデーションルールの例
variable "environment" {
  type        = string
  description = "デプロイ環境（dev、staging、prod）"

  validation {
    condition     = contains(["dev", "staging", "prod"], var.environment)
    error_message = "environmentはdev、staging、prodのいずれかでなければなりません。"
  }
}

variable "vpc_cidr" {
  type        = string
  description = "VPC CIDRブロック"

  validation {
    condition     = can(cidrhost(var.vpc_cidr, 0))
    error_message = "有効なCIDR形式でなければなりません（例：10.0.0.0/16）。"
  }

  validation {
    condition     = tonumber(split("/", var.vpc_cidr)[1]) >= 16 && tonumber(split("/", var.vpc_cidr)[1]) <= 24
    error_message = "VPC CIDRのプレフィックス長は/16から/24の間でなければなりません。"
  }
}

variable "instance_type" {
  type        = string
  default     = "t3.medium"
  description = "EC2インスタンスタイプ"

  validation {
    condition     = can(regex("^(t3|t3a|m5|m6i|c5|c6i)\\.", var.instance_type))
    error_message = "承認されたインスタンスファミリーのみ使用可能です：t3、t3a、m5、m6i、c5、c6i。"
  }
}

# environments/prod/main.tf - Root Moduleの例
module "web_service" {
  source = "../../compositions/web-service"

  environment    = "prod"
  vpc_cidr       = "10.1.0.0/16"
  instance_type  = "m6i.xlarge"
  min_size       = 3
  max_size       = 10
  db_instance_class = "db.r6g.xlarge"
  multi_az       = true

  tags = {
    Team        = "platform"
    CostCenter  = "engineering"
    ManagedBy   = "terraform"
  }
}

# compositions/web-service/main.tf - Composition Moduleの例
module "networking" {
  source = "../../modules/networking"

  vpc_cidr    = var.vpc_cidr
  environment = var.environment
  tags        = var.tags
}

module "compute" {
  source = "../../modules/compute"

  vpc_id         = module.networking.vpc_id
  subnet_ids     = module.networking.private_subnet_ids
  instance_type  = var.instance_type
  min_size       = var.min_size
  max_size       = var.max_size
  environment    = var.environment
  tags           = var.tags
}

module "database" {
  source = "../../modules/database"

  vpc_id            = module.networking.vpc_id
  subnet_ids        = module.networking.database_subnet_ids
  instance_class    = var.db_instance_class
  multi_az          = var.multi_az
  security_group_id = module.compute.app_security_group_id
  environment       = var.environment
  tags              = var.tags
}

# Terraform 1.10+ Ephemeral Resourceの例
ephemeral "aws_secretsmanager_secret_version" "db_password" {
  secret_id = "prod/db/master-password"
}

resource "aws_db_instance" "main" {
  identifier     = "prod-primary"
  engine         = "postgres"
  engine_version = "16.2"
  instance_class = "db.r6g.xlarge"

  # write_only属性 - Stateに保存されない（Terraform 1.11+）
  password_wo         = ephemeral.aws_secretsmanager_secret_version.db_password.secret_string
  password_wo_version = 1
}

# Directoryベースの環境分離構造
infrastructure/
  modules/          # 再利用モジュール
  environments/
    dev/
      main.tf       # module source = "../../modules/..."
      backend.tf    # S3 key = "dev/terraform.tfstate"
      terraform.tfvars
    staging/
      main.tf
      backend.tf    # S3 key = "staging/terraform.tfstate"
      terraform.tfvars
    prod/
      main.tf
      backend.tf    # S3 key = "prod/terraform.tfstate"
      terraform.tfvars

# bootstrap/main.tf - Stateバックエンドインフラのブートストラップ
terraform {
  required_version = ">= 1.9.0"
}

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

resource "aws_s3_bucket" "terraform_state" {
  bucket = "mycompany-terraform-state-prod"

  lifecycle {
    prevent_destroy = true
  }

  tags = {
    Name      = "Terraform State"
    ManagedBy = "bootstrap"
  }
}

resource "aws_s3_bucket_versioning" "terraform_state" {
  bucket = aws_s3_bucket.terraform_state.id

  versioning_configuration {
    status = "Enabled"
  }
}

resource "aws_s3_bucket_server_side_encryption_configuration" "terraform_state" {
  bucket = aws_s3_bucket.terraform_state.id

  rule {
    apply_server_side_encryption_by_default {
      sse_algorithm     = "aws:kms"
      kms_master_key_id = aws_kms_key.terraform_state.arn
    }
    bucket_key_enabled = true
  }
}

resource "aws_s3_bucket_public_access_block" "terraform_state" {
  bucket = aws_s3_bucket.terraform_state.id

  block_public_acls       = true
  block_public_policy     = true
  ignore_public_acls      = true
  restrict_public_buckets = true
}

resource "aws_kms_key" "terraform_state" {
  description             = "KMS key for Terraform state encryption"
  deletion_window_in_days = 30
  enable_key_rotation     = true
}

resource "aws_dynamodb_table" "terraform_lock" {
  name         = "terraform-state-lock"
  billing_mode = "PAY_PER_REQUEST"
  hash_key     = "LockID"

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

  tags = {
    Name      = "Terraform State Lock"
    ManagedBy = "bootstrap"
  }
}

# 利用側のbackend.tf
# terraform {
#   backend "s3" {
#     bucket         = "mycompany-terraform-state-prod"
#     key            = "prod/networking/terraform.tfstate"
#     region         = "ap-northeast-2"
#     encrypt        = true
#     kms_key_id     = "arn:aws:kms:ap-northeast-2:123456789:key/xxx"
#     dynamodb_table = "terraform-state-lock"
#   }
# }

# ロック競合時に表示されるメッセージ
Error: Error acquiring the state lock
Lock Info:
  ID:        a1b2c3d4-e5f6-7890-abcd-ef1234567890
  Path:      s3://mycompany-terraform-state-prod/prod/terraform.tfstate
  Operation: OperationTypeApply
  Who:       engineer@workstation
  Version:   1.11.0
  Created:   2026-03-04 09:15:23.456789 +0000 UTC

# 強制ロック解除（緊急時のみ使用）
terraform force-unlock a1b2c3d4-e5f6-7890-abcd-ef1234567890

# 強制ロック解除前に必ず確認すべき事項
# 1. 該当Lock IDの操作が本当に終了したか確認
# 2. 他のチームメンバーに現在applyを実行中か確認（Slackなど）
# 3. DynamoDBテーブルで該当Lock項目を直接確認
aws dynamodb get-item \
  --table-name terraform-state-lock \
  --key '{"LockID": {"S": "mycompany-terraform-state-prod/prod/terraform.tfstate"}}'

# リソース名変更：aws_instance.web -> aws_instance.web_server
moved {
  from = aws_instance.web
  to   = aws_instance.web_server
}

resource "aws_instance" "web_server" {
  ami           = "ami-0c55b159cbfafe1f0"
  instance_type = "t3.medium"
}

# モジュールへの移動：aws_vpc.main -> module.networking.aws_vpc.main
moved {
  from = aws_vpc.main
  to   = module.networking.aws_vpc.main
}

# モジュール名の変更
moved {
  from = module.old_networking
  to   = module.networking
}

# for_eachキーの変更
moved {
  from = aws_subnet.private["az-a"]
  to   = aws_subnet.private["ap-northeast-2a"]
}

# importブロック（Terraform 1.5+） - 宣言的インポート
import {
  to = aws_s3_bucket.existing_logs
  id = "my-existing-log-bucket"
}

resource "aws_s3_bucket" "existing_logs" {
  bucket = "my-existing-log-bucket"
}

# terraform planで差分を事前確認
# terraform applyでStateに反映

# 1. 現在のStateをバックアップ
cp terraform.tfstate terraform.tfstate.backup.$(date +%Y%m%d_%H%M%S)

# 2. backend.tfファイルを作成/修正
cat > backend.tf << 'HEREDOC'
terraform {
  backend "s3" {
    bucket         = "mycompany-terraform-state"
    key            = "services/web/terraform.tfstate"
    region         = "ap-northeast-2"
    encrypt        = true
    dynamodb_table = "terraform-state-lock"
  }
}
HEREDOC

# 3. terraform initでマイグレーションを実行
terraform init -migrate-state

# 4. マイグレーションの確認
terraform state list

# 5. リモートStateの検証
terraform plan  # No changes expected

# 6. ローカルStateファイルのクリーンアップ（検証完了後）
rm terraform.tfstate terraform.tfstate.backup

// test/networking_test.go
package test

import (
	"testing"

	"github.com/gruntwork-io/terratest/modules/aws"
	"github.com/gruntwork-io/terratest/modules/terraform"
	"github.com/stretchr/testify/assert"
)

func TestNetworkingModule(t *testing.T) {
	t.Parallel()

	awsRegion := "ap-northeast-2"

	terraformOptions := &terraform.Options{
		TerraformDir: "../modules/networking",
		Vars: map[string]interface{}{
			"environment": "test",
			"vpc_cidr":    "10.99.0.0/16",
		},
		EnvVars: map[string]string{
			"AWS_DEFAULT_REGION": awsRegion,
		},
	}

	// テスト終了時にリソースをクリーンアップ
	defer terraform.Destroy(t, terraformOptions)

	// インフラをデプロイ
	terraform.InitAndApply(t, terraformOptions)

	// 出力値を検証
	vpcID := terraform.Output(t, terraformOptions, "vpc_id")
	assert.NotEmpty(t, vpcID)

	// AWS APIで実際のリソースを検証
	vpc := aws.GetVpcById(t, vpcID, awsRegion)
	assert.Equal(t, "10.99.0.0/16", vpc.CidrBlock)

	// Subnet数を検証
	privateSubnetIDs := terraform.OutputList(t, terraformOptions, "private_subnet_ids")
	assert.Equal(t, 3, len(privateSubnetIDs))

	// タグを検証
	actualTags := aws.GetTagsForVpc(t, vpcID, awsRegion)
	assert.Equal(t, "test", actualTags["Environment"])
}

# tests/networking.tftest.hcl
provider "aws" {
  region = "ap-northeast-2"
}

variables {
  environment = "test"
  vpc_cidr    = "10.99.0.0/16"
}

run "vpc_creation" {
  command = plan

  assert {
    condition     = aws_vpc.main.cidr_block == "10.99.0.0/16"
    error_message = "VPC CIDRブロックが期待値と異なります。"
  }

  assert {
    condition     = aws_vpc.main.tags["Environment"] == "test"
    error_message = "Environmentタグが正しくありません。"
  }
}

run "subnet_count" {
  command = plan

  assert {
    condition     = length(aws_subnet.private) == 3
    error_message = "Private Subnetは3つでなければなりません。"
  }
}

# 1. 現在のLock状態を確認
aws dynamodb scan \
  --table-name terraform-state-lock \
  --filter-expression "attribute_exists(LockID)"

# 2. Lock所有者を確認後、安全に解除
terraform force-unlock <LOCK_ID>

# 注意：force-unlockは他のapplyが実行中でないことを確認してから使用すること

# ドリフトの検出
terraform plan -detailed-exitcode
# Exit code 0: 変更なし
# Exit code 1: エラー
# Exit code 2: 変更あり（ドリフト検出）

# 特定リソースのState更新（実際のインフラに基づいてStateを更新）
terraform apply -refresh-only -target=aws_instance.web_server

# StateからリソースをRemove（実際のインフラは維持）
terraform state rm aws_instance.legacy_server

# S3でのStateファイル過去バージョン一覧の確認
aws s3api list-object-versions \
  --bucket mycompany-terraform-state-prod \
  --prefix prod/terraform.tfstate

# 特定バージョンへの復旧
aws s3api get-object \
  --bucket mycompany-terraform-state-prod \
  --key prod/terraform.tfstate \
  --version-id "abc123def456" \
  terraform.tfstate.recovered

# 復旧したStateの検証
terraform show terraform.tfstate.recovered

# Stateファイルの置き換え（DynamoDB Lock確認後）
aws s3 cp terraform.tfstate.recovered \
  s3://mycompany-terraform-state-prod/prod/terraform.tfstate