nexus/wiki/concepts/Cross-account-Terraform-Modules.md

title, type, tags, sources, last_updated

title	type	tags	sources	last_updated
Cross-account Terraform Modules	concept	Terraform Cross-Account Modules IaC AWS	ctp-topic-16-cross-account-terraform-modules	2026-04-14

Overview

Cross-account Terraform Modules 指的是在单个 Terraform 模块中通过配置多个 AWS Provider，实现跨多个 AWS 账号同时创建或管理资源的能力。

Problem Statement

在复杂的云架构中（如 AWS Landing Zone），经常需要在一个模块内跨多个账号创建资源。例如：

• 在 InfoBlocks 账号 配置 DNS 记录
• 在 Workload 账号 部署应用服务

原有的 Gruntwork 流水线主要针对单账号设计，直接赋予账号间互访权限存在巨大安全风险——某一账号被攻破可能波及全局。

Solution Architecture

基于 Shared Account（共享账号） 的中心化部署方案：

1. Jenkins 托管于 Shared Account，当检测到模块目录中存在 cross-account.json 标记文件时，触发 ECS Deploy Runner
2. ECS Deploy Runner（运行在 ECS 上的 Docker 容器）被授予特殊权限，通过 Assume Role 访问目标账号：
   • TF state bucket accessor：读取目标账号 S3 桶中的 Terraform 状态文件
   • cross-account ECS deploy runner role：在目标账号内执行资源部署
3. 通过根目录 terragrunt.hcl 配置角色切换逻辑

Three Design Goals

Goal	Mechanism	Benefit
安全性	无 Workload 账号间直接信任，权限集中于 Shared Account	控制 Blast Radius
自动化	Jenkins 自动识别模块类型并选择正确部署路径	无人工干预
可复用性	模块代码不硬编码特定账号的角色	灵活适配多环境

Key Files

• cross-account.json：约定俗成的标记文件，放置于模块目录中，告知 Jenkins 调用跨账号部署逻辑
• terragrunt.hcl（Root）：全局 Terragrunt 配置文件，定义远程状态存储和角色切换逻辑

Relationships

• ECS Deploy Runner — 执行单元，运行 Docker 容器执行 plan/apply
• Shared Account — 信任源，托管 Jenkins 和公共服务
• Terraform — 底层 IaC 工具
• Gruntwork — 参考架构来源
• AWS-Landing-Zone — 多账号架构框架

Related Concepts

• Infrastructure-as-Code — 上层方法论
• GitOps — 部署编排模式
• Assume Role — 跨账号身份切换机制（AWS IAM）

Notes

• 本方案与单账号 Gruntwork 流水线为演进关系而非冲突
• 本方案与 Atlantis 跨账号 IAM Role 机制类似，但执行载体不同（ECS 容器 vs EC2）