# Terragrunt 验证器 ## 概述此技能为 Terragrunt 配置提供全面的验证、检查和测试功能。 Terragrunt 是 Terraform/OpenTofu 的瘦包装器，它提供了额外的工具来保持配置 DRY（不要重复）、使用多个模块以及管理远程状态。 **在以下情况下使用此技能：** * 验证 Terragrunt HCL 文件（*.hcl、terragrunt.hcl、terragrunt.stack.hcl） * 使用 Terragrunt Stacks（单元/堆栈块，`terragrunt stack generated/run`） * 使用“terragrunt plan”执行空运行测试 * Linting Terragrunt/Terraform 代码以获得最佳实践 * 检测和研究自定义提供程序或模块 * 调试Terragrunt配置问题 * 检查依赖图 * 格式化HCL文件 * 对基础设施代码运行安全扫描（Trivy、Checkov） * 生成运行报告和摘要 ## Terragrunt 版本兼容性该技能是为 **Terragrunt 0.93+** 设计的，其中包括新的 CLI 重新设计。 ### CLI 命令迁移参考已弃用的命令 |新命令 ---|--- `运行所有` | `运行--全部` `hclfmt` | `hcl fmt` `hclvalidate` | `hcl 验证` `验证输入` | `hcl 验证--输入` `图依赖关系` | `有向图` `渲染-json` | `渲染--json -w` `terragrunt-info` | `信息打印` `计划所有`、`应用所有` | `运行--所有计划`、`运行--所有应用` ### 0.93+ 中的主要变化： * `terragrunt run --all` 替换了 `terragrunt run-all` 以进行多模块操作 * `terragrunt dag graph` 替换了 `terragrunt graph-dependencies` 以实现依赖关系可视化 * `terragrunt hcl validate --inputs` 替换了 `validate-inputs` 以进行输入验证 * 通过 `terragrunt hcl fmt --check` 或 `terragrunt hcl validate` 进行 HCL 语法验证 * 完整验证需要 `terragrunt init && terragrunt validate` 如果使用较旧的 Terragrunt 版本，某些命令可能需要调整。 ## 核心能力 ### 1\.综合验证套件运行综合验证脚本以立即执行所有检查： bash 脚本/validate_terragrunt.sh [TARGET_DIR] **它验证什么：** * HCL 格式化（`terragrunt hcl fmt --check`） * HCL 输入验证（`terragrunt hcl validate --inputs`） * Terragrunt配置语法 * Terraform配置验证 * 使用 tflint 进行 Linting * 使用 Trivy（或传统 tfsec）进行安全扫描 * 依赖图验证 * 试运行计划 **环境变量：** * `SKIP_PLAN=true` \- 跳过 terragrunt 计划步骤 * `SKIP_SECURITY=true` \- 跳过安全扫描 (Trivy/tfsec) * `SKIP_LINT=true` \- 跳过 tflint linting * `SKIP_INIT=true` \- 在验证之前跳过 `terragrunt init` * `SKIP_BACKEND_INIT=true` \- 使用 `-backend=false` 运行 init （在 CI/离线中有用） * `SOFT_FAIL_SECURITY=true` \- 报告安全结果而不失败 * `TG_STRICT_MODE=true` \- 启用严格模式（已弃用功能的错误） **使用示例：** # 全面验证 bash 脚本/validate_terragrunt.sh ./infrastruction/prod # 跳过计划生成（更快） SKIP_PLAN=true bash 脚本/validate_terragrunt.sh ./infrastructure # 仅验证，跳过 linting 和安全性 SKIP_LINT=true SKIP_SECURITY=true bash 脚本/validate_terragrunt.sh ### 2\.自定义提供程序和模块检测使用检测脚本来识别可能需要文档查找的自定义提供程序和模块： python3 脚本/detect_custom_resources.py [目录] [--format text|json] **它检测到的内容：** * 自定义 Terraform 提供商（非 HashiCorp） * 远程模块（Git、Terraform 注册表、HTTP） * 提供商版本 * 模块版本和来源 **输出格式：** * `text` \- 带有搜索建议的人类可读报告 * `json` \- 用于自动化的机器可读格式 **当检测到自定义资源时：** > **关键：您必须查找每个检测到的自定义资源（提供程序和模块）的文档。不要跳过任何一个。这是强制性的，不是可选的。** 1. **对于定制提供商：** * **选项 A - 网络搜索：** 搜索提供商文档 * 查询格式：`"{provider_source} terraform 提供者文档版本 {version}"` * 示例：`“mongodb/mongodbatlas terraform 提供程序文档版本 1.14.0”` * **选项 B - Context7 MCP（首选）：** 使用 Context7 进行结构化文档查找 * 步骤 1：解析库 ID：`mcp__context7__resolve-library-id` 和提供程序名称（例如，“datadog terraform 提供程序”） * 步骤 2：**必需** \- 通过 `mcp__context7__query-docs` 使用已解析的库 ID 获取文档 * 使用“身份验证要求”和“配置示例”等查询 2. **对于自定义模块（同样重要 - 不要跳过）：** * **Terraform 注册表模块：** * 使用 Context7: `mcp__context7__resolve-library-id` 和模块名称（例如，“terraform-aws-modules vpc”） * 然后使用`mcp__context7__query-docs`获取文档 * 或访问 `https://registry.terraform.io/modules/{source}/{version}` * **Git 模块：** 使用 WebSearch 和存储库 URL 来查找 README 或文档 * **HTTP 模块：** 调查文档的源 URL * 注意与您的 Terraform/Terragrunt 版本的版本兼容性 3. **文档查找工作流程（对于所有检测到的资源都是强制性的）：** a) 运行 detector_custom_resources.py b) 对于每个自定义提供程序/模块： - 请注意确切的版本 - 使用 Context7 MCP： 1. mcp__context7__resolve-library-id，库名称：“{provider/module name}” 2. mcp__context7__query-docs 包含： - 库ID：“{已解析的ID}” - 查询：“身份验证要求”（用于身份验证要求） 3. mcp__context7__query-docs 包含： - 库ID：“{已解析的ID}” - 查询：“配置示例”（用于设置要求） - 或者使用 WebSearch 进行特定于版本的查询 - 审查文档： * 所需的配置块 * 身份验证要求（API 密钥、凭据） * 可用资源/数据源 * 版本中的已知问题或重大更改 c) 将学到的知识应用于验证/故障排除 d) 如果遇到问题，记录结果 **使用 Context7 MCP 的示例：** # 1. 检测自定义资源 python3 脚本/detect_custom_resources.py ./infrastructure # 输出：提供者：datadog/datadog，版本：3.30.0 # 2.解析库ID mcp__context7__resolve-library-id 与库名称：“datadog terraform 提供程序” # 结果：/datadog/terraform-provider-datadog # 3. 获取身份验证文档（必需） mcp__context7__query-docs 包含：库 ID：“/datadog/terraform-provider-datadog” 查询：“身份验证要求” # 4. 获取配置文档 mcp__context7__query-docs 包含：库 ID：“/datadog/terraform-provider-datadog” 查询：“配置示例” **使用网络搜索的示例：** # 检测自定义资源 python3 脚本/detect_custom_resources.py ./infrastructure # 然后搜索文档： # WebSearch:“datadog terraform 提供程序 3.30.0 身份验证配置” # WebSearch:“datadog terraform 提供者 api_key app_key 设置” ### 3\.逐步验证对于手动或精细验证，请使用以下单独的命令： #### 格式验证 cd <目标目录> terragrunt hcl fmt --检查 # 自动修复格式泰拉格伦特盐酸盐 FMT #### 配置验证 # 检查 HCL 语法和格式 terragrunt hcl fmt --检查 # 注意：在 Terragrunt 0.93+ 中，为了进行更深入的配置验证， # 初始化和验证（需要实际资源/凭据）： # terragrunt 初始化 && terragrunt 验证 #### 地形验证 # 如果需要的话初始化地形初始化 # 验证地形验证 #### 使用 tflint 进行 Linting # 初始化 tflint（如果 .tflint.hcl 存在） tflint --init # 运行 linting tflint——递归 #### 使用 Trivy 进行安全扫描（推荐） > **注意：** tfsec 已合并到 Trivy 中，不再主动维护。将 Trivy 用于所有新项目。 # 使用 Trivy（推荐）琐碎的配置。 --严重性高、严重 # 使用 tfvars 文件琐碎的配置 --tf-vars terraform.tfvars 。 # 排除下载的模块琐碎的配置 --tf-exclude-downloaded-modules 。 # 旧版：使用 tfsec（已弃用） tfsec。 --软失败 #### 替代方案：使用 Checkov 进行安全扫描 # 扫描目录检查-d。 --框架地形 # 使用特定检查进行扫描检查-d。 --检查 CKV_AWS_21 # 输出为 JSON 检查-d。 --输出json #### 依赖图验证 # 注意：在 Terragrunt 0.93+ 中，graph-dependency 命令被替换为“dag graph” # 验证并显示依赖关系图 Terragrunt 有向图 # 可视化依赖关系（需要 graphviz） terragrunt dag 图|点-Tpng > 依赖项.png #### 试运行计划 # 单模块特拉格伦特计划 # 所有模块（新语法 - Terragrunt 0.93+） terragrunt run——所有计划 # 旧语法（已弃用） # terragrunt 运行所有计划 ### 4\.多模块操作对于具有多个 Terragrunt 模块的项目，请使用“run --all”（替换已弃用的“run-all”）： # 验证所有模块 terragrunt run --all 验证 # 规划所有模块 terragrunt run——所有计划 # 应用所有模块 terragrunt run --全部适用 # 销毁所有模块 terragrunt run --全部销毁 # 格式化所有 HCL 文件泰拉格伦特盐酸盐 FMT # 具有并行性 terragrunt run --all plan --parallelism 4 # 使用严格模式（已弃用功能的错误） terragrunt --严格模式运行 --所有计划 # 或者通过环境变量 TG_STRICT_MODE=true terragrunt run --all plan ### 5\. HCL 输入验证（0.93+ 中的新增功能）验证所有必需的输入均已设置并且不存在未使用的输入： # 验证输入 terragrunt hcl 验证--输入 # 显示无效文件的路径 terragrunt hcl 验证 --show-config-path # 与 run --all 结合使用以排除无效文件 terragrunt run --all plan --queue-excludes-file <(terragrunt hcl validate --show-config-path || true) ### 6\.严格模式启用严格模式以尽早捕获已弃用的功能： # 通过 CLI 标志 terragrunt --严格模式运行 --所有计划 # 通过环境变量（推荐用于 CI/CD）导出 TG_STRICT_MODE=true terragrunt run——所有计划 # 检查可用的严格控制 terragrunt 信息严格 **具体严格控制：** 对于更细粒度的控制，请使用“--strict-control”启用特定控制： # 启用特定的严格控制 terragrunt run --all plan --strict-control cli-redesign --strict-control deprecated-commands # 通过环境变量（逗号分隔） TG_STRICT_CONTROL='cli-redesign,deprecated-commands' terragrunt run --all plan # 可用的严格控制： # - cli-redesign：已弃用的 CLI 语法错误 # - deprecated-commands：已弃用命令的错误（run-all、hclfmt 等） # - root-terragrunt-hcl：使用 root terragrunt.hcl 时出错（请改用 root.hcl） # -skip-dependency-inputs：通过不读取依赖项输入来提高性能 # - bare-include：裸包含块上的错误（使用命名包含） ### 7\.新 CLI 命令 (0.93+) #### 渲染配置 # 将配置渲染为 JSON terragrunt 渲染 --json # 渲染并写入文件 terragrunt 渲染 --json --write # 输出到 terragrunt.rendered.json #### 信息打印（替换 terragrunt-info） # 获取当前配置的上下文信息地形信息打印 # 输出包括： # - 配置路径 # - 下载目录 # - terraform_binary # - 工作目录 #### 查找并列出单位 # 查找目录中的所有单元/堆栈特拉格兰特发现 # 输出为 JSON terragrunt 查找 --json # 包含依赖信息 terragrunt 查找 --json --dag # 列出单位（更简单的输出）地形列表 #### 运行摘要和报告 # 使用摘要输出运行（较新版本中的默认值） terragrunt run——所有计划 # 禁用摘要输出 terragrunt run --all plan --summary-disable # 生成详细的报告文件 terragrunt run --all plan --report-file=report.json # CSV 格式报告 terragrunt run --all plan --report-file=report.csv ### 8\. Terragrunt Stacks（v0.78.0+ 中的 GA） Terragrunt Stacks 使用“terragrunt.stack.hcl”文件提供声明性基础设施生成。 #### 堆栈文件结构 # terragrunt.stack.hcl 当地人{ 环境=“开发” aws_region = “us-east-1” } # 定义一个单位（生成单个 terragrunt.hcl）单位“vpc”{ 源 =“git::git@github.com:acme/infra-catalog.git//units/vpc?ref=v0.0.1” 路径=“vpc” 值={ 环境=本地.环境 cidr =“10.0.0.0/16” } } 单元“数据库”{ 源 =“git::git@github.com:acme/infra-catalog.git//units/database?ref=v0.0.1” 路径=“数据库” 值={ 环境=本地.环境 vpc_path =“../vpc” } } # 包括可重用的堆栈堆栈“监控”{ 源 =“git::git@github.com:acme/infra-catalog.git//stacks/monitoring?ref=v0.0.1” 路径=“监控” 值={ 环境=本地.环境 } } #### 堆栈命令 # 生成堆栈（创建 .terragrunt-stack 目录） terragrunt 堆栈生成 # 生成堆栈而不验证 terragrunt 堆栈生成 --no-stack-validate # 在所有堆栈单元上运行命令 terragrunt 堆栈运行计划 terragrunt 堆栈运行应用 # 清理生成的堆栈目录 terragrunt 堆栈清理 # 获取堆栈输出 terragrunt 堆栈输出 #### 堆栈验证控制使用“no_validation”属性跳过特定单位的验证：单位“实验”{ 来源 =“git::git@github.com:acme/infra-catalog.git//units/experimental?ref=v0.0.1” 路径=“实验” # 跳过此单元的验证（对于不完整/实验单元有用）无验证=真值={ 环境=本地.环境 } } #### 堆栈的好处 * **清理工作目录** ：在隐藏的`.terragrunt-stack`目录中生成代码 * **可重用模式** ：定义基础架构模式一次，部署多次 * **版本固定** : 不同的环境可以固定不同的版本 * **原子更新**：模块和配置的轻松回滚 ### 9\. Exec命令（运行任意程序） “exec”命令允许您针对具有 Terragrunt 上下文的单元运行任意程序。这对于将 tflint、checkov 或 AWS CLI 等其他工具与 Terragrunt 的配置集成非常有用。 # 使用单元上下文运行 tflint（TF_VAR_ env vars可用） terragrunt exec——tflint # 针对特定单元运行 checkov terragrunt exec -- checkov -d 。 # 使用单元配置运行 AWS CLI terragrunt exec -- aws s3 ls s3://my-bucket # 使用 Terragrunt 上下文运行自定义脚本 terragrunt exec -- ./scripts/validate_terragrunt.sh # 遍历所有单元 terragrunt run --all exec -- tflint **主要特点：** * Terragrunt 加载单元的输入并使它们可用作“TF_VAR_”前缀环境变量 * 适用于任何可以使用环境变量的程序 * 与 Terragrunt 的身份验证上下文集成（例如 AWS 配置文件） * 可以与`run --all`结合进行多单元操作 **使用案例：** * 使用单元上下文运行安全扫描仪（checkov、trivy） * 每单元执行 linter (tflint) * 使用正确的凭证运行操作命令 (AWS CLI) * 需要 Terragrunt 输入的自定义验证脚本 ### 10\.功能标志（生产功能） Terragrunt 支持一流的功能标志，以实现安全的基础设施更改。功能标志允许您无风险地集成不完整的工作，将发布与部署分离，并编纂 IaC 演进。 #### 定义功能标志 # terragrunt.hcl 功能“启用监控”{ 默认=假 } 功能“use_new_vpc”{ 默认=真 } 输入 = { 监控启用=功能.启用监控.值 vpc_version = feature.use_new_vpc.value ？ “v2”：“v1” } #### 通过 CLI 使用功能标志 # 启用功能标志 terragrunt 计划 --feature enable_monitoring=true # 启用多个功能标志 terragrunt 计划 --feature enable_monitoring=true --feature use_new_vpc=false # 通过环境变量 TG_FEATURE='enable_monitoring=true' terragrunt 计划 #### 带有 run --all 的功能标志 # 在所有单元上应用功能标志 terragrunt 运行 --all plan --feature enable_monitoring=true **好处：** * **安全部署**：测试基础设施子集的更改 * **逐步迁移**：逐步启用新功能 * **A/B 测试**：比较基础设施配置 * **紧急回滚** ：快速禁用有问题的功能 ### 11\.实验（选择加入不稳定的功能） Terragrunt 提供了一个实验系统，用于在不稳定的功能正式发布之前对其进行尝试： # 启用所有实验（不建议用于生产） terragrunt --实验模式运行 --所有计划 # 启用特定实验 terragrunt --实验符号链接运行 --所有计划 # 启用 CAS（内容可寻址存储）以加快克隆速度 terragrunt --experiment cas run --all 计划 **可用实验：** * `symlinks` \- 支持 Terragrunt 单位的符号链接解析 * `cas` \- 内容可寻址存储，用于更快的 Git/模块克隆 * `filter-flag` \- 高级过滤功能（1.0 中出现） ## 验证工作流程验证 Terragrunt 配置时请遵循以下工作流程： ### 规范可执行工作流程（默认路径）使用一个可执行路径，以便文档和脚本保持一致： # 主要验证 bash 脚本/validate_terragrunt.sh <目标目录> # 确定性夹具测试（脚本更改后需要） python3测试/test_detect_custom_resources.py bash 测试/test_validate_terragrunt.sh 执行期望： * 夹具测试应该是确定性的（稳定的通过/失败结果）。 * 验证/安全失败必须表现为非零退出。 ### 步骤 0：阅读最佳实践参考（强制第一步） > **您必须在开始验证之前阅读最佳实践参考文件。这不是可选的。** # 首先阅读最佳实践参考文件如果[-f引用/best_practices.md];那么猫参考/best_practices.md 否则 echo“警告：未找到引用/best_practices.md；继续使用下面的内置清单。” 菲这可确保您了解要验证的模式、反模式和清单。 ### 初步评估 1. **理解结构：** 树 -L 3 <基础设施目录> 2. **识别 Terragrunt 文件：** 找到。 -名称“*.hcl”-o -名称“terragrunt.hcl” 3. **检测自定义资源：** python3 脚本/detect_custom_resources.py 。 ### 文档查找（对于所有检测到的自定义资源都是强制的） > **重要：如果检测到任何自定义提供程序或模块，您必须查找每个提供程序或模块的文档。不要跳过任何一个。** 4. **对于每个检测到的自定义提供商 - 查找文档：** * 使用 Context7 MCP（首选）： 1. `mcp__context7__resolve-library-id` 以及提供者名称 2. `mcp__context7__query-docs` 带有查询：“身份验证要求” 3. `mcp__context7__query-docs` 带有查询：“配置示例” * 或使用网络搜索：`“{provider} terraform 提供程序 {version} 文档”` 5. **对于每个检测到的自定义模块 - 查找文档：** * 将 Context7 MCP 用于 Terraform 注册表模块： 1. 带有模块名称的 `mcp__context7__resolve-library-id`（例如，“terraform-aws-modules vpc”） 2. `mcp__context7__query-docs` 以及相关配置查询 * 对于 Git 模块：使用带有存储库 URL 的 WebSearch * 对于 HTTP 模块：调查文档的源 URL 6. **记录每项资源的调查结果：** * 所需的配置块 * 认证要求 * 版本中的已知问题或重大更改 ### 验证执行 7. **运行全面验证：** bash 脚本/validate_terragrunt.sh <目标目录> 8. **检查输出是否有错误：** * 格式错误 → 使用 `terragrunt hcl fmt` 修复 * 配置错误 → 检查 terragrunt.hcl 语法和输入 * Terraform 验证错误 → 检查 .tf 文件或生成的配置 * Linting 问题 → 检查 tflint 输出并修复 * 安全问题 → 查看 Trivy/Checkov/tfsec 输出和地址 * 依赖错误 → 检查依赖块和路径 * 计划错误 → 检查 Terraform 配置和提供程序设置 ### 最佳实践检查（必需 - 必须完成所有检查表） > **您必须验证下面的每个清单项目并记录结果（✅ 通过或 ❌ 失败）。不完整的验证是不可接受的。** 9. **使用`references/best_practices.md`执行明确的最佳实践验证：** **配置模式清单 - 验证每一项：** [ ] 包含块：子模块使用 `include "root" { path = find_in_parent_folders("root.hcl") }` [ ] 命名包含：所有包含块都有名称（不是裸露的“include {}”） [ ] 根文件命名：根配置名为“root.hcl”（而不是“terragrunt.hcl”） [ ] 环境配置：名为“env.hcl”的环境级配置（不是“terragrunt.hcl”） [ ] 公共变量：通过 `read_terragrunt_config()` 读取 `common.hcl` 中的共享变量 **依赖管理清单：** [ ] 模拟输出：所有依赖块都有用于验证的模拟输出 [ ] 模拟允许的命令：mock_outputs_allowed_terraform_commands 包括 ["validate", "plan", "init"] [ ] 显式路径：依赖项 config_path 使用相对路径（“../vpc”不是绝对路径） [ ] 无循环依赖：运行 `terragrunt dag graph` 来验证没有循环 **安全检查表：** [ ] 状态加密：remote_state 配置有 `encrypt = true` [ ] 状态锁定：为 S3 后端配置的 DynamoDB 表 [ ] 无硬编码凭据：搜索“AKIA”、“password =”、帐户 ID 等模式 [ ] 敏感变量：密码/密钥在变量块中使用 `sensitive = true` [ ] IAM角色：提供商使用assume_role而不是静态凭证 **DRY 原则清单：** [ ] 生成块：提供程序和后端配置使用“生成”块 [ ] 版本约束：terragrunt_version_constraint 和 terraform_version_constraint 设置 [ ] 可重用的局部变量：共享文件中的通用值，不重复 [ ] if_exists：使用适当的 if_exists 策略生成块 **快速 grep 检查运行：** # 检查硬编码的 AWS 账户 ID grep -r "[0-9]\{12\}" --include="*.hcl" 。 | grep -v 模拟 # 检查潜在的凭据 grep -ri“密码\s*=”--include=“*.hcl”。 grep -ri "api_key\s*=" --include="*.hcl" 。 # 检查没有mock_outputs的依赖关系 grep -l "dependency\s" --include="*.hcl" -r 。 | xargs grep -L "mock_outputs" # 检查非模块目录中的 terragrunt.hcl 文件（反模式）找到。 -名称“terragrunt.hcl”-不是-路径“*/.terragrunt-cache/*”|头-20 ### 故障排除 10. **常见问题和解决方案：** **问题：找不到模块** rm -rf .terragrunt 缓存地形初始化 **问题：提供商身份验证错误** * 检查生成文件中的提供者配置 * 验证环境变量或凭据 * 从 WebSearch 查看提供商文档 **问题：依赖错误** * 检查依赖路径是否正确 * 确保提供mock_outputs用于验证 * 使用“terragrunt dag graph”查看依赖关系图 **问题：状态锁定错误** terragrunt 强制解锁 **问题：S3 后端 `dynamodb_table` 弃用警告** * 最近的 Terraform 版本可能会警告 S3 后端已弃用“dynamodb_table”。 * 当与您的工作流程兼容时，在后端配置中首选 `use_lockfile = true`。 * 仅保留“dynamodb_table”以满足旧版兼容性需求。 **问题：未知的提供程序或模块参数** * 重新运行自定义资源检测 * 使用 WebSearch 查找当前文档 * 检查版本兼容性 **问题：生成块冲突（文件已存在）** 错误：文件路径 ./versions.tf 已存在，并且不是由 terragrunt 生成的。无法生成 terraform 文件：./versions.tf 已存在 **解决方案：** 当存在与 Terragrunt 的“generate”块冲突的静态“.tf”文件时，就会发生这种情况。任何一个： * 删除冲突的静态文件（`versions.tf`、`provider.tf`、`backend.tf`） * 或者在生成块中使用 `if_exists = "skip"` 来不覆盖现有文件 # 删除冲突的文件 rm -f 版本.tf 提供者.tf 后端.tf rm -rf .terragrunt 缓存 **问题：根 terragrunt.hcl 反模式警告** 警告：使用 `terragrunt.hcl` 作为 Terragrunt 配置的根是一种反模式 **解决方案：** 在 Terragrunt 0.93+ 中，根配置文件应命名为 `root.hcl` 而不是 `terragrunt.hcl`。重命名文件： mv terragrunt.hcl root.hcl # 更新子模块中的 include 块以引用 root.hcl ## 最佳实践集成请参阅综合最佳实践指南以获取详细建议： # 阅读最佳实践参考如果[-f引用/best_practices.md];那么猫参考/best_practices.md 否则 echo“警告：未找到references/best_practices.md；继续查看本文档中的清单。” 菲 **要检查的关键最佳实践：** * ✅ 使用 `include` 进行共享配置 * ✅ 为依赖项提供mock_outputs * ✅ 使用“generate”块进行提供者配置 * ✅ 启用状态加密和锁定 * ✅ 使用环境变量作为动态值 * ✅ 指定版本限制 * ✅ 避免硬编码值 * ✅ 使用有意义的目录结构 * ✅ 启用安全功能（加密、IAM 角色） **验证时，检查反模式：** * ❌ 硬编码凭据或帐户 ID * ❌ 缺少模拟输出 * ❌ 目录嵌套过深 * ❌ 跨模块的重复配置 * ❌ 缺少版本限制 * ❌ 未加密状态请参阅“references/best_practices.md”以获取完整示例和详细指南。 ## 工具要求 **必填：** * terragrunt（新 CLI 建议 >= 0.93.0） * terraform 或 opentofu (推荐 >= 1.6.0) **可选但推荐：** * tflint - HCL linting * trivy - 安全扫描（取代 tfsec） * checkov - 替代安全扫描器（750+ 内置策略） * graphviz (dot) - 依赖关系可视化 * jq - JSON解析 * python3 - 用于自定义资源检测脚本 **已弃用的工具：** * tfsec - 合并到 Trivy，不再积极维护 **安装命令：** # macOS 酿造安装terragrunt terraform tflint trivy graphviz jq # 安装 Trivy（推荐安全扫描仪）酿造安装琐事 # 安装 Checkov（替代安全扫描器） pip3 安装 checkov # 旧版 tfsec（已弃用 - 使用 trivy 代替） #brew 安装 tfsec # Linux - Trivy 卷曲-sfL https://raw.githubusercontent.com/aquasecurity/trivy/main/contrib/install.sh | sh -s -- -b /usr/local/bin # Linux - 检查 pip3 安装 checkov # 验证安装 terragrunt --版本琐碎的版本检查--版本 ## 与 Context7 MCP 集成如果 Context7 MCP 可用，请将其用于提供程序/模块文档查找： 1. **解析库ID：** mcp__context7__resolve-library-id 与库名称：“mongodb/mongodbatlas” 2. **查询文档：** mcp__context7__query-docs ，库 ID：“/mongodb/mongodbatlas”和查询：“身份验证要求” 这直接提供了版本感知文档，作为 WebSearch 的替代方案。 ## 自动化工作流程 ### CI/CD 集成使用确定性技能级别 CI 门作为阻塞检查： bash 脚本/run_ci_checks.sh --require-shellcheck 该门运行： * Shell 语法检查（`bash -n`） * Python语法检查（`python3 -m py_compile`） * Python 回归测试 (`test/test_detect_custom_resources.py`) * Shell 回归测试 (`test/test_validate_terragrunt.sh`) * ShellCheck linting（当设置 `--require-shellcheck` 时，CI 中需要）该门通过后，在配置了 Terragrunt/Terraform 凭据的作业中运行依赖于环境的验证： #!/bin/bash # ci-validate.sh 设置-euo管道故障 echo“正在运行确定性验证器检查...” bash 脚本/run_ci_checks.sh --require-shellcheck echo“正在安装依赖项...” # 安装 terragrunt、terraform、tflint、trivy/checkov echo“正在检测自定义资源...” python3 脚本/detect_custom_resources.py 。 --格式化 json > 自定义资源.json # 可以在此处与自动文档查找集成 echo“正在运行验证套件...” SKIP_PLAN=true SKIP_BACKEND_INIT=true bash 脚本/validate_terragrunt.sh 。 echo “验证完成！” ### 预提交挂钩用于本地开发的预提交挂钩示例： #!/bin/bash # .git/hooks/预提交 # 格式检查 terragrunt hcl fmt --检查 || { echo“发现 HCL 格式问题。运行：terragrunt hcl fmt” 1号出口 } # 快速 HCL 语法验证 (Terragrunt 0.93+) # 注意：要进行完整验证，请使用：terragrunt init && terragrunt validate # 但这需要凭据。 HCL 格式检查捕获语法错误。 echo "预提交验证通过！" ## 故障排除指南 ### 验证模式和退出语义 `validate_terragrunt.sh` 从目标目录派生模式并相应地更改 Terragrunt 命令路径：模式|目录形状| Terragrunt HCL 检查 |地形检查 |退出语义 ---|---|---|---|--- `单身` |目标目录中的`terragrunt.hcl`（或`terragrunt.stack.hcl`）| `terragrunt hcl 验证` | `terragrunt validate`（除非跳过，否则与 `terragrunt init` 一起使用）|任何语法/验证失败都会以非零值退出 `多` |嵌套单元存在于目标 | 下方`terragrunt hcl validate --all` （如果不支持 `--all`，则回退到普通的 `hcl validate`）| `terragrunt run --all validate` （除非跳过，否则使用 `run --all init`）|任何单元故障均以非零值退出 `仅限 root` |仅 `root.hcl`，目标目录中没有单元 |警告并跳过 |警告并跳过 |对于这些跳过的步骤返回成功 (0) `无` |没有可识别的 Terragrunt 配置文件 |错误 |错误 |返回非零值 ### 调试模式启用调试输出以进行故障排除： # Terragrunt 调试 TERRAGRUNT_DEBUG=1 terragrunt 计划 # 地形跟踪 TF_LOG=TRACE terragrunt 计划 ### 常见错误模式 **“错误：找不到模块”** * 清除缓存：`rm -rf .terragrunt-cache` * 重新初始化：`terragrunt init` **“错误：找不到提供者”** * 检查提供商配置 * 运行自定义资源检测 * 使用 WebSearch 查找正确的提供商源和版本 * 验证required_providers块 **“错误：无效的函数调用”** * 检查 Terragrunt 版本兼容性 * 查看文档中的函数语法 **“在依赖图中检测到循环”** *审查依赖链 * 考虑重构为单个模块 * 使用数据源而不是依赖项 **“获取状态锁时出错”** * 检查是否有其他进程正在运行 * 验证 DynamoDB 表（针对 S3 后端） * 如果安全则强制解锁：`terragrunt 强制解锁 ` **“错误：未知命令”（Terragrunt 0.93+）** * Terragrunt 0.93+ 有一个新的 CLI，其中包含重大更改 * 不推荐使用“render-json”、“validate-inputs”等命令 * 对自定义/不支持的命令使用 `terragrunt run -- ` * 将“graph-dependency”替换为“dag graph” * 请参阅： ## 输出解释 ### 成功指标 ✅ **所有检查均通过：** * 所有 HCL 文件格式正确 * 输入有效 * Terraform 配置有效 * 无掉毛问题 * 没有严重的安全问题 * 有效的依赖图 * 计划生成成功 ### 警告指示器 ⚠️ **需要审核：** * 来自 Trivy/Checkov/tfsec 的安全警告（非关键） * Linting 建议（最佳实践） * 已弃用的提供商功能 * 缺少推荐配置 ### 错误指示器 ✗ **必须修复：** * 格式错误 * 无效输入 * Terraform验证失败 * 循环依赖 * 提供者身份验证失败 * 状态锁定错误 ## 高级用法 ### 自定义验证规则通过添加 `.tflint.hcl` 创建自定义 tflint 规则：插件“terraform”{ 启用=真预设=“推荐” } 插件“aws”{ 启用=真版本=“0.27.0” 来源=“github.com/terraform-linters/tflint-ruleset-aws” } 规则“terraform_naming_convention”{ 启用=真 } ### 自定义安全策略通过添加“.tfsec/config.yml”创建自定义 tfsec 策略：最低严重性：中排除： - AWS001 # 示例：排除特定规则 ### 依赖图分析分析复杂的依赖链： # 生成详细图表（Terragrunt 0.93+ 语法） terragrunt dag 图 > graph.dot # 转换为视觉格式点 -Tpng graph.dot > graph.png 点-Tsvg graph.dot > graph.svg # 分析循环依赖 grep -A5 "循环" <(terragrunt dag graph 2>&1) ## 资源 ### 脚本 * `scripts/validate_terragrunt.sh` \- 综合验证套件 * `scripts/detect_custom_resources.py` \- 自定义提供程序/模块检测器 ### 参考文献 * `references/best_practices.md` \- 综合最佳实践指南，涵盖： * 目录结构模式 * DRY原理及配置分享 * 依赖管理 * 安全最佳实践 * 测试和验证工作流程 * 要避免的常见反模式 * 故障排除指南 ### 外部文档 * [Terragrunt 文档]() * [Terraform 最佳实践]() * [Terraform 注册表]() ## 完成标准 * 文档和脚本就一种规范的可执行工作流程达成一致。 * 夹具运行通过以下方式确定： * `python3 测试/test_detect_custom_resources.py` * `bash 测试/test_validate_terragrunt.sh` * 通过正确的非零退出来报告验证和安全失败。

Terragrunt 验证器

包含技能