---
title: "TF State Bucket Accessor"
type: concept
tags: [Terraform, IAM, S3, State-Management, AWS, Security]
sources:
  - ctp-topic-16-cross-account-terraform-modules.md
last_updated: 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）：

```json
{
  "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]]：双角色模式中的另一个角色