Skip to main content
Latest Documentation
This is the latest documentation for the Cloud Posse Reference Architecture. To determine which version you're currently using, please see Version Identification.
Version: Latest
Sponsor @cloudposse

Initializing the Terraform State S3 Backend

Follow these steps to configure and initialize the Terraform state backend using Atmos, ensuring proper setup of the infrastructure components and state management.

StepsActions
Configure Terraform stateatmos workflow init/tfstate -f quickstart/foundation/accounts

Setting up the Terraform State Backend​

This is where we configure and run Atmos. Atmos is a workflow automation tool that we will use to call Terraform which will provision all the accounts and resources you need to create and manage infrastructure. The Atmos configuration can be found in the atmos.yaml.

If you're unfamiliar with atmos, you can read more about it here.

If you look at components/terraform/, you'll see a bunch of directories. These contain Terraform "root modules" that are provisioned with Atmos. At first they'll only have their vendor files, such as components/terraform/tfstate-backend/component.yaml.

1 Vendor the Terraform State Backend component​

Vendor the Terraform State Backend component by running the following command.

What is Vendoring?

Vendoring downloads the upstream component files from a central repository at a specified version. In this case, we are pulling the baseline components, which include all account components, the Terraform State component, and other necessary files for setting up the account foundation.

This step only downloads the files to your local project - it does not deploy or make any changes to your infrastructure.

Read more about vendoring with Atmos

Loading workflow...
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 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.

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​

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).

  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.

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:

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.

2 Initialize the Terraform State Backend​

Run the following command to initialize the Terraform State Backend. This workflow has two steps:

  • Create the backend using a local Terraform state
  • Once the backend bucket exists, migrate the state file into the newly created S3 bucket
Loading workflow...

3 Migrate all workspaces to S3​

When prompted, type yes to migrate all workspaces to S3.

Initializing the backend...
Do you want to migrate all workspaces to "s3"?
Granting SuperAdmin Access to Terraform State

The IAM User for SuperAdmin will be granted access to Terraform State by principal ARN. This ARN is passed to the tfstate-backend stack catalog under allowed_principal_arns. Verify that this ARN is correct now. You may need to update the root account ID.

References​

Next Steps

Now that the Terraform state backend is initialized, you're ready to deploy all AWS accounts in your organization. Deploy Accounts