69 lines
2.2 KiB
Markdown
69 lines
2.2 KiB
Markdown
---
|
||
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 中的应用
|