terragrunt-skill

Terragrunt インフラストラクチャスキル

概要

このスキルは、OpenTofu と組み合わせた Terragrunt を用いたインフラストラクチャに関するガイダンスを提供します。以下の 3 リポジトリパターンに従います。

1. インフラストラクチャカタログ - 別々のリポジトリのモジュールを参照するユニットとスタック
2. インフラストラクチャ Live - カタログを利用する環境固有のデプロイ
3. モジュールリポジトリ - 各 OpenTofu モジュール用の個別リポジトリ（独立したバージョン管理）

アーキテクチャの選択

デフォルトの推奨: 明示的スタック — このスキルで解説するカタログ + terragrunt.stack.hcl + values パターンです。ユニットはスタックファイルから生成され、設定は values を通じて流れ、ユニットごとのボイラープレートは不要です。

サポートされる代替案: 従来の暗黙的スタック — 元々の Gruntwork パターンです。account/region/env/component のディレクトリ階層、レベルごとの .hcl 変数ファイル、include + expose による _envcommon/ 内の共有コンポーネント設定を使用します。ユニットのディレクトリはすべて暗黙的スタックです。リポジトリがすでにこの構成に従っている場合、規模が小さすぎてカタログを正当化できない場合、またはチームがスタックに対応する準備ができていない場合に使用します。詳細は classic-live-structure.md を参照してください。

直交する選択: モジュールの構成 — モジュールのモノレポ（modules/ + examples/、1 つのタグがすべてをバージョン管理、//modules/x?ref= によるソース指定）と、モジュールごとのリポジトリ（独立したバージョン管理）があります。どちらもどちらのアーキテクチャでも機能します。詳細は modules-monorepo.md を参照してください。

従来型 → スタックへの移行: 公式の Terralith to Terragrunt ガイド に従ってください。

クイックナビゲーション

トピック	リファレンス
命名規則	naming.md
カタログ構造	catalog-structure.md
Live リポジトリ構造	live-structure.md
従来の Live 構造（暗黙的スタック）	classic-live-structure.md
モジュールのモノレポ	modules-monorepo.md
検出コマンド（find/list/dag）	discovery-commands.md
ルート/アカウント/環境設定	root-config.md
ユニットの依存関係	dependencies.md
カタログのスキャフォールディング	catalog-scaffolding.md
スタックコマンド	stack-commands.md
パターンとベストプラクティス	patterns.md
状態管理	state-management.md
マルチアカウント構成	multi-account.md
パフォーマンス最適化	performance.md
Content Addressable Store (CAS)	cas.md
CI/CD パイプライン（共有 + IAM/OIDC 設定）	cicd-pipelines.md
GitLab CI パイプライン	cicd-gitlab.md
GitHub Actions パイプライン	cicd-github.md

中核となる概念

Values パターン

ユニットは values.xxx を通じて設定を受け取ります:

inputs = {
  name        = values.name
  environment = values.environment
  instance_class = try(values.instance_class, "db.t3.medium")  # Optional with default
}

参照の解決

ユニットは "../acm" のようなシンボリック参照を依存関係の出力に解決します:

inputs = {
  acm_certificate_arn = try(values.acm_certificate_arn, "") == "../acm" ?
    dependency.acm.outputs.acm_certificate_arn :
    values.acm_certificate_arn
}

Terragrunt 1.1+ では autoinclude ブロックが代替手段として追加されています — 依存関係はスタックファイルで宣言され、カタログのユニットは依存関係にとらわれないままです。両者の選択については dependencies.md を参照してください。

モジュールのソース指定

ユニットは values から取得したバージョンを付けて、Git URL 経由でモジュールを参照します:

terraform {
  source = "git::[email protected]:YOUR_ORG/modules/rds.git//app?ref=${values.version}"
}

カタログ内部の参照（同一リポジトリ内のユニット/スタック/モジュール）については、Terragrunt 1.1+ では update_source_with_cas = true を指定した単純な相対パスが許可されています — stack generate がそれらをコンテンツアドレス参照に書き換えるため、URL の固定やバージョンの配線は不要です。詳細は cas.md を参照してください。

一般的な操作

新しいユニットを作成する

1. units/<name>/terragrunt.hcl を作成します
2. ${values.version} を含む Git URL 経由でモジュールを参照します
3. 入力には values.xxx を使用します
4. モック出力を含む依存関係を追加します
5. "../unit" パターンの参照解決を実装します

新しいスタックを作成する

1. stacks/<name>/terragrunt.stack.hcl を作成します
2. 計算値のために locals を定義します
3. カタログユニットを参照する unit ブロックを追加します
4. バージョンや依存関係パスを含む値を渡します

新しい環境にデプロイする

1. 環境ディレクトリ構造を作成します
2. state_bucket_suffix を含む env.hcl を追加します
3. terragrunt run --all -- backend bootstrap を実行してステートリソースを作成します
4. カタログを参照するスタックファイルを追加します

ベストプラクティス

1. モジュールのバージョンを固定する - values.version に Git タグを使用します
2. カタログのバージョンを固定する - ユニットのソース URL に refs を使用します
3. 参照解決を使用する - "../unit" → 依存関係の出力
4. モック出力を提供する - 依存関係なしで plan/validate を有効にします
5. 機能を自動検出する - length(keys(try(values.X, {}))) > 0
6. パスを上書きする - try(values.X_path, "../default")
7. 環境ごとにステートを分離する - state_bucket_suffix を使用します

よくある落とし穴

1. Git refspec エラー - ?ref=branch//path ではなく //path?ref=branch を使用します
2. 三項演算子内のヒアドキュメント - 括弧で囲みます: condition ? (\n<<-EOF\n...\nEOF\n) : ""
3. モック出力の不足 - plan/validate のために常に提供します
4. ハードコードされたパス - ローカルパスはテストにのみ使用します

バージョン管理

• 開発: ブランチ refs（ref=feature-branch）
• テスト: RC タグ（ref=v1.0.0-rc1）
• 本番: 安定版タグ（ref=v1.0.0）