Terraformのディレクトリ構成ベストプラクティス｜environments分割とmodules共通化のリポジトリ設計

この記事のポイント

・単一main.tfはリソースが増えると「全リソースplan」「環境コピー増殖」で必ず破綻する
・environments分割型はdev/stg/prodをディレクトリで分離しtfstateも環境ごとに独立させる
・modules/共通化の基準は「2環境以上で同じ構成を使うリソース群」を抽出することだけ
・tfstateのS3バックエンドはenvironments/dev・stg・prodで必ずkeyパスを分ける

terraform-repo/
├── main.tf          # リソース定義
├── variables.tf     # 入力変数
├── outputs.tf       # 出力値
├── providers.tf     # プロバイダー設定
└── terraform.tfvars # 変数の値

terraform-repo/
├── environments/
│   ├── dev/
│   │   ├── main.tf          # modulesを呼び出すだけ
│   │   ├── variables.tf
│   │   ├── outputs.tf
│   │   ├── terraform.tfvars # dev用の値
│   │   └── backend.tf       # S3バックエンド（devパス）
│   ├── stg/
│   │   ├── main.tf
│   │   ├── variables.tf
│   │   ├── outputs.tf
│   │   ├── terraform.tfvars # stg用の値
│   │   └── backend.tf       # S3バックエンド（stgパス）
│   └── prod/
│       ├── main.tf
│       ├── variables.tf
│       ├── outputs.tf
│       ├── terraform.tfvars # prod用の値
│       └── backend.tf       # S3バックエンド（prodパス）
└── modules/
    ├── vpc/
    │   ├── main.tf
    │   ├── variables.tf
    │   └── outputs.tf
    ├── ec2/
    │   ├── main.tf
    │   ├── variables.tf
    │   └── outputs.tf
    └── rds/
        ├── main.tf
        ├── variables.tf
        └── outputs.tf

terraform-repo/
├── shared/
│   ├── network/   # VPC・サブネット・NATゲートウェイ
│   └── security/  # セキュリティグループ・IAMポリシー
└── products/
    ├── product-a/
    │   ├── environments/
    │   │   ├── dev/
    │   │   └── prod/
    │   └── modules/
    └── product-b/
        ├── environments/
        │   ├── dev/
        │   └── prod/
        └── modules/

# environments/dev/backend.tf
terraform {
  backend "s3" {
    bucket         = "mycompany-terraform-state"
    key            = "environments/dev/terraform.tfstate"
    region         = "ap-northeast-1"
    dynamodb_table = "terraform-state-lock"
    encrypt        = true
  }
}

# environments/prod/backend.tf（keyパスのみ異なる）
terraform {
  backend "s3" {
    bucket         = "mycompany-terraform-state"
    key            = "environments/prod/terraform.tfstate"
    region         = "ap-northeast-1"
    dynamodb_table = "terraform-state-lock"
    encrypt        = true
  }
}

# environments/dev/main.tf
module "vpc" {
  source     = "../../modules/vpc"
  env        = var.env
  vpc_cidr   = var.vpc_cidr
  az_list    = var.az_list
}

module "ec2" {
  source         = "../../modules/ec2"
  env            = var.env
  vpc_id         = module.vpc.vpc_id
  subnet_ids     = module.vpc.private_subnet_ids
  instance_type  = var.instance_type
  ami_id         = var.ami_id
}

# environments/dev/terraform.tfvars
env           = "dev"
vpc_cidr      = "10.0.0.0/16"
az_list       = ["ap-northeast-1a", "ap-northeast-1c"]
instance_type = "t3.micro"
ami_id        = "ami-0abcdef1234567890"

# environments/prod/terraform.tfvars（値だけが異なる）
env           = "prod"
vpc_cidr      = "10.1.0.0/16"
az_list       = ["ap-northeast-1a", "ap-northeast-1c", "ap-northeast-1d"]
instance_type = "t3.large"
ami_id        = "ami-0abcdef9876543210"

modules/
└── vpc/
    ├── main.tf      # VPC・サブネット・IGW・ルートテーブルの定義
    ├── variables.tf # 入力変数（env・cidr・az_list等）
    └── outputs.tf   # 出力値（vpc_id・subnet_ids等を呼び元に公開）

# NG：全環境で同じキーを使っている
terraform {
  backend "s3" {
    bucket = "mycompany-terraform-state"
    key    = "terraform.tfstate"   # 環境名がない
  }
}

# NG：backendブロック内でvar.は使えない
terraform {
  backend "s3" {
    key = "environments/${var.env}/terraform.tfstate"   # エラー
  }
}

# 実行するとこのエラーが出る
Error: Variables not allowed
  on backend.tf line 4, in terraform:
  Variables may not be used here.

# -backend-configで外部ファイルから設定を注入する方法
$ terraform init -backend-config=../../config/dev.backend.hcl

# dev.backend.hcl
bucket = "mycompany-terraform-state"
key    = "environments/dev/terraform.tfstate"
region = "ap-northeast-1"