Skip to content

Commit 8475d41

Browse files
Benbentwoclaude
andauthored
Fix step numbering on tfstate initialization docs (#882)
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
1 parent 894c461 commit 8475d41

1 file changed

Lines changed: 36 additions & 36 deletions

File tree

docs/layers/accounts/initialize-tfstate.mdx

Lines changed: 36 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -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

Comments
 (0)