Terragrunt 编排规模化路径从单模块到团队规模的 4 步实践【免费下载链接】terragruntTerragrunt is a flexible orchestration tool that allows Infrastructure as Code written in OpenTofu/Terraform to scale.项目地址: https://gitcode.com/GitHub_Trending/te/terragrunt当仓库里第 50 个模块开始复制粘贴同一份 S3 状态配置时问题就不在代码里了。Terragrunt 编排把每个模块各管各的变成一条配置链、一张依赖图、一套锁。下面四个阶段是我们实际走过的路径每一步都有验收标准。心智模型先建立 3 个直觉再碰配置这节解决知道命令但不知道边界在哪的问题。单元 ≈ 单服务的户口。每个含terragrunt.hcl的目录是一个独立单元有自己的状态文件和 inputs。扩容的天花板不取决于工具取决于你把户口拆得多细。DAG ≈ 流水线。单元间的依赖组成有向无环图run-all按图排生产顺序。模块不用关心vpc 该先建吗图会替你排好。include ≈ 配置继承链。find_in_parent_folders向上找 root.hcl 等共享配置目录越深优先级越高。共享的往上沉差异的留在原地。Terragrunt 单元依赖关系图节点是单元边是 dependency 声明四阶段演进路径从单模块到团队规模这节按规模递进每个阶段该做什么、何时该做答案完全不同。阶段一单体可用单模块的第一个单元触发信号仓库里 1-3 个.tf目录状态文件还在工作目录里一个人还能记清每个模块在干嘛。# terragrunt.hcl —— 目的单单元所需的最小配置 terraform { source git::https://git.example.com/infra.git//networking?refv1.4.0 } inputs { project payments region eu-west-1 vpc_cidr 10.20.0.0/16 }为什么这么写source 锁定 tag单元的行为只由 inputs 和版本号决定而不是有人悄悄改了模块目录。验收标准✅ 在单元目录跑terragrunt plan能出正常 plan状态文件落在预期的 key 上目录里没有意外残留的本地状态。阶段二模块复用状态后端只定义一处触发信号新增模块时你在复制第 9 份 backend 配置改一次桶名要翻 8 个文件。# root.hcl —— 目的全仓库的状态后端只写一遍 remote_state { backend s3 config { bucket corp-tofu-state key ${path_relative_to_include()}/tofu.tfstate # 为什么按单元目录自动唯一 region eu-west-1 encrypt true dynamodb_table corp-tofu-locks } } # 单元 terragrunt.hcl —— 目的一行 include 完成接入 include root { path find_in_parent_folders(root.hcl) }为什么这么写remote state 的 key 不能手填path_relative_to_include()按相对目录生成单元侧只剩 include配置链靠继承补齐。验收标准✅ 新增单元只需 3 行 include单元目录里搜不到任何 backend 配置各单元状态 key 自动唯一。阶段三多环境一致用 dependency 替代硬编码输出触发信号prod/qa/stage 三个目录长得 90% 一样只有 instance_type 和 subnet ID 是写死的不同值。# _env/app.hcl —— 目的跨环境共享的依赖与输入 dependency vpc { config_path ../vpc } inputs { vpc_id dependency.vpc.outputs.vpc_id # 为什么自动取值无处写死 } # qa/app/terragrunt.hcl —— 目的只保留本环境的差异 include env { path ${get_terragrunt_dir()}/../../_env/app.hcl } inputs { env qa }为什么这么写_env目录下划线前缀表示不可部署只放跨环境相同的单元目录只放本环境不同的依赖值走dependency.vpc.outputs。Terragrunt 跨环境提升同一份源码各环境只有 env 输入不同验收标准✅diff prod/app/terragrunt.hcl qa/app/terragrunt.hcl只有一行 env 不同。阶段四团队规模化并发度与 CI 入口触发信号全量run-all apply从 10 分钟涨到 40 分钟每次 CI 都重新拉 provider日志里开始出现 429。# 目的全量执行的并发对齐云 API 限流 terragrunt run-all apply --parallelism 5为什么这么写并行度不是越大越快受云限流和状态锁约束多数团队 5-10 够用配合 provider cache 后 CI 不再重复下载。Terragrunt CI 流程PR 自动附上 plan 结果apply 走审批验收标准✅ 全量 plan 时间稳定CI 日志无 429/Throttlingprovider 每个 PR 只下载一次。决策速查表规模化前必然遇到的 5 个决策点这节替代零散的高级功能罗列遇到场景时直接查行。决策点推荐方案适用条件反例场景状态后端选型S3/GCS 锁表root.hcl 统一托管多单元、多环境单状态资源少于 10 个filesystem 够用单元粒度每服务每环境一个目录服务生命周期独立强耦合组件合并为同一单元跨单元取值dependency 块自动获取依赖对方 outputs一次性临时值走环境变量跨环境共享配置多级 includeroot _env环境数 ≥3 且高度相似只有 2 个环境locals 直接写CI 执行策略PR 内 run-all plan 并发控制团队 5 人以上、共享状态单人单仓库本地 plan 即可故障根因复盘状态串台、循环依赖与锁冲突的 3 个高频坑这节解决知道会踩、不知道为什么踩的问题。每例按现象、根因、修复、防复发展开。案例一两个环境的状态 key 撞车现象qa 环境的 plan 输出显示要修改 prod 的资源apply 险些删掉别人的组件。根因三套环境的 backendkey写成了同一个固定值状态在桶里串台。修复改为按目录自动生成环境间天然隔离# ❌ 错误写法三套环境同一个 key状态直接串台 key app/tofu.tfstate # ✅ 正确写法按单元相对目录拆分 key ${path_relative_to_include()}/tofu.tfstate防复发评审规则里加一条backend 禁止出现与环境无关的绝对 keyCI 在合并前校验各环境 key 覆盖完整。案例二两个单元形成循环依赖现象run-all plan直接报 cycle 错误哪个单元都跑不起来。根因共享配置单元引用了 A 的 outputsA 又反过来引用共享配置的 outputs成环。修复把两者共用的部分抽到第三个单元让依赖变成单向。防复发每次 PR 合并前跑terragrunt graph-dependencies确认无环并把图贴进 PR 描述。案例三CI 与本地互相抢锁现象本地 plan 正常CI apply 报 state locked且偶发、难复现。根因本地和 CI 同时写同一状态锁表 TTL 短于实际执行时长。修复写操作入口统一收敛到 CI本地只允许 plan锁表 TTL 按真实执行时长调。防复发把状态写操作只从 CI 发起写进流程文档大体量状态按服务拆分缩小锁的作用面。规模化检查清单交付前的 9 项自查这节给你一份可以直接贴进 PR 描述的清单。全部勾完仓库才算能交给别人维护。配置所有单元的状态配置来自 include 链单元目录内零 backend 配置跨单元取值全部走 dependencygrep 不到硬编码的资源 ID共享配置root / _env只有单一来源不存在第三份拷贝状态状态桶开启版本化与加密锁表覆盖全部单元且未与其他项目共用权限provider 的 assume_role 按环境拆分CI 令牌为最小权限状态桶策略最小化plan 只读apply 才写流程PR 必须附run-all plan输出合并前跑graph-dependencies确认 DAG 无环今天就做一件事先跑terragrunt graph-dependencies看你当前的依赖图长什么样再对照四阶段定位卡在哪一步。深入细节可看 include 机制文档 与 状态后端文档。【免费下载链接】terragruntTerragrunt is a flexible orchestration tool that allows Infrastructure as Code written in OpenTofu/Terraform to scale.项目地址: https://gitcode.com/GitHub_Trending/te/terragrunt创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考