terragrunt-generator

Terragrunt 生成器

概述

遵循当前最佳实践、命名约定和安全标准，生成可用于生产环境的 Terragrunt 配置。所有生成的配置都会自动验证。

触发短语

用户提出以下需求时，请使用此技能：

• 新建 root.hcl、terragrunt.hcl 或 terragrunt.stack.hcl
• 多环境 Terragrunt 布局（dev/staging/prod）
• 配置 Terragrunt 依赖项（dependency 或 dependencies 块）
• 设置 Terragrunt 模块源（本地、Git、通过 tfr:/// 使用 Terraform Registry）
• 在 catalog/units/* 下生成 Stack 目录单元

支持的 Terragrunt 2025 功能：

• Stacks - 使用 terragrunt.stack.hcl 的基础设施蓝图（自 v0.78.0 起正式发布）
• Feature Flags - 通过 feature 块进行运行时控制
• Exclude Blocks - 精细控制执行（取代已弃用的 skip）
• Errors Blocks - 高级错误处理（取代已弃用的 retryable_errors）
• OpenTofu Engine - 支持替代 IaC 引擎

根配置命名

推荐： 根据迁移指南，根文件使用 root.hcl，而不是 terragrunt.hcl。

方式	根文件	Include 语法
现代	root.hcl	find_in_parent_folders("root.hcl")
旧版	terragrunt.hcl	find_in_parent_folders()

Include 标准： 所有新示例和生成的配置默认使用 find_in_parent_folders("root.hcl")。仅当明确针对名为 terragrunt.hcl 的旧版根文件时，才使用 find_in_parent_folders()。

架构模式

关键： 生成任何配置之前，必须确定架构模式并了解其限制。

模式 A：使用环境无关根配置的多环境

适用场景： 使用共享根配置管理多个环境（dev/staging/prod）。

核心原则： root.hcl 与环境无关——它不会读取特定环境的文件。

infrastructure/
├── root.hcl              # Environment-AGNOSTIC (no env.hcl references)
├── dev/
│   ├── env.hcl           # Environment variables (locals block)
│   ├── vpc/terragrunt.hcl
│   └── rds/terragrunt.hcl
└── prod/
    ├── env.hcl           # Environment variables (locals block)
    ├── vpc/terragrunt.hcl
    └── rds/terragrunt.hcl

root.hcl 的限制：

• ❌ 不能使用 read_terragrunt_config(find_in_parent_folders("env.hcl"))——根级目录不存在 env.hcl
• ❌ 不能引用来自 env.hcl 的 local.environment 或 local.aws_region
• ✅ 可以使用静态值或通过 get_env() 获取运行时配置
• ✅ 可以使用 ${path_relative_to_include()} 设置状态键（可动态解析）

子模块读取 env.hcl：

# dev/vpc/terragrunt.hcl
include "root" {
  path = find_in_parent_folders("root.hcl")
}

locals {
  env = read_terragrunt_config(find_in_parent_folders("env.hcl"))
}

inputs = {
  name = "${local.env.locals.environment}-vpc"  # Works: env.hcl exists in dev/
}

模式 B：单环境或环境感知型根配置

适用场景： 单一环境，或所有环境共用同一个能够检测环境的根配置。

infrastructure/
├── root.hcl              # Can be environment-aware via get_env() or directory parsing
├── account.hcl           # Account-level config (optional)
├── region.hcl            # Region-level config (optional)
└── vpc/
    └── terragrunt.hcl

root.hcl 可以检测环境：

# root.hcl - environment detection via directory path
locals {
  # Parse environment from path (e.g., "prod/vpc" -> "prod")
  path_parts  = split("/", path_relative_to_include())
  environment = local.path_parts[0]

  # OR use environment variable
  environment = get_env("TG_ENVIRONMENT", "dev")
}

模式 C：共享环境变量（_env 目录）

适用场景： 通过符号链接或直接引用集中管理环境变量。

infrastructure/
├── root.hcl              # Environment-AGNOSTIC
├── _env/                 # Centralized environment definitions
│   ├── prod.hcl
│   ├── staging.hcl
│   └── dev.hcl
├── prod/
│   ├── env.hcl           # Reads from _env/prod.hcl
│   └── vpc/terragrunt.hcl
└── dev/
    ├── env.hcl           # Reads from _env/dev.hcl
    └── vpc/terragrunt.hcl

env.hcl 从 _env 读取：

# prod/env.hcl
locals {
  env_vars = read_terragrunt_config("${get_repo_root()}/_env/prod.hcl")

  # Re-export for child modules
  environment        = local.env_vars.locals.environment
  aws_region         = local.env_vars.locals.aws_region
  vpc_cidr           = local.env_vars.locals.vpc_cidr
  # ... other variables
}

架构模式选择检查清单（规范）

必须： 编写任何文件之前，必须完成此检查清单，并将勾选后的清单输出给用户。此要求不可省略。

生成任何文件之前，先输出已完成的检查清单：

## Architecture Pattern Selection

[x] Identified architecture pattern: Pattern ___ (A/B/C)
[x] Root.hcl scope: [ ] environment-agnostic  OR  [ ] environment-aware
[x] env.hcl location: ___________________
[x] Child modules access env via: ___________________
[x] Verified: No file references a path that doesn't exist from its location

已完成的检查清单示例：

## Architecture Pattern Selection

[x] Identified architecture pattern: Pattern A (Multi-Environment with Environment-Agnostic Root)
[x] Root.hcl scope: [x] environment-agnostic  OR  [ ] environment-aware
[x] env.hcl location: dev/env.hcl, prod/env.hcl (one per environment)
[x] Child modules access env via: read_terragrunt_config(find_in_parent_folders("env.hcl"))
[x] Verified: No file references a path that doesn't exist from its location

快速变量定义示例

以下入门文件适用于模式 B，以及需要感知账户和区域的配置。

env.hcl

locals {
  environment = "dev"
  aws_region  = "us-east-1"
  project     = "platform"
}

account.hcl

locals {
  account_id   = "123456789012"
  account_name = "shared-services"
}

region.hcl

locals {
  aws_region = "us-east-1"
}

使用场景

• 创建新的 Terragrunt 项目或配置
• 设置多环境基础设施（dev/staging/prod）
• 实现 DRY Terraform 配置
• 管理具有依赖关系的复杂基础设施
• 使用自定义 Terraform 提供程序或模块

核心功能

1. 生成根配置

创建根级别的 root.hcl 或 terragrunt.hcl，其中包含远程状态、提供程序配置和通用变量。

MANDATORY： 生成前，读取模板文件：

Read: assets/templates/root/terragrunt.hcl

模板： assets/templates/root/terragrunt.hcl 模式： references/common-patterns.md → 根配置模式

需要替换的占位符：

• [BUCKET_NAME]、[AWS_REGION]、[DYNAMODB_TABLE]
• [TERRAFORM_VERSION]、[PROVIDER_NAME]、[PROVIDER_SOURCE]、[PROVIDER_VERSION]
• [ENVIRONMENT]、[PROJECT_NAME]

Root.hcl 设计原则：

1. 默认不依赖特定环境 - 不要假设根目录中存在 env.hcl
2. 为提供程序/后端区域使用静态值 - 或使用 get_env() 进行运行时配置
3. 状态键使用 path_relative_to_include() - 这会自动包含环境路径
4. 提供程序标签可以是静态的 - 特定环境的标签放在子模块中

2. 生成子模块配置

创建包含依赖项、模拟输出和正确 include 的子模块。

MANDATORY： 生成前，读取模板文件：

Read: assets/templates/child/terragrunt.hcl

模板： assets/templates/child/terragrunt.hcl 模式： references/common-patterns.md → 子模块模式

模块源选项：

• 本地："../../modules/vpc"
• Git："git::https://github.com/org/repo.git//path?ref=v1.0.0"
• Registry："tfr:///terraform-aws-modules/vpc/aws?version=5.1.0"

3. 生成独立模块

创建不依赖根配置的自包含模块。

MANDATORY： 生成前，读取模板文件：

Read: assets/templates/module/terragrunt.hcl

模板： assets/templates/module/terragrunt.hcl

规范占位符替换映射表

每次生成输出时都使用此映射表：

占位符	含义	替换示例	备注
[AWS_REGION]	AWS 区域	us-east-1	所有模板中的规范区域占位符
[ENVIRONMENT]	环境名称	dev	目录命名使用小写
[PROJECT_NAME]	项目/应用名称	payments-platform	标签和名称使用相同的值
[BUCKET_NAME]	远程状态 S3 存储桶	acme-tfstate-prod	首次 apply 前必须创建存储桶
[DYNAMODB_TABLE]	状态锁表	acme-terraform-locks	首次 apply 前必须创建表
[PROVIDER_SOURCE]	Terraform 提供程序源	hashicorp/aws	使用完全限定的源
[TERRAFORM_VERSION]	所需的 Terraform/OpenTofu 版本	1.8.5	同时用于 terraform_version_constraint 和 required_version。确保与模块约束兼容。

旧版别名规范化： 如果在较早的示例中看到 [REGION]，请将其视为 [AWS_REGION]，并在验证前替换。

4. 生成多环境基础设施

创建 dev/staging/prod 的完整目录结构。

MANDATORY： 生成前：

1. 确定架构模式（参见“架构模式”部分）
2. 读取根配置、环境和子模块的相关模板
3. 验证 env.hcl 的放置位置和访问模式：

   Read: assets/templates/env/env.hcl
   

模式： references/common-patterns.md → 特定环境模式

典型结构（模式 A - 不依赖特定环境的根配置）：

infrastructure/
├── root.hcl              # Environment-AGNOSTIC root config
├── dev/
│   ├── env.hcl           # Dev environment variables
│   └── vpc/terragrunt.hcl
└── prod/
    ├── env.hcl           # Prod environment variables
    └── vpc/terragrunt.hcl

5. 生成 Terragrunt Stacks（2025）

使用 terragrunt.stack.hcl 的基础设施蓝图。

**强制要求：**生成前，请阅读模板文件：

Read: assets/templates/stack/terragrunt.stack.hcl
Read: assets/templates/catalog/terragrunt.hcl

文档：Stacks Documentation 模板：assets/templates/stack/terragrunt.stack.hcl 目录模板：assets/templates/catalog/terragrunt.hcl 模式：references/common-patterns.md → Stacks Patterns

**Stack 路径规则：**在依赖单元之间保持 no_dot_terragrunt_stack 模式一致。不要在同一依赖链中混用直接路径生成和 .terragrunt-stack 生成。

命令：

terragrunt stack generate    # Generate unit configurations
terragrunt stack run plan    # Plan all units
terragrunt stack run apply   # Apply all units
terragrunt stack output      # Get aggregated outputs
terragrunt stack clean       # Clean generated directories

6. 生成 Feature Flags（2025）

无需更改代码即可控制运行时行为。

文档：Feature Flags Documentation 模式：references/common-patterns.md → Feature Flags Patterns

**关键：**Feature flag 的 default 值必须是静态值（布尔值、字符串、数字）。 不能引用 local.* 值。请使用静态默认值，并通过 CLI/环境变量进行覆盖。

正确：

feature "enable_monitoring" {
  default = false  # Static value - OK
}

错误：

feature "enable_monitoring" {
  default = local.env.locals.enable_monitoring  # Dynamic reference - FAILS
}

用法：

terragrunt apply --feature enable_monitoring=true
# or
export TG_FEATURE="enable_monitoring=true"

**特定环境的默认值：**为每个环境文件使用不同的静态默认值，而非动态引用。

7. 生成 Exclude Blocks（2025）

精细控制执行（取代已弃用的 skip）。

文档：Exclude Block Reference 模式：references/common-patterns.md → Exclude Block Patterns

操作："plan"、"apply"、"destroy"、"all"、"all_except_output"

**生产环境建议：**对于关键生产资源，添加 exclude blocks，以防止意外销毁：

# Protect production databases from accidental destroy
exclude {
  if      = true
  actions = ["destroy"]
  exclude_dependencies = false
}

# Also use prevent_destroy for critical resources
prevent_destroy = true

8. 生成 Errors Blocks（2025）

高级错误处理（取代已弃用的 retryable_errors）。

文档：Errors Block Reference 模式：references/common-patterns.md → Errors Block Patterns

9. 生成 OpenTofu 引擎配置（2025）

使用 OpenTofu 作为 IaC 引擎。

文档：Engine Documentation 模式：references/common-patterns.md → OpenTofu Engine Patterns

10. 处理自定义 Providers/Modules

使用自定义 provider 生成配置时：

1. 识别 provider 名称、来源和版本
2. 使用 WebSearch 搜索："[provider] terraform provider [version] documentation"
3. 或者在可用时使用 Context7 MCP 获取结构化文档
4. 使用正确的 required_providers block 生成配置
5. 在注释中说明身份验证要求

生成工作流

**关键：**每个生成任务都必须遵循此工作流。跳过步骤会导致验证错误。

步骤 1：了解需求

• 配置类型是什么？（根配置、子配置、独立配置、stack）
• 单环境还是多环境？
• 模块之间有哪些依赖关系？
• 将使用哪些 providers/modules？

步骤 2：确定架构模式

**强制要求：**在编写任何文件之前，选择并记录该模式。

场景	模式	Root.hcl 范围
具有共享根配置的多环境	Pattern A	与环境无关
单一环境	Pattern B	与环境相关
集中式环境变量	Pattern C	与环境无关

完成上文的架构模式选择清单（规范版），并在生成文件之前将其纳入输出。

步骤 3：读取必需的模板

必须执行： 在生成每种配置类型之前，先读取相关模板文件。

配置类型	要读取的模板	用途
根配置	assets/templates/root/terragrunt.hcl	共享状态后端、providers 和通用输入
环境变量	assets/templates/env/env.hcl	子模块读取的每环境本地变量（模式 A）
子模块	assets/templates/child/terragrunt.hcl	配置为包含根配置的环境模块
独立模块	assets/templates/module/terragrunt.hcl	不包含根配置的独立 Terragrunt 模块
Stack 文件	assets/templates/stack/terragrunt.stack.hcl	可生成多个单元的蓝图
Catalog 单元	assets/templates/catalog/terragrunt.hcl	供 Stack 使用的可复用单元模板

还需读取：

• references/common-patterns.md - 生成模式的主要来源

步骤 4：生成并验证

验证策略： 生成过程中进行内联检查，并在最后进行批量验证。

多环境项目的生成顺序：

1. 首先生成 root.hcl

   • 内联检查（生成过程中）：
     • 如果与环境无关，则不使用 read_terragrunt_config(find_in_parent_folders("env.hcl"))
     • remote_state 块包含 encrypt = true
     • 使用 errors 块（而非已弃用的 retryable_errors）

2. 为每个环境生成 env.hcl 文件

   • 内联检查（生成过程中）：
     • locals 块包含环境、aws_region 和特定于模块的变量
     • 不引用该目录层级中不存在的文件

3. 生成子模块（VPC 等）——先生成没有依赖项的模块

   • 内联检查（生成过程中）：
     • include 块使用 find_in_parent_folders("root.hcl")
     • 存在 read_terragrunt_config(find_in_parent_folders("env.hcl"))
     • terraform.source 使用有效语法（tfr:///、git:: 或相对路径）

4. 生成依赖其他模块的模块（RDS、EKS 等）

   • 内联检查（生成过程中）：
     • dependency 块包含 mock_outputs
     • mock_outputs_allowed_terraform_commands 包含 ["validate", "plan", "destroy"]
     • 生产模块设置了 prevent_destroy = true 和/或 exclude 块

5. 生成所有文件后，运行批量验证

   注意： 完整的 CLI 验证（terragrunt hcl fmt、terragrunt dag graph）要求所有文件都已存在，因此需在最后批量运行。

   # Batch validation commands (run after all files exist):
   terragrunt hcl fmt --check          # Format validation
   terragrunt dag graph                 # Dependency graph validation
   

   • 调用 Skill(devops-skills:terragrunt-validator) 进行全面验证

步骤 5：修复并重新验证

如果验证失败：

1. 分析错误（路径解析、缺失变量、语法错误）
2. 修复相关文件中的问题
3. 重新验证修复后的文件
4. 重复以上步骤，直到解决所有错误

步骤 6：呈现结果

遵循下方的“呈现要求”部分。

验证工作流

重要： 必须验证每个生成的配置。

增量验证检查

生成 root.hcl 后：

cd <infrastructure-directory>
terragrunt hcl fmt --check

生成每个子模块后：

cd <module-directory>
terragrunt hcl fmt --check
# If no dependencies on other modules:
terragrunt hcl validate --inputs

完整验证

生成所有文件后：

1. 调用验证技能：

   Invoke: Skill(devops-skills:terragrunt-validator)
   

2. 如果验证失败：

   • 分析错误（占位符缺失、语法无效、路径错误）
   • 修复问题
   • 重新验证（重复此过程，直到解决所有错误）

3. 如果验证成功： 呈现配置并附上使用说明

仅在以下情况下跳过验证： 部分代码片段、文档示例或用户明确提出要求

验证回退方案（环境限制）

如果常规验证路径不可用，请按以下顺序使用回退方案，并报告跳过了哪些步骤：

1. 如果 terragrunt 不可用：
   • 运行静态检查：

     rg -n "\[[A-Z0-9_]+\]" .
     rg -n "find_in_parent_folders\\(\"env\\.hcl\"\\)" .
     

   • 报告运行时 Terragrunt 验证尚未完成。
2. 如果无法执行验证器技能：
   • 改为直接运行 Terragrunt 检查：

     terragrunt hcl fmt --check
     terragrunt dag graph
     

3. 如果无法使用 tree 展示目录结构：
   • 使用：

     find . -maxdepth 4 -type f | sort
     

展示要求

强制要求： 成功完成验证后，必须展示以下所有部分。展示不完整不可接受。请复制并填写以下模板。

1. 目录结构摘要（强制）

# Show the generated structure
tree <infrastructure-directory>

2. 生成的文件（强制）

输出包含所有生成文件的表格：

| File | Purpose |
|------|---------|
| root.hcl | Shared configuration for all child modules (state backend, provider) |
| dev/env.hcl | Development environment variables |
| prod/env.hcl | Production environment variables |
| dev/vpc/terragrunt.hcl | VPC module for development |
| ... | ... |

3. 使用说明（强制）

必须包含此部分。 请复制以下模板并填写实际值：

## Usage Instructions

### Prerequisites
Before running Terragrunt commands, ensure:
1. AWS credentials are configured (`aws configure` or environment variables)
2. S3 bucket `<BUCKET_NAME>` exists for state storage
3. DynamoDB table `<TABLE_NAME>` exists for state locking

### Commands

# Navigate to infrastructure directory
cd <INFRASTRUCTURE_DIR>

# Initialize all modules
terragrunt run --all init

# Preview changes for a specific environment
cd <ENV>/vpc && terragrunt plan

# Preview all changes
terragrunt run --all plan

# Apply changes (requires approval)
terragrunt run --all apply

# Destroy (use with extreme caution)
terragrunt run --all destroy

4. 占位符替换和机密信息检查（强制）

必须包含此部分。 请复制以下模板并填写实际值：

## Placeholder and Secrets Check

### Placeholder Replacement
- [ ] All placeholders (`[AWS_REGION]`, `[BUCKET_NAME]`, `[DYNAMODB_TABLE]`, etc.) replaced with real values
- [ ] No legacy placeholder aliases left (for example `[REGION]`)
- [ ] `terraform.source` values point to real module sources and pinned versions

### Secrets Safety
- [ ] No plaintext credentials or access keys in `terragrunt.hcl`, `root.hcl`, `env.hcl`, `account.hcl`, or `region.hcl`
- [ ] Sensitive values sourced via environment variables, secret managers, or CI variables
- [ ] Example values kept non-sensitive and clearly marked as placeholders

5. 环境专属说明（强制）

必须包含此部分。 请复制以下模板并填写实际值：

## Environment Notes

### Required Environment Variables
| Variable | Description | Example |
|----------|-------------|---------|
| AWS_PROFILE | AWS CLI profile to use | `my-profile` |
| AWS_REGION | AWS region (or set in provider) | `us-east-1` |

### Prerequisites
- [ ] S3 bucket `<BUCKET_NAME>` must exist before first run
- [ ] DynamoDB table `<TABLE_NAME>` must exist for state locking
- [ ] IAM permissions for Terraform state management

### Production-Specific Protections
| Module | Protection | Description |
|--------|------------|-------------|
| prod/rds | `prevent_destroy = true` | Prevents accidental database deletion |
| prod/rds | `exclude { actions = ["destroy"] }` | Blocks destroy commands |

6. 后续步骤（可选）

建议用户接下来可以做什么（例如添加更多模块、自定义配置等）。

最佳实践

请参阅 ../terragrunt-validator/references/best_practices.md，了解完整指南。

关键原则：

• 使用 include 块继承根配置（DRY）
• 始终为依赖项提供模拟输出
• 启用状态加密（encrypt = true）
• 使用 generate 块配置提供程序
• 为本地/Git 模块指定有界版本约束（~> 5.0，而不是 >= 5.0）
• 切勿硬编码凭据或机密信息
• 为瞬时错误配置重试逻辑

关于注册表模块版本约束的说明： 使用 Terraform 注册表模块时（例如 tfr:///terraform-aws-modules/vpc/aws?version=5.1.0），它们通常会定义自己的 required_providers。此时，可以不在 root.hcl 中生成 required_providers，以避免冲突。模块固定版本（?version=X.X.X）提供了版本约束。详情请参阅“常见问题 → 注册表模块中的提供程序冲突”。

应避免的反模式：

• 硬编码账户 ID、区域或环境名称
• 未为依赖项提供模拟输出
• 在多个模块间重复配置
• 未加密的状态存储
• 缺少版本约束或版本约束过宽松（定义自身版本约束的注册表模块除外）
• root.hcl 试图读取根目录中不存在的 env.hcl

已弃用属性

已弃用	替代项	参考
skip	exclude 块	文档
retryable_errors	errors.retry 块	文档
run-all	run --all	迁移指南
--terragrunt-* 标志	不带前缀的标志	CLI 参考
TERRAGRUNT_* 环境变量	TG_* 环境变量	CLI 参考

资源

模板 — 生成前必须阅读

配置类型	模板文件	用途	阅读时机
根配置	assets/templates/root/terragrunt.hcl	共享后端、提供程序和通用输入	生成任何 root.hcl 之前
环境变量	assets/templates/env/env.hcl	每个环境的局部变量（环境、区域、规格、功能开关）	生成任何 env.hcl（模式 A）之前
子模块	assets/templates/child/terragrunt.hcl	模块包含、源和可选依赖框架	生成任何子模块之前
独立模块	assets/templates/module/terragrunt.hcl	不继承根配置的模块配置	生成独立模块之前
Stack 文件	assets/templates/stack/terragrunt.stack.hcl	Stack 蓝图和单元生成	生成 Stack 之前
Catalog 单元	assets/templates/catalog/terragrunt.hcl	供 Stack 定义使用的可复用单元	生成 Catalog 单元之前

参考资料

参考资料	内容	用途	阅读时机
references/common-patterns.md	所有生成模式及示例	编写文件前选择兼容的模式	始终在生成前阅读
../terragrunt-validator/references/best_practices.md	全面的最佳实践	最终质量和安全检查	始终在生成前阅读

官方文档

• Terragrunt 文档
• 配置参考
• CLI 参考
• Stacks
• 功能标志
• 引擎
• 迁移指南

常见问题

Root.hcl 无法找到 env.hcl

症状：

Error: Attempt to get attribute from null value
  on ./root.hcl line X:
  This value is null, so it does not have any attributes.

原因： Root.hcl 正在通过 find_in_parent_folders("env.hcl") 尝试读取 env.hcl，但根级别不存在 env.hcl。

解决方案： 让 Root.hcl 与环境无关：

# DON'T do this in root.hcl for multi-environment setups:
locals {
  env_vars = read_terragrunt_config(find_in_parent_folders("env.hcl"))  # FAILS
}

# DO use static values or get_env():
generate "provider" {
  path      = "provider.tf"
  if_exists = "overwrite_terragrunt"
  contents  = <<EOF
provider "aws" {
  region = "us-east-1"  # Static value, or use get_env("AWS_REGION", "us-east-1")
}
EOF
}

与 Registry 模块的 Provider 冲突

使用 Terraform Registry 模块（例如 tfr:///terraform-aws-modules/vpc/aws）时，它们可能会定义自己的 required_providers 块。这可能与 root.hcl 生成的 Provider 配置冲突。

症状：

Error: Duplicate required providers configuration

解决方案：

1. 移除冲突的生成块 — 如果使用自行管理 Provider 的 Registry 模块，请避免生成重复的 required_providers：

   # In root.hcl - only generate provider config, not required_providers
   generate "provider" {
     path      = "provider.tf"
     if_exists = "overwrite_terragrunt"
     contents  = <<EOF
   provider "aws" {
     region = "us-east-1"
   }
   EOF
   }
   

2. 使用 if_exists = "skip" — 如果文件已存在，则跳过生成：

   generate "versions" {
     path      = "versions.tf"
     if_exists = "skip"  # Don't overwrite module's versions.tf
     contents  = "..."
   }
   

3. 清除缓存 — 如果修复后冲突仍然存在：

   rm -rf .terragrunt-cache
   terragrunt init
   

功能标志验证错误

如果在功能块中看到 Unknown variable; There is no variable named "local"，请确保默认值是静态值（请参阅上文的“功能标志”部分）。

子模块无法找到 env.hcl

症状：

Error: Attempt to get attribute from null value
  on ./dev/vpc/terragrunt.hcl line X:

原因： 子模块的 find_in_parent_folders("env.hcl") 无法找到 env.hcl。

解决方案： 确保环境目录中存在 env.hcl：

dev/
├── env.hcl           # This file MUST exist
└── vpc/
    └── terragrunt.hcl  # Calls find_in_parent_folders("env.hcl")

快速参考卡

文件读取清单

生成前，按以下顺序阅读这些文件：

1. references/common-patterns.md — 了解可用模式
2. ../terragrunt-validator/references/best_practices.md — 熟悉规则
3. assets/templates/ 中的相关模板 — 结构参考

架构决策树

Q: Multiple environments (dev/staging/prod)?
├─ YES → Q: Shared root configuration?
│   ├─ YES → Pattern A: Environment-Agnostic Root
│   └─ NO  → Separate root.hcl per environment
└─ NO  → Q: Environment detection needed?
    ├─ YES → Pattern B: Environment-Aware Root
    └─ NO  → Pattern B: Simple single-environment

验证顺序

1. 格式检查：terragrunt hcl fmt --check
2. 输入验证：terragrunt hcl validate --inputs
3. 完整验证：调用 Skill(devops-skills:terragrunt-validator)
4. 修复错误 → 重新验证 → 重复直至无错误

完成标准

只有在以下条件全部满足时，才能完成此技能执行：

• 已完成并展示一份架构检查清单（即本文件中的规范检查清单）
• 除非明确要求使用旧版语法，否则生成的文件始终使用现代根级 include 语法
• 注册表源使用规范的 tfr:///NAMESPACE/NAME/PROVIDER?version=X.Y.Z 格式
• 仅在确有需要时添加依赖项区块（不得将其留作未解决的占位符）
• 已替换所有占位符，并在输出中报告机密信息检查结果
• 验证已成功，或已运行备用检查并明确记录其局限性