@@ -49,57 +49,57 @@ If you look at `components/terraform/`, you'll see a bunch of directories. These
4949
5050 <AtmosWorkflow workflow = " vendor" fileName = " quickstart/foundation/accounts" />
5151
52- </Step >
52+ <details >
53+ <summary >Why Do We Use Wildcard Patterns with IAM?</summary >
5354
54- < details >
55- < summary >Why Do We Use Wildcard Patterns with IAM?</ summary >
55+ The ` tfstate-backend ` component creates IAM roles with trust policies that control which principals can assume them.
56+ Understanding how these policies work is important for security.
5657
57- The ` tfstate-backend ` component creates IAM roles with trust policies that control which principals can assume them.
58- Understanding how these policies work is important for security.
58+ ### The Character Limit Problem
5959
60- ### The Character Limit Problem
60+ IAM role trust policies have a ** hard limit of 4096 characters** (after requesting a quota increase from the default
61+ 2048). For organizations with multiple accounts, listing every role and permission set by explicit ARN would easily
62+ exceed this limit—even with the maximum quota.
6163
62- IAM role trust policies have a ** hard limit of 4096 characters ** (after requesting a quota increase from the default
63- 2048). For organizations with multiple accounts, listing every role and permission set by explicit ARN would easily
64- exceed this limit—even with the maximum quota.
64+ Instead, the reference architecture uses wildcard ARN patterns like:
65+ - ` arn:aws:iam::*: role/acme-*-gbl-*-terraform ` for Terraform execution roles
66+ - ` arn:aws:iam::*:role/aws-reserved/sso.amazonaws.com/*/AWSReservedSSO_Terraform*Access_* ` for SSO permission sets
6567
66- Instead, the reference architecture uses wildcard ARN patterns like:
67- - ` arn:aws:iam::*:role/acme-*-gbl-*-terraform ` for Terraform execution roles
68- - ` arn:aws:iam::*:role/aws-reserved/sso.amazonaws.com/*/AWSReservedSSO_Terraform*Access_* ` for SSO permission sets
68+ ### The Two-Way Security Handshake
6969
70- ### The Two-Way Security Handshake
70+ Using wildcards in trust policies is secure because access requires a ** two-way handshake ** :
7171
72- Using wildcards in trust policies is secure because access requires a ** two-way handshake** :
72+ 1 . ** Trust Policy (this side):** The tfstate role's trust policy allows principals matching the pattern to attempt
73+ assumption, but only if they're within your AWS Organization (` aws:PrincipalOrgID ` condition).
7374
74- 1 . ** Trust Policy (this side):** The tfstate role's trust policy allows principals matching the pattern to attempt
75- assumption, but only if they're within your AWS Organization ( ` aws:PrincipalOrgID ` condition) .
75+ 2 . ** Principal's Policy (other side):** The principal (e.g., a Terraform role or SSO permission set) must also have
76+ an IAM policy granting ` sts:AssumeRole ` on the specific tfstate role ARN .
7677
77- 2 . ** Principal's Policy (other side): ** The principal (e.g., a Terraform role or SSO permission set) must also have
78- an IAM policy granting ` sts:AssumeRole ` on the specific tfstate role ARN .
78+ A role matching the wildcard pattern cannot access Terraform state unless it also has explicit permission to assume
79+ the tfstate role. This defense-in-depth approach maintains security while staying within IAM limits .
7980
80- A role matching the wildcard pattern cannot access Terraform state unless it also has explicit permission to assume
81- the tfstate role. This defense-in-depth approach maintains security while staying within IAM limits.
81+ ### Requesting a Quota Increase (If Needed)
8282
83- ### Requesting a Quota Increase (If Needed)
83+ If you customize the trust policies and approach the 2048 character default limit, you can request an increase up to
84+ the maximum of 4096 characters. Requests within this limit are auto-approved instantly:
8485
85- If you customize the trust policies and approach the 2048 character default limit, you can request an increase up to
86- the maximum of 4096 characters. Requests within this limit are auto-approved instantly:
86+ ``` bash
87+ atmos auth exec --identity core-root/terraform -- \
88+ aws service-quotas request-service-quota-increase \
89+ --service-code iam \
90+ --quota-code L-C07B4B0D \
91+ --desired-value 4096 \
92+ --region us-east-1
93+ ```
8794
88- ``` bash
89- atmos auth exec --identity core-root/terraform -- \
90- aws service-quotas request-service-quota-increase \
91- --service-code iam \
92- --quota-code L-C07B4B0D \
93- --desired-value 4096 \
94- --region us-east-1
95- ```
95+ :::note
96+ This is only needed if you customize trust policies beyond the defaults. The reference architecture's wildcard
97+ patterns fit comfortably within the default 2048 character limit.
98+ :::
9699
97- :::note
98- This is only needed if you customize trust policies beyond the defaults. The reference architecture's wildcard
99- patterns fit comfortably within the default 2048 character limit.
100- :::
100+ </details >
101101
102- </details >
102+ </Step >
103103
104104 <Step >
105105 ## <StepNumber /> Initialize the Terraform State Backend
0 commit comments