nexus/wiki/concepts/TF-State-Bucket-Accessor.md

title, type, tags, sources, last_updated

title	type	tags	sources	last_updated
TF State Bucket Accessor	concept	Terraform IAM S3 State-Management AWS Security	ctp-topic-16-cross-account-terraform-modules.md	2026-05-15

Overview

TF State Bucket Accessor 是跨账号 Terraform 部署方案中的两个核心 IAM 角色之一，专门用于在目标 AWS 账号中读取和写入 Terraform 状态文件（S3 存储）。

Purpose

Terraform 状态文件记录了基础设施的当前期望状态。在跨账号场景中：

• 状态文件存储位置：每个 Workload 账号拥有独立的 S3 存储桶
• 访问挑战：Shared Account 的 ECS-Deploy-Runner 需要读写这些状态文件
• 安全约束：不能直接赋予 Shared Account 对所有 S3 桶的完全访问权限
• 解决方案：在每个目标账号中创建专门的 IAM 角色，仅允许部署工具 Assume

Security Design

遵循最小权限原则（Principle of Least Privilege）：

{
  "Effect": "Allow",
  "Principal": {
    "AWS": "arn:aws:iam::<SharedAccount>:role/ecs-deploy-runner-execution-role"
  },
  "Action": [
    "s3:GetObject",
    "s3:PutObject",
    "s3:ListBucket"
  ],
  "Resource": [
    "arn:aws:s3:::<account>-terraform-state",
    "arn:aws:s3:::<account>-terraform-state/*"
  ]
}

Relationship with Terraform State

• TerraformState：状态文件管理是 IaC 的核心问题
• Blast-Radius：专用角色限制了凭证泄露时的影响范围
• Assume-Role：EDR 通过 Assume Role 获取该角色的临时凭证

Dual Role Pattern

跨账号 Terraform 部署使用双角色模式，将状态访问和资源部署分离：

角色	职责	托管位置
TF State Bucket Accessor	读取/写入 Terraform 状态文件	目标账号
Cross-account-ECS-Deploy-Runner-Role	执行资源部署（plan/apply）	目标账号

Relationships

• TerraformState ← protected_by ← TF-State-Bucket-Accessor
• ECS-Deploy-Runner ← uses ← TF-State-Bucket-Accessor
• Assume-Role ← mechanism ← TF-State-Bucket-Accessor
• Blast-Radius ← controls ← TF-State-Bucket-Accessor

Related Entities

• ECS-Deploy-Runner：使用该角色的执行器
• Cross-account-ECS-Deploy-Runner-Role：双角色模式中的另一个角色