mcpField
T
terragrunt

terragrunt

github.com/ionfury云与 DevOps2566 次安装今天更新
代码仓库

关于 terragrunt

用于通过 Terragrunt 管理裸机 Kubernetes 基础设施的技能，涵盖从 PXE 启动到集群运行。它为基础设施贡献者提供项目专用任务命令，以及机器清单、功能标志、单元和验证流程指引。

主要功能

  1. 01通过 task 格式化、测试和验证 Terragrunt
  2. 02机器清单修改与堆栈规划指引
  3. 03功能标志和单元创建模式
  4. 04状态操作与验证注意事项

适用场景

  1. 01将机器加入 live 集群清单
  2. 02添加功能标志或基础设施单元
  3. 03验证并审查多个堆栈的更改

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/ionfury/homelab --skill terragrunt

安装后在 Claude Code 中输入/terragrunt确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

tests.yaml
references/
stacks.md
units.md

详细介绍

Terragrunt 基础设施 Skill

管理裸机 Kubernetes 基础设施，从 PXE 启动到集群运行。

有关架构概览（unit 与 module 的区别、配置集中化），请参阅 infrastructure/CLAUDE.md。有关详细的 unit 模式，请参阅 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 → 审查计划（config module 会自动包含 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")）→ 在 stack 的 features 列表中启用（features = ["gateway-api", "longhorn", "new-feature"]）。

如何创建新的 unit

创建 units/new-unit/terragrunt.hcl（include root、指向 module 源、使用 mock_outputs 声明 dependency "config"、设置 inputs = dependency.config.outputs.new_unit）→ 创建 modules/new-unit/，其中包含 variables.tf、main.tf、outputs.tf、versions.tf → 从 config module 添加 output → 将 unit 块添加到需要它的 stack。完整 unit 模板请参阅 units.md。

有关 module 测试，请参阅 opentofu-modules skill。运行 task tg:test-config，或运行 task tg:test 测试所有 module。

重要事项

  • 切勿猜测 MAC 地址或 IP——必须对照 inventory.hcl 核实
  • 切勿提交 .terragrunt-cache/ 或 .terragrunt-stack/
  • 切勿手动编辑 Terraform state

State 操作

使用带索引的资源（例如 this["rpi4"]）移除 state 条目时，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

这适用于对带 map 键的资源（如 data.talos_machine_configuration.this["rpi4"]）进行的任何 state 操作。

验证清单

task tg:fmt → task tg:test（如果存在 module 测试）→ 对所有 stack 运行 task tg:validate-<stack> → 审查 task tg:plan-<stack>（没有意外的 destroy，网络变更不会破坏连接性）。

参考

  • stacks.md - 详细的 Terragrunt stacks 文档
  • units.md - 详细的 Terragrunt units 文档

评论

支持 Markdown