terragrunt-generator

Terragrunt ジェネレーター

概要

最新のベストプラクティス、命名規則、セキュリティ標準に準拠した、本番環境で利用できる Terragrunt 構成を生成します。生成されたすべての構成は自動的に検証されます。

トリガーフレーズ

ユーザーが次の内容を依頼した場合に、このスキルを使用します。

• 新しい root.hcl、terragrunt.hcl、または terragrunt.stack.hcl
• 複数環境の Terragrunt レイアウト（dev/staging/prod）
• Terragrunt の依存関係の接続（dependency または dependencies ブロック）
• Terragrunt モジュールのソース設定（ローカル、Git、tfr:/// を使った Terraform Registry）
• catalog/units/* 配下でのスタックカタログユニットの生成

対応している Terragrunt 2025 の機能：

• Stacks - terragrunt.stack.hcl を使用したインフラストラクチャのブループリント（v0.78.0 から GA）
• Feature Flags - feature ブロックによる実行時制御
• Exclude Blocks - 詳細な実行制御（非推奨の skip を置き換えます）
• Errors Blocks - 高度なエラー処理（非推奨の retryable_errors を置き換えます）
• OpenTofu Engine - 代替 IaC エンジンのサポート

ルート構成の命名

推奨： 移行ガイドに従い、ルートファイルには terragrunt.hcl ではなく root.hcl を使用してください。

アプローチ	ルートファイル	Include 構文
モダン	root.hcl	find_in_parent_folders("root.hcl")
レガシー	terragrunt.hcl	find_in_parent_folders()

Include 標準： 新しい例および生成する構成では、デフォルトで find_in_parent_folders("root.hcl") を使用します。terragrunt.hcl という名前のレガシーなルートファイルを明示的に対象とする場合に限り、find_in_parent_folders() を使用してください。

アーキテクチャパターン

重要： 構成を生成する前に、必ずアーキテクチャパターンを特定し、その制約を理解してください。

パターン A：環境に依存しないルートを使用する複数環境構成

使用する場合： 共有ルート構成を使用して複数の環境（dev/staging/prod）を管理するとき。

重要な原則： root.hcl は環境に依存しません。環境固有のファイルを読み込みません。

infrastructure/
├── root.hcl              # Environment-AGNOSTIC (no env.hcl references)
├── dev/
│   ├── env.hcl           # Environment variables (locals block)
│   ├── vpc/terragrunt.hcl
│   └── rds/terragrunt.hcl
└── prod/
    ├── env.hcl           # Environment variables (locals block)
    ├── vpc/terragrunt.hcl
    └── rds/terragrunt.hcl

root.hcl の制約：

• ❌ read_terragrunt_config(find_in_parent_folders("env.hcl")) は使用できません。ルートレベルに env.hcl が存在しないためです
• ❌ env.hcl に由来する local.environment や local.aws_region は参照できません
• ✅ 静的な値、または実行時構成に get_env() を使用できます
• ✅ 状態キーには ${path_relative_to_include()} を使用できます（動的に機能します）

子モジュールで env.hcl を読み込みます：

# dev/vpc/terragrunt.hcl
include "root" {
  path = find_in_parent_folders("root.hcl")
}

locals {
  env = read_terragrunt_config(find_in_parent_folders("env.hcl"))
}

inputs = {
  name = "${local.env.locals.environment}-vpc"  # Works: env.hcl exists in dev/
}

パターン B：単一環境、または環境を認識するルート構成

使用する場合： 単一環境の場合、またはすべての環境で環境検出機能を備えた同じルートを共有する場合。

infrastructure/
├── root.hcl              # Can be environment-aware via get_env() or directory parsing
├── account.hcl           # Account-level config (optional)
├── region.hcl            # Region-level config (optional)
└── vpc/
    └── terragrunt.hcl

root.hcl で環境を検出できます：

# root.hcl - environment detection via directory path
locals {
  # Parse environment from path (e.g., "prod/vpc" -> "prod")
  path_parts  = split("/", path_relative_to_include())
  environment = local.path_parts[0]

  # OR use environment variable
  environment = get_env("TG_ENVIRONMENT", "dev")
}

パターン C：共有環境変数（_env ディレクトリ）

使用する場合： シンボリックリンクまたは直接参照を使用して環境変数を一元管理するとき。

infrastructure/
├── root.hcl              # Environment-AGNOSTIC
├── _env/                 # Centralized environment definitions
│   ├── prod.hcl
│   ├── staging.hcl
│   └── dev.hcl
├── prod/
│   ├── env.hcl           # Reads from _env/prod.hcl
│   └── vpc/terragrunt.hcl
└── dev/
    ├── env.hcl           # Reads from _env/dev.hcl
    └── vpc/terragrunt.hcl

env.hcl で _env から読み込みます：

# prod/env.hcl
locals {
  env_vars = read_terragrunt_config("${get_repo_root()}/_env/prod.hcl")

  # Re-export for child modules
  environment        = local.env_vars.locals.environment
  aws_region         = local.env_vars.locals.aws_region
  vpc_cidr           = local.env_vars.locals.vpc_cidr
  # ... other variables
}

アーキテクチャパターン選択チェックリスト（標準）

必須： ファイルを作成する前に、必ずこのチェックリストを完了し、チェックマークを付けた状態でユーザーに出力してください。これは省略できません。

ファイルを生成する前に、完了済みのチェックリストを出力してください：

## Architecture Pattern Selection

[x] Identified architecture pattern: Pattern ___ (A/B/C)
[x] Root.hcl scope: [ ] environment-agnostic  OR  [ ] environment-aware
[x] env.hcl location: ___________________
[x] Child modules access env via: ___________________
[x] Verified: No file references a path that doesn't exist from its location

チェックリストの記入例：

## Architecture Pattern Selection

[x] Identified architecture pattern: Pattern A (Multi-Environment with Environment-Agnostic Root)
[x] Root.hcl scope: [x] environment-agnostic  OR  [ ] environment-aware
[x] env.hcl location: dev/env.hcl, prod/env.hcl (one per environment)
[x] Child modules access env via: read_terragrunt_config(find_in_parent_folders("env.hcl"))
[x] Verified: No file references a path that doesn't exist from its location

変数定義の簡単な例

パターン B、およびアカウント／リージョンを考慮する構成では、これらのひな形ファイルを使用してください。

env.hcl

locals {
  environment = "dev"
  aws_region  = "us-east-1"
  project     = "platform"
}

account.hcl

locals {
  account_id   = "123456789012"
  account_name = "shared-services"
}

region.hcl

locals {
  aws_region = "us-east-1"
}

使用する場面

• 新しい Terragrunt プロジェクトや構成を作成するとき
• 複数の環境（dev/staging/prod）のインフラストラクチャを設定するとき
• DRY な Terraform 構成を実装するとき
• 依存関係を含む複雑なインフラストラクチャを管理するとき
• カスタム Terraform プロバイダーやモジュールを使用するとき

主な機能

1. ルート構成の生成

リモートステート、プロバイダー設定、共通変数を含む、ルートレベルの root.hcl または terragrunt.hcl を作成します。

必須： 生成する前に、テンプレートファイルを読み込んでください。

Read: assets/templates/root/terragrunt.hcl

テンプレート： assets/templates/root/terragrunt.hcl パターン： references/common-patterns.md → ルート構成のパターン

置き換える主なプレースホルダー：

• [BUCKET_NAME]、[AWS_REGION]、[DYNAMODB_TABLE]
• [TERRAFORM_VERSION]、[PROVIDER_NAME]、[PROVIDER_SOURCE]、[PROVIDER_VERSION]
• [ENVIRONMENT]、[PROJECT_NAME]

Root.hcl の設計原則：

1. デフォルトでは環境に依存しない設計にする - ルートレベルに env.hcl が存在すると想定しないでください
2. プロバイダー／バックエンドのリージョンには静的な値を使う - または、実行時の設定に get_env() を使ってください
3. ステートキーには path_relative_to_include() を使う - これにより環境パスが自動的に含まれます
4. プロバイダーのタグには静的な値を使えます - 環境固有のタグは子モジュールに設定してください

2. 子モジュール構成の生成

依存関係、モック出力、適切な include を含む子モジュールを作成します。

必須： 生成する前に、テンプレートファイルを読み込んでください。

Read: assets/templates/child/terragrunt.hcl

テンプレート： assets/templates/child/terragrunt.hcl パターン： references/common-patterns.md → 子モジュールのパターン

モジュールソースの選択肢：

• ローカル："../../modules/vpc"
• Git："git::https://github.com/org/repo.git//path?ref=v1.0.0"
• レジストリ："tfr:///terraform-aws-modules/vpc/aws?version=5.1.0"

3. スタンドアロンモジュールの生成

ルートに依存しない、自己完結型のモジュールです。

必須： 生成する前に、テンプレートファイルを読み込んでください。

Read: assets/templates/module/terragrunt.hcl

テンプレート： assets/templates/module/terragrunt.hcl

標準プレースホルダー置換マップ

生成するすべての出力で、このマップを使用してください。

プレースホルダー	意味	置換例	備考
[AWS_REGION]	AWS リージョン	us-east-1	すべてのテンプレートで標準のリージョン用プレースホルダー
[ENVIRONMENT]	環境名	dev	ディレクトリ名には小文字を使用
[PROJECT_NAME]	プロジェクト／アプリケーション名	payments-platform	タグと名前に同じ値を使用
[BUCKET_NAME]	リモートステートの S3 バケット	acme-tfstate-prod	初回の apply 前にバケットを作成しておく必要があります
[DYNAMODB_TABLE]	ステートロック用テーブル	acme-terraform-locks	初回の apply 前にテーブルを作成しておく必要があります
[PROVIDER_SOURCE]	Terraform プロバイダーのソース	hashicorp/aws	完全修飾されたソースを使用
[TERRAFORM_VERSION]	必須の Terraform/OpenTofu バージョン	1.8.5	terraform_version_constraint と required_version の両方で使用します。モジュールの制約と互換性があるバージョンを使用してください。

旧エイリアスの正規化： 古い例に [REGION] がある場合は、[AWS_REGION] として扱い、検証前に置き換えてください。

4. マルチ環境インフラストラクチャの生成

dev/staging/prod 用の完全なディレクトリ構造を作成します。

必須： 生成する前に、次の手順を実行してください。

1. アーキテクチャパターンを決定する（「アーキテクチャパターン」セクションを参照）
2. ルート、環境、子モジュール用の関連テンプレートを読み込む
3. env.hcl の配置とアクセスパターンを確認する：

   Read: assets/templates/env/env.hcl
   

パターン： references/common-patterns.md → 環境固有のパターン

一般的な構成（パターン A - 環境に依存しないルート）：

infrastructure/
├── root.hcl              # Environment-AGNOSTIC root config
├── dev/
│   ├── env.hcl           # Dev environment variables
│   └── vpc/terragrunt.hcl
└── prod/
    ├── env.hcl           # Prod environment variables
    └── vpc/terragrunt.hcl

5. Terragrunt スタックの生成（2025）

terragrunt.stack.hcl を使用したインフラストラクチャのブループリントです。

必須： 生成する前に、テンプレートファイルを読み込んでください。

Read: assets/templates/stack/terragrunt.stack.hcl
Read: assets/templates/catalog/terragrunt.hcl

ドキュメント： スタックのドキュメント テンプレート： assets/templates/stack/terragrunt.stack.hcl カタログテンプレート： assets/templates/catalog/terragrunt.hcl パターン： references/common-patterns.md → スタックのパターン

スタックパスのルール： 依存するユニット間で no_dot_terragrunt_stack モードを一貫させてください。同じ依存関係チェーン内で、直接パスと .terragrunt-stack による生成を混在させないでください。

コマンド：

terragrunt stack generate    # Generate unit configurations
terragrunt stack run plan    # Plan all units
terragrunt stack run apply   # Apply all units
terragrunt stack output      # Get aggregated outputs
terragrunt stack clean       # Clean generated directories

6. フィーチャーフラグの生成（2025）

コードを変更せずに実行時の動作を制御できます。

ドキュメント： フィーチャーフラグのドキュメント パターン： references/common-patterns.md → フィーチャーフラグのパターン

重要： フィーチャーフラグの default 値は、静的な値（ブール値、文字列、数値）でなければなりません。 local.* の値は参照できません。静的なデフォルト値を使用し、CLI／環境変数で上書きしてください。

正しい例：

feature "enable_monitoring" {
  default = false  # Static value - OK
}

誤った例：

feature "enable_monitoring" {
  default = local.env.locals.enable_monitoring  # Dynamic reference - FAILS
}

使用方法：

terragrunt apply --feature enable_monitoring=true
# or
export TG_FEATURE="enable_monitoring=true"

環境ごとのデフォルト値： 動的な参照ではなく、環境ファイルごとに異なる静的なデフォルト値を使用してください。

7. Exclude ブロックの生成（2025）

実行をきめ細かく制御します（非推奨の skip を置き換えます）。

ドキュメント： Exclude ブロックのリファレンス パターン： references/common-patterns.md → Exclude ブロックのパターン

アクション： "plan"、"apply"、"destroy"、"all"、"all_except_output"

本番環境での推奨事項： 重要な本番リソースには、誤った破棄を防ぐために Exclude ブロックを追加してください。

# Protect production databases from accidental destroy
exclude {
  if      = true
  actions = ["destroy"]
  exclude_dependencies = false
}

# Also use prevent_destroy for critical resources
prevent_destroy = true

8. Errors ブロックの生成（2025）

高度なエラー処理を行います（非推奨の retryable_errors を置き換えます）。

ドキュメント： Errors ブロックのリファレンス パターン： references/common-patterns.md → Errors ブロックのパターン

9. OpenTofu エンジン設定の生成（2025）

IaC エンジンとして OpenTofu を使用します。

ドキュメント： エンジンのドキュメント パターン： references/common-patterns.md → OpenTofu エンジンのパターン

10. カスタムプロバイダー／モジュールの処理

カスタムプロバイダーを使用する設定を生成する場合：

1. プロバイダー名、ソース、バージョンを特定します
2. WebSearch で "[provider] terraform provider [version] documentation" を検索します
3. 利用可能な場合は、Context7 MCP を使用して構造化されたドキュメントを参照します
4. 適切な required_providers ブロックを含めて生成します
5. 認証要件をコメントに記載します

生成ワークフロー

重要： すべての生成タスクで、このワークフローに従ってください。手順を省略すると、検証エラーにつながります。

Step 1：要件の把握

• どの種類の設定ですか？（ルート、子、スタンドアロン、スタック）
• 単一環境ですか、複数環境ですか？
• モジュール間にはどのような依存関係がありますか？
• どのプロバイダー／モジュールを使用しますか？

Step 2：アーキテクチャパターンの決定

必須： ファイルを書き込む前に、パターンを選択して記録してください。

シナリオ	パターン	Root.hcl の適用範囲
共有ルートを持つ複数環境	Pattern A	環境に依存しない
単一環境	Pattern B	環境に依存する
集中管理された環境変数	Pattern C	環境に依存しない

上記の**アーキテクチャパターン選択チェックリスト（標準版）**を完了し、ファイル生成の前に出力に含めてください。

Step 3: 必須テンプレートを読む

必須： 各種設定を生成する前に、該当するテンプレートファイルを読んでください。

設定タイプ	読むテンプレート	目的
ルート設定	assets/templates/root/terragrunt.hcl	共有ステートバックエンド、プロバイダー、共通入力
環境変数	assets/templates/env/env.hcl	子モジュールが読み込む環境ごとのローカル変数（パターン A）
子モジュール	assets/templates/child/terragrunt.hcl	ルートの include に接続された環境モジュール
スタンドアロンモジュール	assets/templates/module/terragrunt.hcl	ルートの include を使用しない独立した Terragrunt モジュール
スタックファイル	assets/templates/stack/terragrunt.stack.hcl	複数のユニットを生成するブループリント
カタログユニット	assets/templates/catalog/terragrunt.hcl	スタックで使用する再利用可能なユニットテンプレート

あわせて読むもの：

• references/common-patterns.md - 生成パターンの主要な参照元

Step 4: 検証しながら生成する

検証戦略： 生成中のインラインチェックと、最後の一括検証を組み合わせます。

複数環境のプロジェクトにおける生成順序：

1. 最初に root.hcl を生成する

   • インラインチェック（生成中）：
     • 環境に依存しない場合、read_terragrunt_config(find_in_parent_folders("env.hcl")) を使用しない
     • remote_state ブロックに encrypt = true がある
     • 非推奨の retryable_errors ではなく errors ブロックを使用する

2. 各環境の env.hcl ファイルを生成する

   • インラインチェック（生成中）：
     • locals ブロックに environment、aws_region、およびモジュール固有の変数が含まれている
     • そのディレクトリレベルに存在しないファイルへの参照がない

3. 子モジュール（VPC など）を生成する - 依存関係のないモジュールを先に生成する

   • インラインチェック（生成中）：
     • include ブロックで find_in_parent_folders("root.hcl") を使用している
     • read_terragrunt_config(find_in_parent_folders("env.hcl")) がある
     • terraform.source が有効な構文（tfr:///、git::、相対パス）を使用している

4. 依存するモジュール（RDS、EKS など）を生成する

   • インラインチェック（生成中）：
     • dependency ブロックに mock_outputs がある
     • mock_outputs_allowed_terraform_commands に ["validate", "plan", "destroy"] が含まれている
     • 本番モジュールに prevent_destroy = true および／または exclude ブロックがある

5. すべてのファイルを生成した後、一括検証を実行する

   注： 完全な CLI 検証（terragrunt hcl fmt、terragrunt dag graph）にはすべてのファイルが必要なため、最後にまとめて実行します。

   # Batch validation commands (run after all files exist):
   terragrunt hcl fmt --check          # Format validation
   terragrunt dag graph                 # Dependency graph validation
   

   • 包括的な検証のために Skill(devops-skills:terragrunt-validator) を呼び出す

Step 5: 修正して再検証する

検証に失敗した場合：

1. エラーを分析する（パス解決、変数の不足、構文エラー）
2. 該当するファイルの問題を修正する
3. 修正したファイルを再検証する
4. すべてのエラーが解消されるまで繰り返す

Step 6: 結果を提示する

以下の「提示要件」セクションに従ってください。

検証ワークフロー

重要： 生成した設定はすべて検証する必要があります。

段階的な検証チェック

root.hcl の生成後：

cd <infrastructure-directory>
terragrunt hcl fmt --check

各子モジュールの生成後：

cd <module-directory>
terragrunt hcl fmt --check
# If no dependencies on other modules:
terragrunt hcl validate --inputs

完全な検証

すべてのファイルを生成した後：

1. 検証スキルを呼び出す：

   Invoke: Skill(devops-skills:terragrunt-validator)
   

2. 検証に失敗した場合：

   • エラーを分析する（プレースホルダーの不足、無効な構文、誤ったパス）
   • 問題を修正する
   • 再検証する（すべてのエラーが解消されるまで繰り返す）

3. 検証に成功した場合： 使用方法の説明とともに設定を提示する

検証を省略できるのは次の場合のみ： 部分的なスニペット、ドキュメントの例、またはユーザーから明示的な依頼があった場合

検証のフォールバック（環境上の制約）

通常の検証方法を利用できない場合は、次の順序でフォールバックし、スキップした内容を報告してください。

1. terragrunt を利用できない場合：
   • 静的チェックを実行します。

     rg -n "\[[A-Z0-9_]+\]" .
     rg -n "find_in_parent_folders\\(\"env\\.hcl\"\\)" .
     

   • Terragrunt の実行時検証が保留中であることを報告します。
2. バリデーターのスキルを実行できない場合：
   • 代わりに Terragrunt のチェックを直接実行します。

     terragrunt hcl fmt --check
     terragrunt dag graph
     

3. 表示用の tree を利用できない場合：
   • 次のコマンドを使用します。

     find . -maxdepth 4 -type f | sort
     

表示要件

必須： 検証に成功した後、以下のすべてのセクションを必ず提示してください。不完全な提示は認められません。以下のテンプレートをコピーして記入してください。

1. ディレクトリ構成の概要（必須）

# Show the generated structure
tree <infrastructure-directory>

2. 生成されたファイル（必須）

生成されたファイルをすべて含む次の表を出力してください：

| File | Purpose |
|------|---------|
| root.hcl | Shared configuration for all child modules (state backend, provider) |
| dev/env.hcl | Development environment variables |
| prod/env.hcl | Production environment variables |
| dev/vpc/terragrunt.hcl | VPC module for development |
| ... | ... |

3. 使用方法（必須）

このセクションを必ず含めてください。 以下のテンプレートをコピーし、実際の値を記入してください。

## Usage Instructions

### Prerequisites
Before running Terragrunt commands, ensure:
1. AWS credentials are configured (`aws configure` or environment variables)
2. S3 bucket `<BUCKET_NAME>` exists for state storage
3. DynamoDB table `<TABLE_NAME>` exists for state locking

### Commands

# Navigate to infrastructure directory
cd <INFRASTRUCTURE_DIR>

# Initialize all modules
terragrunt run --all init

# Preview changes for a specific environment
cd <ENV>/vpc && terragrunt plan

# Preview all changes
terragrunt run --all plan

# Apply changes (requires approval)
terragrunt run --all apply

# Destroy (use with extreme caution)
terragrunt run --all destroy

4. プレースホルダーの置換とシークレットの確認（必須）

このセクションを必ず含めてください。 以下のテンプレートをコピーし、実際の値を記入してください。

## Placeholder and Secrets Check

### Placeholder Replacement
- [ ] All placeholders (`[AWS_REGION]`, `[BUCKET_NAME]`, `[DYNAMODB_TABLE]`, etc.) replaced with real values
- [ ] No legacy placeholder aliases left (for example `[REGION]`)
- [ ] `terraform.source` values point to real module sources and pinned versions

### Secrets Safety
- [ ] No plaintext credentials or access keys in `terragrunt.hcl`, `root.hcl`, `env.hcl`, `account.hcl`, or `region.hcl`
- [ ] Sensitive values sourced via environment variables, secret managers, or CI variables
- [ ] Example values kept non-sensitive and clearly marked as placeholders

5. 環境固有の注意事項（必須）

このセクションを必ず含めてください。 以下のテンプレートをコピーし、実際の値を記入してください。

## Environment Notes

### Required Environment Variables
| Variable | Description | Example |
|----------|-------------|---------|
| AWS_PROFILE | AWS CLI profile to use | `my-profile` |
| AWS_REGION | AWS region (or set in provider) | `us-east-1` |

### Prerequisites
- [ ] S3 bucket `<BUCKET_NAME>` must exist before first run
- [ ] DynamoDB table `<TABLE_NAME>` must exist for state locking
- [ ] IAM permissions for Terraform state management

### Production-Specific Protections
| Module | Protection | Description |
|--------|------------|-------------|
| prod/rds | `prevent_destroy = true` | Prevents accidental database deletion |
| prod/rds | `exclude { actions = ["destroy"] }` | Blocks destroy commands |

6. 次のステップ（任意）

モジュールの追加や設定のカスタマイズなど、ユーザーが次に行うとよいことを提案してください。

ベストプラクティス

包括的なガイドラインについては、../terragrunt-validator/references/best_practices.md を参照してください。

主な原則：

• ルート設定を継承するには include ブロックを使用します（DRY）。
• 依存関係には必ずモック出力を指定します。
• 状態の暗号化を有効にします（encrypt = true）。
• プロバイダー設定には generate ブロックを使用します。
• ローカルモジュール／Git モジュールでは、上限を設けたバージョン制約（>= 5.0 ではなく ~> 5.0）を指定します。
• 認証情報やシークレットをハードコードしないでください。
• 一時的なエラーに備えて、リトライロジックを設定します。

レジストリモジュールのバージョン制約に関する注意： Terraform Registry のモジュール（例：tfr:///terraform-aws-modules/vpc/aws?version=5.1.0）は、通常、独自の required_providers を定義しています。この場合、競合を避けるために、root.hcl での required_providers の生成を省略してもかまいません。モジュールの固定バージョン（?version=X.X.X）によってバージョン制約が指定されます。詳細は「よくある問題 → Registry モジュールでのプロバイダー競合」を参照してください。

避けるべきアンチパターン：

• アカウント ID、リージョン、環境名のハードコード
• 依存関係のモック出力の欠落
• モジュール間での設定の重複
• 暗号化されていない状態の保存
• バージョン制約の欠落または緩すぎる制約（独自の制約を定義するレジストリモジュールを使用する場合を除く）
• ルート階層に存在しない env.hcl を root.hcl から読み込もうとすること

非推奨の属性

非推奨	置き換え先	参照先
skip	exclude ブロック	ドキュメント
retryable_errors	errors.retry ブロック	ドキュメント
run-all	run --all	移行ガイド
--terragrunt-* フラグ	接頭辞なしのフラグ	CLI リファレンス
TERRAGRUNT_* 環境変数	TG_* 環境変数	CLI リファレンス

リソース

テンプレート - 生成前に必ず読むこと

設定タイプ	テンプレートファイル	目的	読むタイミング
ルート設定	assets/templates/root/terragrunt.hcl	共有バックエンド、プロバイダー、共通の入力	ルートの root.hcl を生成する前
環境変数	assets/templates/env/env.hcl	環境ごとのローカル値（環境、リージョン、サイズ、機能フラグ）	env.hcl（パターン A）を生成する前
子モジュール	assets/templates/child/terragrunt.hcl	モジュールのインクルード、ソース、オプションの依存関係のひな形	子モジュールを生成する前
スタンドアロンモジュール	assets/templates/module/terragrunt.hcl	ルートの継承を使用しないモジュール設定	スタンドアロンモジュールを生成する前
スタックファイル	assets/templates/stack/terragrunt.stack.hcl	スタックの設計図とユニットの生成	スタックを生成する前
カタログユニット	assets/templates/catalog/terragrunt.hcl	スタック定義で使用する再利用可能なユニット	カタログユニットを生成する前

参考資料

参考資料	内容	目的	読むタイミング
references/common-patterns.md	例を含むすべての生成パターン	ファイルを作成する前に、互換性のあるパターンを選択する	生成前に必ず読む
../terragrunt-validator/references/best_practices.md	包括的なベストプラクティス	最終的な品質と安全性の確認	生成前に必ず読む

公式ドキュメント

• Terragrunt ドキュメント
• 設定リファレンス
• CLI リファレンス
• スタック
• 機能フラグ
• エンジン
• 移行ガイド

よくある問題

Root.hcl から env.hcl が見つからない

症状：

Error: Attempt to get attribute from null value
  on ./root.hcl line X:
  This value is null, so it does not have any attributes.

原因： Root.hcl は find_in_parent_folders("env.hcl") を使って env.hcl を読み込もうとしていますが、ルート階層に env.hcl が存在しません。

解決策： Root.hcl を環境に依存しない設定にします。

# DON'T do this in root.hcl for multi-environment setups:
locals {
  env_vars = read_terragrunt_config(find_in_parent_folders("env.hcl"))  # FAILS
}

# DO use static values or get_env():
generate "provider" {
  path      = "provider.tf"
  if_exists = "overwrite_terragrunt"
  contents  = <<EOF
provider "aws" {
  region = "us-east-1"  # Static value, or use get_env("AWS_REGION", "us-east-1")
}
EOF
}

レジストリモジュールとのプロバイダーの競合

Terraform Registry モジュール（例：tfr:///terraform-aws-modules/vpc/aws）を使用する場合、モジュール側で独自の required_providers ブロックを定義していることがあります。これは root.hcl で生成されるプロバイダー設定と競合する可能性があります。

症状：

Error: Duplicate required providers configuration

解決策：

1. 競合する generate ブロックを削除する - 独自のプロバイダーを管理するレジストリモジュールを使用する場合、重複する required_providers の生成を避けます。

   # In root.hcl - only generate provider config, not required_providers
   generate "provider" {
     path      = "provider.tf"
     if_exists = "overwrite_terragrunt"
     contents  = <<EOF
   provider "aws" {
     region = "us-east-1"
   }
   EOF
   }
   

2. if_exists = "skip" を使用する - ファイルがすでに存在する場合は生成をスキップします。

   generate "versions" {
     path      = "versions.tf"
     if_exists = "skip"  # Don't overwrite module's versions.tf
     contents  = "..."
   }
   

3. キャッシュをクリアする - 修正後も競合が続く場合：

   rm -rf .terragrunt-cache
   terragrunt init
   

機能フラグの検証エラー

機能ブロックで Unknown variable; There is no variable named "local" が表示される場合は、デフォルト値が静的な値であることを確認してください（上記の「機能フラグ」セクションを参照）。

子モジュールから env.hcl が見つからない

症状：

Error: Attempt to get attribute from null value
  on ./dev/vpc/terragrunt.hcl line X:

原因： 子モジュールの find_in_parent_folders("env.hcl") で env.hcl が見つかりません。

解決策： 環境ディレクトリに env.hcl が存在することを確認します。

dev/
├── env.hcl           # This file MUST exist
└── vpc/
    └── terragrunt.hcl  # Calls find_in_parent_folders("env.hcl")

クイックリファレンスカード

ファイル読み込みチェックリスト

生成前に、以下のファイルを順番に読みます。

1. references/common-patterns.md - 利用可能なパターンを理解する
2. ../terragrunt-validator/references/best_practices.md - ルールを把握する
3. assets/templates/ の関連テンプレート - 構造を確認する

アーキテクチャ決定ツリー

Q: Multiple environments (dev/staging/prod)?
├─ YES → Q: Shared root configuration?
│   ├─ YES → Pattern A: Environment-Agnostic Root
│   └─ NO  → Separate root.hcl per environment
└─ NO  → Q: Environment detection needed?
    ├─ YES → Pattern B: Environment-Aware Root
    └─ NO  → Pattern B: Simple single-environment

検証手順

1. フォーマットの確認：terragrunt hcl fmt --check
2. 入力の検証：terragrunt hcl validate --inputs
3. 完全な検証：Skill(devops-skills:terragrunt-validator) を呼び出す
4. エラーを修正 → 再検証 → 問題がなくなるまで繰り返す

完了条件

このスキルの実行は、以下のすべてを満たした場合にのみ完了です。

• 1 つのアーキテクチャチェックリストが完了し、提示されている（このファイル内の正式なチェックリスト）
• 生成されたファイルでは、レガシー形式が明示的に要求されていない限り、一貫して最新のルートインクルード構文が使用されている
• レジストリソースでは、正式な tfr:///NAMESPACE/NAME/PROVIDER?version=X.Y.Z 形式が使用されている
• 依存関係ブロックは実際に必要な場合にのみ追加されている（未解決のプレースホルダーとして残されていない）
• すべてのプレースホルダーが置き換えられ、シークレットのチェック結果が出力に報告されている
• 検証に成功しているか、制限事項が明記されたうえで代替チェックが実行されている