terragrunt-skill

Terragrunt 基础设施技能

概述

本技能为使用 Terragrunt 配合 OpenTofu 的基础设施提供指导，遵循三仓库模式：

1. Infrastructure Catalog - 引用来自独立仓库的模块的单元和栈
2. Infrastructure Live - 使用 catalog 的特定环境部署
3. Module Repos - 每个 OpenTofu 模块的独立仓库（独立版本控制）

选择架构

默认推荐：显式栈 —— 本技能所教授的 catalog + terragrunt.stack.hcl + values 模式。单元从栈文件生成；配置通过 values 流转；没有逐单元的样板代码。

支持的替代方案：经典隐式栈 —— 最初的 Gruntwork 模式：account/region/env/component 目录层级，逐级 .hcl 变量文件，通过 include + expose 在 _envcommon/ 中共享组件配置。任何单元目录都是隐式栈。当仓库已经遵循此模式、规模太小不足以证明使用 catalog 的合理性、或团队尚未准备好使用栈时，请使用它。参见 classic-live-structure.md。

正交选择：模块组织方式 —— 模块 monorepo（modules/ + examples/，一个标签为所有模块版本，//modules/x?ref= 引用方式）vs 每仓库一个模块（独立版本控制）。两者都可与任一架构配合使用。参见 modules-monorepo.md。

从经典迁移到栈：遵循官方的 Terralith to Terragrunt 指南。

快速导航

主题	参考
命名约定	naming.md
Catalog 结构	catalog-structure.md
Live 仓库结构	live-structure.md
经典 live 结构（隐式栈）	classic-live-structure.md
模块 monorepo	modules-monorepo.md
发现命令（find/list/dag）	discovery-commands.md
根/账户/环境配置	root-config.md
单元依赖	dependencies.md
Catalog 脚手架	catalog-scaffolding.md
栈命令	stack-commands.md
模式与最佳实践	patterns.md
状态管理	state-management.md
多账户设置	multi-account.md
性能优化	performance.md
内容寻址存储（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 块作为替代方案 —— 依赖在栈文件中声明，catalog 单元保持与依赖无关。关于如何在两者之间选择，参见 dependencies.md。

模块引用

单元通过 Git URL 引用模块，版本从 values 中获取：

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

对于 catalog 内部引用（同一仓库中的单元/栈/模块），Terragrunt 1.1+ 允许使用普通相对路径并设置 update_source_with_cas = true —— stack generate 会将它们重写为内容寻址引用，因此无需 URL 固定或版本传递。参见 cas.md。

常见操作

创建新单元

1. 创建 units/<name>/terragrunt.hcl
2. 通过 Git URL 引用模块，并使用 ${values.version}
3. 使用 values.xxx 作为输入
4. 添加带 mock 输出的依赖
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 中使用 ref
3. 使用引用解析 - "../unit" → 依赖输出
4. 提供 mock 输出 - 使 plan/validate 无需依赖即可运行
5. 自动检测功能 - length(keys(try(values.X, {}))) > 0
6. 覆盖路径 - try(values.X_path, "../default")
7. 按环境分离状态 - 使用 state_bucket_suffix

常见陷阱

1. Git refspec 错误 - 使用 //path?ref=branch，而不是 ?ref=branch//path
2. 三元表达式中的 Heredoc - 用括号包裹：condition ? (\n<<-EOF\n...\nEOF\n) : ""
3. 缺少 mock 输出 - 始终为 plan/validate 提供
4. 硬编码路径 - 仅在测试时使用本地路径

版本管理

• 开发： 分支 ref（ref=feature-branch）
• 测试： RC 标签（ref=v1.0.0-rc1）
• 生产： 稳定标签（ref=v1.0.0）