Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
72 changes: 36 additions & 36 deletions docs/layers/accounts/initialize-tfstate.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -49,57 +49,57 @@ If you look at `components/terraform/`, you'll see a bunch of directories. These

<AtmosWorkflow workflow="vendor" fileName="quickstart/foundation/accounts" />

</Step>
<details>
<summary>Why Do We Use Wildcard Patterns with IAM?</summary>

<details>
<summary>Why Do We Use Wildcard Patterns with IAM?</summary>
The `tfstate-backend` component creates IAM roles with trust policies that control which principals can assume them.
Understanding how these policies work is important for security.

The `tfstate-backend` component creates IAM roles with trust policies that control which principals can assume them.
Understanding how these policies work is important for security.
### The Character Limit Problem

### The Character Limit Problem
IAM role trust policies have a **hard limit of 4096 characters** (after requesting a quota increase from the default
2048). For organizations with multiple accounts, listing every role and permission set by explicit ARN would easily
exceed this limit—even with the maximum quota.

IAM role trust policies have a **hard limit of 4096 characters** (after requesting a quota increase from the default
2048). For organizations with multiple accounts, listing every role and permission set by explicit ARN would easily
exceed this limit—even with the maximum quota.
Instead, the reference architecture uses wildcard ARN patterns like:
- `arn:aws:iam::*:role/acme-*-gbl-*-terraform` for Terraform execution roles
- `arn:aws:iam::*:role/aws-reserved/sso.amazonaws.com/*/AWSReservedSSO_Terraform*Access_*` for SSO permission sets

Instead, the reference architecture uses wildcard ARN patterns like:
- `arn:aws:iam::*:role/acme-*-gbl-*-terraform` for Terraform execution roles
- `arn:aws:iam::*:role/aws-reserved/sso.amazonaws.com/*/AWSReservedSSO_Terraform*Access_*` for SSO permission sets
### The Two-Way Security Handshake

### The Two-Way Security Handshake
Using wildcards in trust policies is secure because access requires a **two-way handshake**:

Using wildcards in trust policies is secure because access requires a **two-way handshake**:
1. **Trust Policy (this side):** The tfstate role's trust policy allows principals matching the pattern to attempt
assumption, but only if they're within your AWS Organization (`aws:PrincipalOrgID` condition).

1. **Trust Policy (this side):** The tfstate role's trust policy allows principals matching the pattern to attempt
assumption, but only if they're within your AWS Organization (`aws:PrincipalOrgID` condition).
2. **Principal's Policy (other side):** The principal (e.g., a Terraform role or SSO permission set) must also have
an IAM policy granting `sts:AssumeRole` on the specific tfstate role ARN.

2. **Principal's Policy (other side):** The principal (e.g., a Terraform role or SSO permission set) must also have
an IAM policy granting `sts:AssumeRole` on the specific tfstate role ARN.
A role matching the wildcard pattern cannot access Terraform state unless it also has explicit permission to assume
the tfstate role. This defense-in-depth approach maintains security while staying within IAM limits.

A role matching the wildcard pattern cannot access Terraform state unless it also has explicit permission to assume
the tfstate role. This defense-in-depth approach maintains security while staying within IAM limits.
### Requesting a Quota Increase (If Needed)

### Requesting a Quota Increase (If Needed)
If you customize the trust policies and approach the 2048 character default limit, you can request an increase up to
the maximum of 4096 characters. Requests within this limit are auto-approved instantly:

If you customize the trust policies and approach the 2048 character default limit, you can request an increase up to
the maximum of 4096 characters. Requests within this limit are auto-approved instantly:
```bash
atmos auth exec --identity core-root/terraform -- \
aws service-quotas request-service-quota-increase \
--service-code iam \
--quota-code L-C07B4B0D \
--desired-value 4096 \
--region us-east-1
```

```bash
atmos auth exec --identity core-root/terraform -- \
aws service-quotas request-service-quota-increase \
--service-code iam \
--quota-code L-C07B4B0D \
--desired-value 4096 \
--region us-east-1
```
:::note
This is only needed if you customize trust policies beyond the defaults. The reference architecture's wildcard
patterns fit comfortably within the default 2048 character limit.
:::

:::note
This is only needed if you customize trust policies beyond the defaults. The reference architecture's wildcard
patterns fit comfortably within the default 2048 character limit.
:::
</details>

</details>
</Step>

<Step>
## <StepNumber/> Initialize the Terraform State Backend
Expand Down
Loading