diff --git a/docs/layers/accounts/initialize-tfstate.mdx b/docs/layers/accounts/initialize-tfstate.mdx
index 65cb259f0..88591590f 100644
--- a/docs/layers/accounts/initialize-tfstate.mdx
+++ b/docs/layers/accounts/initialize-tfstate.mdx
@@ -49,57 +49,57 @@ If you look at `components/terraform/`, you'll see a bunch of directories. These
-
+
+ Why Do We Use Wildcard Patterns with IAM?
-
- Why Do We Use Wildcard Patterns with IAM?
+ 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.
- :::
+
-
+
## Initialize the Terraform State Backend