Terragrunt 入门指南用一个 terragrunt.hcl 文件搞定多环境基础设施编排【免费下载链接】terragruntTerragrunt is a flexible orchestration tool that allows Infrastructure as Code written in OpenTofu/Terraform to scale.项目地址: https://gitcode.com/GitHub_Trending/te/terragrunt假设你同时维护 dev、staging、prod 三套环境每套都要部署 VPC、数据库和应用。今天你要改一下所有环境的 tags于是打开六个terragrunt.hcl逐个粘贴修改改到第三个时开始怀疑人生。这正是 Terragrunt 想解决的处境它不是 Terraform 的替代品而是一套基础设施编排层——把每个terragrunt.hcl看作一个单元让环境差异只写一行其余配置统一复用并自动按依赖顺序批量执行。它帮你省掉了什么Terragrunt 站在 OpenTofu/Terraform 之上做三件事配置复用、状态管理、批量编排。它值得用的原因可以归纳为三点配置只写一遍根配置通过include注入到每个单元环境间差异只剩几个输入值多环境部署不再是复制粘贴工程。状态自动托管远程状态的 bucket、锁表由 Terragrunt 自动创建并加密告别控制台手工点选。批量执行有顺序单元间依赖被解析成有向无环图DAGrun --all会先跑被依赖方、再跑依赖方同组内并发。三步装好并跑通第一条命令这一节给你一条最短路径安装 → 建一个最小单元 → 看到hi.txt被创建。# 1. 安装macOS/Linux curl -sSfL --proto https --tlsv1.2 https://terragrunt.com/install | bash terragrunt --version # 确认安装成功在任意已有 OpenTofu/Terraform 项目的目录里建一个空的terragrunt.hcl这个项目就被 Terragrunt 接管了touch terragrunt.hcl terragrunt apply -auto-approve # 不需要先手动跑 init官方快速上手里有一个不依赖云账号的最小示例main.tf里只放一个local_file资源跑完apply会在缓存目录里生成hi.txt。输出比较啰嗦是正常现象那是 Terragrunt 在替你处理源码下载、代码生成和 init想要清爽输出可以加--log-format bare。terragrunt find列出当前项目里的堆栈绿色与单元蓝色一眼看清编排范围三个核心机制白话版这一节只讲最关键的三个机制每个配一个类比和一段真实配置。单元与堆栈 ≈ 文件与文件夹类比单元unit就是一个含terragrunt.hcl的目录相当于一份独立状态的基础设施实例堆栈stack是相关单元的集合通常对应一个环境。# foo/terragrunt.hcl terraform { source ../shared # 指向共享模块单元目录里不用写 .tf } inputs { content Hello from foo # 动态注入模块变量 }配置复用 ≈ 模板继承类比根目录的root.hcl是父类每个单元的terragrunt.hcl通过include继承它改一处全局生效。# root.hcl remote_state { backend s3 config { bucket my-tofu-state key ${path_relative_to_include()}/tofu.tfstate # 每个单元状态 key 自动不同 } }# app/terragrunt.hcl include root { path find_in_parent_folders(root.hcl) # 自动向上找父目录的 root.hcl }依赖解析 ≈ 拓扑排序类比Terragrunt 扫描所有dependency块把单元排成先跑谁后跑谁的分组无依赖的单元同组并发。# bar/terragrunt.hcl dependency foo { config_path ../foo # 声明 bar 依赖 foo执行顺序自动排前 } inputs { content Foo content: ${dependency.foo.outputs.content} }依赖图直观展示单元之间的先后关系run --all会按此拓扑顺序执行高频场景模式这一节按遇到什么场景就怎么做来查配置均取自官方文档。场景一后端配置在每个 .tf 里复制OpenTofu 的backend块不支持变量和函数多模块下只能粘贴。用remote_state块写一次Terragrunt 会生成backend.tf并且自动创建缺失的 S3 桶和 DynamoDB 锁表带版本控制、加密、访问日志remote_state { backend s3 generate { path backend.tf, if_exists overwrite } config { bucket my-terraform-state key ${path_relative_to_include()}/terraform.tfstate dynamodb_table my-lock-table } }场景二B 单元需要 A 单元的输出写dependency块即可输出通过dependency.foo.outputs.xxx引用。若 A 还没 apply 过plan阶段会报no outputs补一个mock_outputs占位值就能跑通dependency foo { config_path ../foo mock_outputs { content placeholder } # plan 阶段占位 mock_outputs_allowed_terraform_commands [plan] # 仅在 plan 时用 mock }场景三一批单元要统一执行在堆栈根目录执行无需逐个cdterragrunt run --all plan terragrunt run --all --non-interactive apply场景四只想动其中几个单元--filter支持路径、名称、属性、依赖图、Git 差异等多种表达式先 dry-run 再执行terragrunt find --filter ./prod/** | nameweb # 先确认命中范围 terragrunt run --filter ./prod/** | nameweb apply场景五apply 前后要跑脚本before_hook/after_hook/error_hook挂在terraform块内按命令匹配触发terraform { before_hook notify { commands [apply] execute [echo, Starting apply] } }目录与配置蓝图这一节给一棵可直接照抄的目录树和对应的根配置。命名规则照搬官方文档_env前缀放跨环境但只对某服务有效的公共配置。live/ ├── root.hcl # 全局状态后端、provider 生成 ├── _env/ # 服务级公共配置下划线前缀表示不可直接部署 │ ├── app.hcl │ └── vpc.hcl ├── dev/ │ ├── vpc/terragrunt.hcl │ ├── db/terragrunt.hcl │ └── app/terragrunt.hcl └── prod/ ├── vpc/terragrunt.hcl ├── db/terragrunt.hcl └── app/terragrunt.hcl单元侧只需保留差异部分# prod/app/terragrunt.hcl include root { path find_in_parent_folders(root.hcl) } terraform { source gitcode.example.com:org/modules.git//app?refv0.1.0 } dependency vpc { config_path ../vpc } inputs { env prod # 唯一的环境差异项 vpc_id dependency.vpc.outputs.vpc_id }root.hcl里除了remote_state还常用generate块注入 provider 配置比如 AWS 的assume_role写法见 状态后端文档。避坑问答现象一plan报 is a dependency but detected no outputs原因依赖单元尚未 apply状态里还没有输出可读。解法如上所述补mock_outputs如果只需要执行顺序而不需要输出改用只声明顺序的dependencies块。现象二忘记手动init或觉得每次都要跑init很烦原因Terragrunt 实际在.terragrunt-cache目录里执行 OpenTofu后端配置是运行时生成的。解法什么都不用做——Auto-init 会在需要时自动执行init直接apply即可。现象三backend.tf、.terragrunt-cache被提交进仓库原因这两个都是运行产物。解法写入.gitignore缓存目录可随时删除Terragrunt 会重建。现象四CI 里跑apply时又弹确认提示卡死流水线原因破坏性命令默认交互式确认。解法加--non-interactive标志。上线前 Checklist这一节可以直接贴在 PR 模板里逐项勾选Terragrunt 版本已用工具管理器mise/asdf .tool-versions锁定本地与 CI 一致每个单元的状态 key 用path_relative_to_include()区分互不覆盖状态桶开启加密与版本控制锁表DynamoDB 或 lockfile已配置依赖未 apply 时的plan已验证可跑通mock_outputs 就位terragrunt run --all前先用terragrunt find --filter核对命中范围.terragrunt-cache与生成文件已加入.gitignoreCI 采用PR 上 plan、合并后 apply的流程apply 带--non-interactive团队约定hcl validate通过后才能合并plan 输出按单元回显到 PR 评论评审时可以直接看到每个单元要增改多少资源收尾Terragrunt 的价值不在于单条命令有多强而在于单元 堆栈 DAG这套结构把多环境基础设施收敛成了可查询、可排序、可批量执行的对象。建议从两个单元起步先用include消除重复再引入dependency和run --all最后把整条链路搬进 CI。按这个顺序走每一步都有明确收益也能随时停下来。延伸阅读仓库内路径快速上手教程从零搭一个两单元 DAG 的完整示例Includes 配置复用多层 include 的完整写法Filter 过滤语法路径、属性、Git 差异等全部过滤表达式【免费下载链接】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），仅供参考 Terragrunt 入门指南：用一个 terragrunt.hcl 文件搞定多环境基础设施编排
Terragrunt 入门指南用一个 terragrunt.hcl 文件搞定多环境基础设施编排【免费下载链接】terragruntTerragrunt is a flexible orchestration tool that allows Infrastructure as Code written in OpenTofu/Terraform to scale.项目地址: https://gitcode.com/GitHub_Trending/te/terragrunt假设你同时维护 dev、staging、prod 三套环境每套都要部署 VPC、数据库和应用。今天你要改一下所有环境的 tags于是打开六个terragrunt.hcl逐个粘贴修改改到第三个时开始怀疑人生。这正是 Terragrunt 想解决的处境它不是 Terraform 的替代品而是一套基础设施编排层——把每个terragrunt.hcl看作一个单元让环境差异只写一行其余配置统一复用并自动按依赖顺序批量执行。它帮你省掉了什么Terragrunt 站在 OpenTofu/Terraform 之上做三件事配置复用、状态管理、批量编排。它值得用的原因可以归纳为三点配置只写一遍根配置通过include注入到每个单元环境间差异只剩几个输入值多环境部署不再是复制粘贴工程。状态自动托管远程状态的 bucket、锁表由 Terragrunt 自动创建并加密告别控制台手工点选。批量执行有顺序单元间依赖被解析成有向无环图DAGrun --all会先跑被依赖方、再跑依赖方同组内并发。三步装好并跑通第一条命令这一节给你一条最短路径安装 → 建一个最小单元 → 看到hi.txt被创建。# 1. 安装macOS/Linux curl -sSfL --proto https --tlsv1.2 https://terragrunt.com/install | bash terragrunt --version # 确认安装成功在任意已有 OpenTofu/Terraform 项目的目录里建一个空的terragrunt.hcl这个项目就被 Terragrunt 接管了touch terragrunt.hcl terragrunt apply -auto-approve # 不需要先手动跑 init官方快速上手里有一个不依赖云账号的最小示例main.tf里只放一个local_file资源跑完apply会在缓存目录里生成hi.txt。输出比较啰嗦是正常现象那是 Terragrunt 在替你处理源码下载、代码生成和 init想要清爽输出可以加--log-format bare。terragrunt find列出当前项目里的堆栈绿色与单元蓝色一眼看清编排范围三个核心机制白话版这一节只讲最关键的三个机制每个配一个类比和一段真实配置。单元与堆栈 ≈ 文件与文件夹类比单元unit就是一个含terragrunt.hcl的目录相当于一份独立状态的基础设施实例堆栈stack是相关单元的集合通常对应一个环境。# foo/terragrunt.hcl terraform { source ../shared # 指向共享模块单元目录里不用写 .tf } inputs { content Hello from foo # 动态注入模块变量 }配置复用 ≈ 模板继承类比根目录的root.hcl是父类每个单元的terragrunt.hcl通过include继承它改一处全局生效。# root.hcl remote_state { backend s3 config { bucket my-tofu-state key ${path_relative_to_include()}/tofu.tfstate # 每个单元状态 key 自动不同 } }# app/terragrunt.hcl include root { path find_in_parent_folders(root.hcl) # 自动向上找父目录的 root.hcl }依赖解析 ≈ 拓扑排序类比Terragrunt 扫描所有dependency块把单元排成先跑谁后跑谁的分组无依赖的单元同组并发。# bar/terragrunt.hcl dependency foo { config_path ../foo # 声明 bar 依赖 foo执行顺序自动排前 } inputs { content Foo content: ${dependency.foo.outputs.content} }依赖图直观展示单元之间的先后关系run --all会按此拓扑顺序执行高频场景模式这一节按遇到什么场景就怎么做来查配置均取自官方文档。场景一后端配置在每个 .tf 里复制OpenTofu 的backend块不支持变量和函数多模块下只能粘贴。用remote_state块写一次Terragrunt 会生成backend.tf并且自动创建缺失的 S3 桶和 DynamoDB 锁表带版本控制、加密、访问日志remote_state { backend s3 generate { path backend.tf, if_exists overwrite } config { bucket my-terraform-state key ${path_relative_to_include()}/terraform.tfstate dynamodb_table my-lock-table } }场景二B 单元需要 A 单元的输出写dependency块即可输出通过dependency.foo.outputs.xxx引用。若 A 还没 apply 过plan阶段会报no outputs补一个mock_outputs占位值就能跑通dependency foo { config_path ../foo mock_outputs { content placeholder } # plan 阶段占位 mock_outputs_allowed_terraform_commands [plan] # 仅在 plan 时用 mock }场景三一批单元要统一执行在堆栈根目录执行无需逐个cdterragrunt run --all plan terragrunt run --all --non-interactive apply场景四只想动其中几个单元--filter支持路径、名称、属性、依赖图、Git 差异等多种表达式先 dry-run 再执行terragrunt find --filter ./prod/** | nameweb # 先确认命中范围 terragrunt run --filter ./prod/** | nameweb apply场景五apply 前后要跑脚本before_hook/after_hook/error_hook挂在terraform块内按命令匹配触发terraform { before_hook notify { commands [apply] execute [echo, Starting apply] } }目录与配置蓝图这一节给一棵可直接照抄的目录树和对应的根配置。命名规则照搬官方文档_env前缀放跨环境但只对某服务有效的公共配置。live/ ├── root.hcl # 全局状态后端、provider 生成 ├── _env/ # 服务级公共配置下划线前缀表示不可直接部署 │ ├── app.hcl │ └── vpc.hcl ├── dev/ │ ├── vpc/terragrunt.hcl │ ├── db/terragrunt.hcl │ └── app/terragrunt.hcl └── prod/ ├── vpc/terragrunt.hcl ├── db/terragrunt.hcl └── app/terragrunt.hcl单元侧只需保留差异部分# prod/app/terragrunt.hcl include root { path find_in_parent_folders(root.hcl) } terraform { source gitcode.example.com:org/modules.git//app?refv0.1.0 } dependency vpc { config_path ../vpc } inputs { env prod # 唯一的环境差异项 vpc_id dependency.vpc.outputs.vpc_id }root.hcl里除了remote_state还常用generate块注入 provider 配置比如 AWS 的assume_role写法见 状态后端文档。避坑问答现象一plan报 is a dependency but detected no outputs原因依赖单元尚未 apply状态里还没有输出可读。解法如上所述补mock_outputs如果只需要执行顺序而不需要输出改用只声明顺序的dependencies块。现象二忘记手动init或觉得每次都要跑init很烦原因Terragrunt 实际在.terragrunt-cache目录里执行 OpenTofu后端配置是运行时生成的。解法什么都不用做——Auto-init 会在需要时自动执行init直接apply即可。现象三backend.tf、.terragrunt-cache被提交进仓库原因这两个都是运行产物。解法写入.gitignore缓存目录可随时删除Terragrunt 会重建。现象四CI 里跑apply时又弹确认提示卡死流水线原因破坏性命令默认交互式确认。解法加--non-interactive标志。上线前 Checklist这一节可以直接贴在 PR 模板里逐项勾选Terragrunt 版本已用工具管理器mise/asdf .tool-versions锁定本地与 CI 一致每个单元的状态 key 用path_relative_to_include()区分互不覆盖状态桶开启加密与版本控制锁表DynamoDB 或 lockfile已配置依赖未 apply 时的plan已验证可跑通mock_outputs 就位terragrunt run --all前先用terragrunt find --filter核对命中范围.terragrunt-cache与生成文件已加入.gitignoreCI 采用PR 上 plan、合并后 apply的流程apply 带--non-interactive团队约定hcl validate通过后才能合并plan 输出按单元回显到 PR 评论评审时可以直接看到每个单元要增改多少资源收尾Terragrunt 的价值不在于单条命令有多强而在于单元 堆栈 DAG这套结构把多环境基础设施收敛成了可查询、可排序、可批量执行的对象。建议从两个单元起步先用include消除重复再引入dependency和run --all最后把整条链路搬进 CI。按这个顺序走每一步都有明确收益也能随时停下来。延伸阅读仓库内路径快速上手教程从零搭一个两单元 DAG 的完整示例Includes 配置复用多层 include 的完整写法Filter 过滤语法路径、属性、Git 差异等全部过滤表达式【免费下载链接】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），仅供参考