nexus/wiki/concepts/Root-Terragrunt-HCL.md

title, type, tags, sources, last_updated

title	type	tags	sources	last_updated
Root Terragrunt HCL	concept	Terraform Terragrunt IaC Configuration AWS	ctp-topic-16-cross-account-terraform-modules.md ctp-topic-48-terraform-vs-terragrunt.md	2026-05-15

Overview

Root Terragrunt HCL 是项目根目录下的 terragrunt.hcl 配置文件，用于定义所有 Terraform 模块通用的远程状态存储（Remote State）和角色切换逻辑。它是 Terragrunt DRY（Don't Repeat Yourself）原则的核心体现。

Key Responsibilities

1. Remote State Configuration

remote_state {
  backend = "s3"
  config = {
    bucket         = "my-terraform-state"
    key            = "${path_relative_to_include()}/terraform.tfstate"
    region         = "us-east-1"
    encrypt        = true
    dynamodb_table = "terraform-locks"
  }
}

2. Cross-Account Role Switching

inputs = {
  # 在跨账号场景中，通过 assume_role 切换到目标账号的角色
  assume_role_arn = "arn:aws:iam::TARGET_ACCOUNT:role/Cross-account-ECS-Deploy-Runner-Role"
}

How It Works

Terragrunt 通过继承机制将根目录的配置自动应用于所有子模块：

1. 检测模块：Jenkins 检测到模块目录
2. 加载配置：Terragrunt 加载根目录的 terragrunt.hcl
3. 注入变量：自动将 remote_state 和 assume_role_arn 注入子模块
4. 执行命令：运行 terragrunt plan/apply

Relationship with Terragrunt

• Terragrunt ← uses ← Root-Terragrunt-HCL
• Cross-account-Terraform-Modules ← configured_by ← Root-Terragrunt-HCL
• ECS-Deploy-Runner ← configured_by ← Root-Terragrunt-HCL

Key Differences: Local vs CI/CD

环境	Role 处理
本地开发	Terragrunt 自动从 HCL 配置 Assume Role，无需手动干预
Jenkins CI/CD	EDR 使用 HCL 中配置的 assume_role_arn，通过 ECS 容器环境 Assume

Related Concepts

• Terragrunt：Terragrunt 是该配置的解析和执行引擎
• TerraformState：remote_state 配置定义了状态文件存储位置
• Assume-Role：assume_role_arn 配置控制跨账号角色切换
• DRY-Principle：Root HCL 是 DRY 原则在 IaC 中的应用