terragrunt

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

PXE ブートから稼働中のクラスターまで、ベアメタル Kubernetes インフラストラクチャを管理します。

アーキテクチャの概要（ユニットとモジュール、設定の一元化）については、infrastructure/CLAUDE.md を参照してください。ユニットの詳しいパターンについては、infrastructure/units/CLAUDE.md を参照してください。

タスクコマンド（必ず使用してください）

# Validation (run in order)
task tg:fmt                    # Format HCL files
task tg:test-<module>          # Test specific module (e.g., task tg:test-config)
task tg:validate-<stack>       # Validate stack (e.g., task tg:validate-integration)

# Operations
task tg:list                   # List available stacks
task tg:plan-<stack>           # Plan (e.g., task tg:plan-integration)
task tg:apply-<stack>          # Apply (REQUIRES HUMAN APPROVAL)
task tg:gen-<stack>            # Generate stack files
task tg:clean-<stack>          # Clean generated files

terragrunt または tofu を直接実行してはいけません。必ず task コマンドを使用してください。

マシンを追加する方法

inventory.hcl を編集 → task tg:plan-live を実行 → プランを確認（設定モジュールは cluster == "live" のマシンを自動的に含めます）→ apply の前に人間による承認を依頼します。

node50 = {
  cluster = "live"
  type    = "worker"
  install = {
    selector     = "disk.model == 'Samsung'"
    architecture = "amd64"
  }
  interfaces = [{
    id           = "eth0"
    hardwareAddr = "aa:bb:cc:dd:ee:ff"  # VERIFY correct
    addresses    = [{ ip = "192.168.10.50" }]  # VERIFY available
  }]
}

フィーチャーフラグを追加する方法

必要に応じて versions.hcl にバージョンを追加 → modules/config/main.tf にフィーチャー検出を追加（contains(var.features, "new-feature")）→ スタックの features リストで有効にします（features = ["gateway-api", "longhorn", "new-feature"]）。

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

units/new-unit/terragrunt.hcl を作成（root をインクルードし、モジュールのソースを指定し、mock_outputs を含む dependency "config" を宣言し、inputs = dependency.config.outputs.new_unit を設定）→ variables.tf、main.tf、outputs.tf、versions.tf を含む modules/new-unit/ を作成 → config モジュールに出力を追加 → 必要なスタックに unit ブロックを追加します。ユニットのテンプレート全体については、units.md を参照してください。

モジュールテストについては、opentofu-modules スキルを参照してください。task tg:test-config を実行するか、すべてのモジュールをテストする場合は task tg:test を実行します。

重要

• 決して MAC アドレスや IP アドレスを推測せず、inventory.hcl で確認してください
• 決して .terragrunt-cache/ や .terragrunt-stack/ をコミットしないでください
• 決して Terraform の状態を手動で編集しないでください

状態の操作

インデックス付きリソース（例：this["rpi4"]）の状態エントリを削除する際、xargs は引用符を取り除くため、エラーが発生します。代わりに while ループを使用してください。

# WRONG - xargs mangles quotes in resource names
terragrunt state list | xargs -n 1 terragrunt state rm

# CORRECT - while loop preserves quotes
terragrunt state list | while read -r resource; do terragrunt state rm "$resource"; done

これは、data.talos_machine_configuration.this["rpi4"] のようにマップキーを持つリソースに対するあらゆる状態操作に適用されます。

検証チェックリスト

task tg:fmt → task tg:test（モジュールテストがある場合）→ すべてのスタックに対して task tg:validate-<stack> → task tg:plan-<stack> の内容を確認（予期しない破棄がないこと、ネットワークの変更で接続が切断されないこと）。

参考資料

• stacks.md - Terragrunt スタックの詳細なドキュメント
• units.md - Terragrunt ユニットの詳細なドキュメント