TerragruntでTerraformをDRY化する設計入門｜includeとdependencyで環境差分を管理する方法

この記事のポイント

・TerraformのbackendにはHCL変数が使えないため、環境差分が重複しやすい
・Terragruntのincludeブロックで親設定を継承し、backend設定を1箇所に集約できる
・dependencyブロックでVPC→EC2のようなモジュール間outputを安全に参照できる
・run-allコマンドで依存グラフを自動解決しながら複数モジュールを一括実行できる

# NG: backendブロックで変数は使えない
terraform {
  backend "s3" {
    bucket = var.tfstate_bucket  # エラー
    key    = "${var.env}/terraform.tfstate"  # エラー
  }
}

# Terragruntのインストール（v0.67.x）
curl -L https://github.com/gruntwork-io/terragrunt/releases/download/v0.67.4/terragrunt_linux_amd64 \
  -o /usr/local/bin/terragrunt
chmod +x /usr/local/bin/terragrunt
terragrunt --version
# terragrunt version v0.67.4

infra/
├── terragrunt.hcl          # ルートの共通設定（backend・provider）
├── modules/                # 再利用可能なTerraformモジュール
│   ├── vpc/
│   │   ├── main.tf
│   │   ├── variables.tf
│   │   └── outputs.tf
│   └── ec2/
│       ├── main.tf
│       ├── variables.tf
│       └── outputs.tf
└── environments/
    ├── dev/
    │   ├── vpc/
    │   │   └── terragrunt.hcl   # 環境ごとのterragrunt設定
    │   └── ec2/
    │       └── terragrunt.hcl
    ├── stg/
    │   ├── vpc/
    │   │   └── terragrunt.hcl
    │   └── ec2/
    │       └── terragrunt.hcl
    └── prod/
        ├── vpc/
        │   └── terragrunt.hcl
        └── ec2/
            └── terragrunt.hcl

# infra/terragrunt.hcl（ルート共通設定）

locals {
  # ディレクトリ構造からaws_regionを自動検出する場合の例
  aws_region = "ap-northeast-1"
}

generate "provider" {
  path      = "provider.tf"
  if_exists = "overwrite_terragrunt"
  contents  = <

# infra/environments/dev/vpc/terragrunt.hcl

include "root" {
  path = find_in_parent_folders()
}

terraform {
  source = "../../../../modules/vpc"
}

inputs = {
  vpc_cidr    = "10.0.0.0/16"
  environment = "dev"
}

# infra/environments/stg/vpc/terragrunt.hcl

include "root" {
  path = find_in_parent_folders()
}

terraform {
  source = "../../../../modules/vpc"
}

inputs = {
  vpc_cidr    = "10.1.0.0/16"
  environment = "stg"
}

# infra/environments/dev/ec2/terragrunt.hcl

include "root" {
  path = find_in_parent_folders()
}

terraform {
  source = "../../../../modules/ec2"
}

dependency "vpc" {
  config_path = "../vpc"

  # terragrunt plan時（vpc未applyの状態）のフォールバック値
  mock_outputs = {
    vpc_id             = "vpc-00000000"
    private_subnet_ids = ["subnet-00000000"]
  }
  mock_outputs_allowed_terraform_commands = ["validate", "plan"]
}

inputs = {
  vpc_id             = dependency.vpc.outputs.vpc_id
  private_subnet_ids = dependency.vpc.outputs.private_subnet_ids
  instance_type      = "t3.micro"
  environment        = "dev"
}

# planとvalidateのみmock_outputsを許可する設定
mock_outputs_allowed_terraform_commands = ["validate", "plan"]
# applyでmock_outputsを使うとダミーIDがリソースに渡るため危険。applyは除外する

# infra/environments/dev/ec2/terragrunt.hcl

include "root" {
  path = find_in_parent_folders()
}

locals {
  # 環境共通変数をまとめたYAMLファイルを読み込む（任意）
  env_vars = yamldecode(file(find_in_parent_folders("env_vars.yaml")))
  env      = local.env_vars.environment   # "dev"
  region   = local.env_vars.aws_region    # "ap-northeast-1"
}

terraform {
  source = "../../../../modules/ec2"
}

inputs = {
  instance_type = "t3.micro"    # dev環境は小さいインスタンス
  environment   = local.env
  region        = local.region
}

# infra/environments/dev/env_vars.yaml
environment: dev
aws_region: ap-northeast-1

# dev環境全体をplanする
cd infra/environments/dev
terragrunt run-all plan

# 実行ログ例（抜粋）
[terragrunt] INFO  Found 2 modules in total
[terragrunt] INFO  Module environments/dev/vpc has no dependencies
[terragrunt] INFO  Module environments/dev/ec2 depends on environments/dev/vpc
[terragrunt] INFO  Running 'terraform plan' in environments/dev/vpc ...
# ... vpc planの出力 ...
[terragrunt] INFO  Running 'terraform plan' in environments/dev/ec2 ...
# ... ec2 planの出力 ...

# CI/CDでの一括apply（確認プロンプトをスキップ）
TG_NON_INTERACTIVE=true terragrunt run-all apply

# 特定ディレクトリだけをapply（通常のterraformと同様）
cd infra/environments/dev/vpc
terragrunt apply

# 確認コマンド
find . -name "terragrunt.hcl" | sort

# 想定出力（ルートにterragrunt.hclがあることを確認）
./environments/dev/ec2/terragrunt.hcl
./environments/dev/vpc/terragrunt.hcl
./terragrunt.hcl   ← これが見つからない場合は配置ミス

# 修正後の設定
mock_outputs_allowed_terraform_commands = ["validate", "plan"]
# "apply" は絶対に含めない

# クレデンシャル確認
aws sts get-caller-identity
# {
#     "UserId": "AIDA...",
#     "Account": "123456789012",
#     "Arn": "arn:aws:iam::123456789012:user/terraform-ci"
# }

# S3バケットへのアクセス確認
aws s3 ls s3://my-tfstate-bucket