---
title: "Cross-account Terraform Modules"
type: concept
tags: [Terraform, Cross-Account, Modules, IaC, AWS]
sources: [ctp-topic-16-cross-account-terraform-modules]
last_updated: 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）