Terragrunt 根配置迁移指南从根terragrunt.hcl迁移到root.hcl【免费下载链接】terragruntTerragrunt is a flexible orchestration tool that allows Infrastructure as Code written in OpenTofu/Terraform to scale.项目地址: https://gitcode.com/GitHub_Trending/te/terragruntTerragrunt 曾推荐大型代码库使用根terragrunt.hcl 子目录terragrunt.hcl的双层结构但这一约定在实践中频繁引发混淆。本文以 Terragrunt 官方迁移文档为主线结合仓库源码系统讲解为什么弃用根terragrunt.hcl、如何重命名为root.hcl、如何更新find_in_parent_folders调用、如何用--root-file-name与--no-include-root控制 scaffold/catalog 生成行为以及如何通过root-terragrunt-hclstrict control 强制落地新规范。读完后你将能安全、无痛地将既有代码库迁移到新的根配置命名模式并为未来版本的行为变更做好准备。问题背景为什么根配置叫terragrunt.hcl不再合适长期以来官方推荐的最佳实践是在任何规模较大的代码库中维护两类terragrunt.hcl文件根terragrunt.hcl定义整个代码库所有 unit 共用的 Terragrunt 配置远程状态、provider 缓存、通用钩子等子目录terragrunt.hcl定义每个 unit 特有的配置。这一模式简单直观一眼就能看出文件用途都是 Terragrunt 配置并且部分 Terragrunt 特性如find_in_parent_folders默认就是按这种结构设计的。但随着代码库变大这套约定暴露了明显的弊端共享配置与单元配置难以区分从文件名上看根配置和子单元配置长得一模一样新用户经常分不清哪个是共享配置、哪个是某个单元自己的配置命令执行位置变得敏感类似run --all这样的命令必须从一个所有子目录都是待运行单元的目录执行否则 Terragrunt 可能把根terragrunt.hcl误当成单元配置功能上毫无收益从功能角度看把根配置命名为terragrunt.hcl并不会带来任何实际帮助反而徒增理解成本。仓库社区中也出现过相关混淆反馈对应 gruntwork-io/terragrunt 的 issue #3181。基于这些原因官方调整了推荐模式。推荐方案把根配置重命名为root.hcl新的推荐做法非常简单直接把根terragrunt.hcl重命名为其他文件名例如root.hcl。这样做的好处是不再需要小心翼翼地在特定目录下执行 Terragrunt 命令避免它误把根配置当成单元配置目录结构一目了然凡是叫terragrunt.hcl的就是可运行的单元root.hcl则是共享根配置减少run --all等命令的误用风险。从仓库源码也能看到这一新约定已被固化为常量。在 pkg/config/config.go 中定义了const ( DefaultTerragruntConfigPath terragrunt.hcl DefaultStackFile terragrunt.stack.hcl DefaultTerragruntJSONConfigPath terragrunt.hcl.json DefaultAutoIncludeFile inthclparse.AutoIncludeFile DefaultAutoIncludeStackFile inthclparse.AutoIncludeStackFile RecommendedParentConfigName root.hcl )其中RecommendedParentConfigName root.hcl表明root.hcl正是官方推荐的父级根配置文件名而terragrunt.hcl仅是单元的默认配置文件。配套更新修正find_in_parent_folders调用仅仅重命名文件还不够——任何假设根配置名为terragrunt.hcl的配置都需要同步更新。最常见的场景就是无参调用find_in_parent_folders()它的默认行为是向上查找名为terragrunt.hcl的文件因此必须显式传入新的根配置文件名。迁移前# /some/path/terragrunt.hcl include root { path find_in_parent_folders() }迁移后# /some/path/terragrunt.hcl include root { path find_in_parent_folders(root.hcl) }源码中同样印证了这一点。仓库自带的测试与脚手架生成逻辑都以带参数的形式使用该函数例如 internal/util/testdata/fixture-glob-canonical/module-b/module-b-child/terragrunt.hclinclude root { path find_in_parent_folders(root.hcl) }此外internal/cli/tf_binary_selection_test.go 的测试中同样使用find_in_parent_folders(root.hcl)构造被测场景可作为迁移后写法的参考范式。生成工具对齐scaffold 与 catalog 的根文件控制如果你使用 Scaffold 和 Catalog 自动生成新单元同样需要调整默认行为。过去可以安全地假设大多数用户使用根terragrunt.hcl因此默认生成的单元会向上查找terragrunt.hcl。迁移后这一假设不再成立。catalog和scaffold两个命令都提供了两个标志来显式控制新单元的生成方式标志作用--root-file-name 文件名指定新生成的单元将查找的根配置文件名称如root.hcl--no-include-root生成单元时完全不包含根 include即新单元不查找任何父级配置以catalog为例迁移前terragrunt catalog迁移后terragrunt catalog --root-file-name root.hcl这两个标志同样适用于scaffold命令例如生成一个不引用任何根配置的单元terragrunt scaffold MODULE_URL --no-include-root源码层面的实现依据在 internal/cli/flags/shared/scaffold.go 中定义了这两个标志的正式名称RootFileNameFlagName root-file-name NoIncludeRootFlagName no-include-root--root-file-name对应RootFileName变量--no-include-root对应NoIncludeRoot布尔变量二者均可通过环境变量TG_前缀注入。scaffold 的内置模板正是借助这些变量生成单元配置的。查看 internal/cli/commands/scaffold/scaffold.go 中的默认模板# This is a Terragrunt unit generated by Gruntwork Boilerplate (https://github.com/gruntwork-io/boilerplate). terraform { source {{ .sourceUrl }} } {{ if .EnableRootInclude }} include root { path find_in_parent_folders({{ .RootFileName }}) } {{ end }}可以看到模板把根 include 的开启与否EnableRootInclude与根文件名RootFileName都作为变量处理--no-include-root会关闭根 include--root-file-name则直接决定find_in_parent_folders查找的文件名。而在 internal/cli/commands/scaffold/scaffold.go 处RootFileName变量的默认值来自opts.ScaffoldRootFileName其初始值由--root-file-name标志提供若未提供catalog会调用scaffold.GetDefaultRootFileName计算默认值见 internal/cli/commands/catalog/cli.go。严格管控用root-terragrunt-hclstrict control 强制新规范为了在团队中强制执行新命名模式Terragrunt 提供了名为root-terragrunt-hcl的 strict control。启用后当 Terragrunt 检测到通过find_in_parent_folders引用根terragrunt.hcl文件时会直接报错。命令行方式terragrunt plan --strict-controlroot-terragrunt-hcl环境变量方式对目录内所有命令生效TG_STRICT_CONTROLroot-terragrunt-hcl terragrunt plan启用该 strict control 还有一个附加效果scaffold与catalog命令的默认根配置文件名会变为root.hcl未显式指定--root-file-name时。源码层面的实现依据在 internal/strict/controls/controls.go 中该 control 被定义为Control{ Name: RootTerragruntHCL, Description: Throw an error when users try to reference a root terragrunt.hcl file using find_in_parent_folders., Error: errors.New( Using terragrunt.hcl as the root of Terragrunt configurations is an anti-pattern, and no longer supported. Use a differently named file like root.hcl instead. ..., ), Warning: Using terragrunt.hcl as the root of Terragrunt configurations is an anti-pattern, and no longer recommended. In a future version of Terragrunt, this will result in an error. ..., }其中RootTerragruntHCL root-terragrunt-hclinternal/strict/controls/controls.go。Error字段是在启用 strict 模式时的报错文案Warning字段则是在未启用 strict 模式时的告警文案——对应下文将要介绍的当前警告、未来报错的过渡策略。未来行为警告如何演变为报错当前阶段当 Terragrunt 检测到旧模式时只会发出警告鼓励用户迁移到新模式但在未来版本中这一行为会变成显式报错。官方同时给出了明确的兼容性承诺考虑到这套模式沿用了很长时间用户会有非常充裕的时间完成迁移对大多数已正常工作的配置而言新旧模式的差异极小不会引起行为突变Terragrunt至少到 2.0 版本之前不会移除对旧模式的支持即便到了 2.0移除也会伴随漫长的警告期。因此对于存量代码库你可以从容地安排迁移节奏同时欢迎反馈迁移过程中遇到的问题以便官方优化过渡体验。常见问题FAQfind_in_parent_folders能否直接改用新的默认值例如root.hcl理论上可以但官方明确反对原因有四会造成即时破坏性变更用户仓库中可能同时存在root.hcl与terragrunt.hcl直接改默认值会导致 Terragrunt 找到错误的配置文件没有触及问题本质真正困扰新用户的不是默认值本身而是下面这段代码语义不透明include root { path find_in_parent_folders() }它没有告诉用户 Terragrunt 究竟会在父目录中查找什么隐藏的隐式回退值不是好模式与现有回退参数重复find_in_parent_folders的第二个参数本就支持回退值再为默认值引入另一种回退机制会造成混淆rootinclude 本无特殊含义从功能上讲root只是一个命名约定Terragrunt 并不强制要求提供根 include用户也可以拥有任意多个 include。显式要求写明根配置文件名正是为了让用户认真思考根配置是什么、里面该放什么。根配置命名为root.hcl一定更好吗root.hcl是推荐模式但并非强制要求。文档与示例均已切换到这一命名跟随该模式可以让你在编写配置时更容易照葫芦画瓢、与社区示例保持一致。有没有不该使用的根配置名称官方强烈建议不要使用任何以terragrunt开头的文件名作为根配置例如terragrunt.hcl或terragrunt.stack.hcl。虽然这并非正式保留字但 Terragrunt 目前仅有两个特殊文件名terragrunt.hcl—— 单元unit的默认配置文件terragrunt.stack.hcl—— 栈stack的默认配置文件。两者的定义均可在 pkg/config/config.go 中确认。使用以terragrunt开头的文件名会让用户误以为 Terragrunt 对该名称存在特殊行为从而再次引发混淆。迁移清单总结将根terragrunt.hcl重命名为root.hcl或其他非terragrunt前缀的名字全局搜索并更新所有find_in_parent_folders()无参调用改为find_in_parent_folders(root.hcl)更新 CI/脚本中任何依赖旧文件名的路径或逻辑若使用scaffold/catalog通过--root-file-name root.hcl指定新单元查找的根文件或用--no-include-root生成独立单元可选在 CI 或本地通过--strict-controlroot-terragrunt-hcl或TG_STRICT_CONTROL环境变量强制校验防止回归到旧模式保持关注版本更新留意告警升级为报错的时间点在 2.0 之前从容完成全部迁移。【免费下载链接】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），仅供参考