---
title: "CTP Topic 16 Cross-account Terraform modules"
type: source
tags: [Terraform, Cross-Account, Modules, CTP, IaC, DevOps, AWS-Landing-Zone]
date: 2026-04-14
---

## Source File
- [[raw/Cloud & DevOps/Public-Cloud-Learning-Sessions/03_Terraform/ctp-topic-16-cross-account-terraform-modules.md]]

## Summary（用中文描述）
- 核心主题：**跨账号 Terraform 模块的中心化部署方案**，解决多账号 AWS 环境中一个模块内跨账号创建资源的安全与自动化问题
- 问题域：原有的 Gruntwork 流水线针对单账号设计，在多账号场景下存在安全风险（一账号被攻破可能波及全局）
- 方法/机制：基于 **Shared Account（共享账号）** 的中心化部署架构，Jenkins + ECS Deploy Runner + Assume Role 三者联动
- 结论/价值：实现安全性（账号间无直接信任关系）、自动化（Jenkins 自动识别跨账号模块）、可复用性（模块代码不硬编码特定账号角色）

## Key Claims（用中文描述）
- **Shared Account 作为中转站**：Jenkins 托管在 Shared Account，当检测到 `cross-account.json` 标记文件时触发 ECS Deploy Runner
- **Assume Role 双角色机制**：ECS Deploy Runner 通过 Assume Role 访问目标账号的两个角色——`TF state bucket accessor`（读取状态文件）和 `cross-account ECS deploy runner role`（执行资源部署）
- **Blast Radius 控制**：避免 Workload 账号之间直接互访，权限控制在受严格审计的 Shared Account
- **Terragrunt HCL 全局配置**：通过根目录 `terragrunt.hcl` 定义远程状态存储和角色切换逻辑，支持本地开发与 Jenkins 自动部署的差异化角色处理

## Key Quotes
> "Cross-account Terraform Modules 指在一个模块内通过配置多个 Provider，实现在多个 AWS 账号中同时创建或管理资源的功能" — Fibos，核心概念定义
> "Shared Account 是整个 Landing Zone 的核心管理账号，托管 Jenkins、镜像仓库等公共服务，并作为跨账号部署的信任源" — Fibos，架构定位
> "ECS Deploy Runner 运行在 ECS 上的 Docker 容器，负责执行 Terraform plan 和 apply 命令，是流水线中的实际执行单元" — Fibos，EDR 定义

## Key Concepts
- [[Cross-account Terraform Modules]]：在一个 Terraform 模块中通过配置多个 Provider，实现在多个 AWS 账号中同时创建或管理资源的功能
- [[Shared Account]]：Landing Zone 核心管理账号，托管 Jenkins 及公共服务，作为跨账号部署的信任源
- [[ECS Deploy Runner]]：运行在 ECS 上的 Docker 容器，负责执行 Terraform plan/apply，是流水线的实际执行单元
- [[TF State Bucket Accessor]]：专门定义的 IAM 角色，仅允许部署工具访问目标账号 S3 桶中的 Terraform 状态文件
- [[Cross-account ECS Deploy Runner Role]]：部署在目标账号中的角色，允许 Shared Account 的执行器通过 Assume Role 获取资源创建权限
- [[cross-account.json]]：约定俗成的标记文件，放置于模块目录中，用于告知 Jenkins 该模块需要调用跨账号部署逻辑
- [[Root Terragrunt HCL]]：全局 Terragrunt 配置文件，定义远程状态存储和角色切换逻辑

## Key Entities
- **Fibos**：主讲人，分享了团队基于 Shared Account 的跨账号 Terraform 部署方案
- **Gruntwork**：参考架构来源，原有 Gruntwork 流水线主要针对单账号设计
- **Jenkins**：CI/CD 引擎，托管在 Shared Account，负责检测模块类型并触发部署流程
- **AWS Landing Zone**：多账号架构框架，Shared Account + Workload Account 的分层设计

## Connections
- [[ctp-topic-9-ci-cd-with-gruntwork]] ← foundation ← [[ctp-topic-16-cross-account-terraform-modules]]
- [[ECS Deploy Runner]] ← depends_on ← [[Shared Account]]
- [[Cross-account Terraform Modules]] ← uses ← [[ECS Deploy Runner]]
- [[ECS Deploy Runner]] ← assumes ← [[Cross-account ECS Deploy Runner Role]]
- [[ECS Deploy Runner]] ← reads_state ← [[TF State Bucket Accessor]]
- [[Root Terragrunt HCL]] ← configures ← [[Cross-account Terraform Modules]]
- [[ctp-topic-48-terraform-vs-terragrunt]] ← related ← [[Root Terragrunt HCL]]
- [[AWS-Landing-Zone]] ← enables ← [[Shared Account]]

## Contradictions
- 与 [[ctp-topic-9-ci-cd-with-gruntwork]]（单账号 Gruntwork 流水线）：原有 Gruntwork 流水线主要针对单账号设计，不处理跨账号场景；本方案通过 Shared Account 中心化架构扩展支持多账号，同时保留 Gruntwork 模块复用优势。两者为演进关系而非冲突。
- 与 [[ctp-topic-32-using-atlantis-cicd-for-infrastructure-deployments]]（Atlantis 替代 Jenkins）：Atlantis 在 merge 前应用变更，每个 Landing Zone 部署单台 EC2 实例；本方案的 ECS Deploy Runner 运行在容器中，更适合跨账号大规模部署。Atlantis 的跨账号访问通过各账户 IAM 角色实现，与本方案 Assume Role 机制类似，但执行载体不同。