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

## Overview

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

## Key Responsibilities

### 1. Remote State Configuration

```hcl
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

```hcl
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 中的应用