Deploying AWS Accounts

This guide walks through deploying AWS accounts using atmos workflows. Before starting, ensure you have completed the Prepare AWS Organization guide, which creates the AWS Organization, enables AWS RAM sharing, and raises account limits.

Steps	Actions
Validate prerequisites	Review account configuration
Import AWS Organization	atmos terraform import account -s core-gbl-root ...
Deploy accounts	atmos workflow deploy/accounts -f quickstart/foundation/accounts
Deploy accounts settings	atmos workflow deploy/account-settings -f quickstart/foundation/accounts
Finalize account setup	Click Ops (optional)

1 Validate Prerequisites for Account Deployment

Before deploying accounts, verify that you have completed all prerequisites from the Prepare AWS Organization guide:

• AWS Organization has been created via ClickOps
• AWS RAM sharing with AWS Organization is enabled
• Account quota increase has been requested (and ideally approved)
• Terraform state backend has been initialized

Next, review the "account" configuration in the stack catalog. This is the hardest part to change/fix once the accounts are provisioned. If you aren't confident about the email configuration, account names, or anything else, now is the time to make changes or ask for help.

You should double-check the following:

• Check that stacks/catalog/account.yaml has the values you expect, especially account email format
• Run atmos describe component account -s core-gbl-root to inspect the final component configuration (e.g. after all the mixins have been imported)
• Plan the run with atmos terraform plan account -s core-gbl-root

2 Import the AWS Organization

The AWS Organization was created manually as part of the Prepare AWS Organization guide. Now we need to import this existing organization into Terraform so it can be managed as infrastructure-as-code.

Import the existing AWS Organization into Terraform state using the following command. Replace ORG_ID with your AWS Organization ID (e.g., o-abc123def4):

atmos terraform import account -s core-gbl-root "aws_organizations_organization.this[0]" ORG_ID

Finding Your Organization ID

You can find your Organization ID in the AWS Console under AWS Organizations → Settings, or by running:

aws organizations describe-organization --query 'Organization.Id' --output text

This command runs terraform import to bring the existing AWS Organization under Terraform management. After this step, all organization-level changes will be managed through Atmos and Terraform.

Verify Import

After the import completes, verify the organization was imported successfully:

atmos terraform plan account -s core-gbl-root

The plan should show no changes for the organization resource, indicating it was imported correctly.

3 Deploy Accounts

Again review the "account" configuration in stacks/catalog/account.yaml. In particular, check the email address and account names. In the next step, we will create and configure all accounts in the AWS Organization using the configuration in that stack file.

Once confident, begin the accounts deployment:

Loading workflow...

This workflow creates all AWS member accounts in the AWS Organization using the configuration in your stack files.

4 Update Account ID Placeholders

Now that accounts are created, you have real account IDs to work with. The reference architecture contains placeholder account IDs that need to be replaced with your actual values.

To get your account IDs, run:

atmos terraform output account -s core-gbl-root
## or if on the latest version with instanced components:
atmos terraform output aws-account/core-artifacts -s core-gbl-root

Update the Static Account Map

Update the static account map in your organization's defaults file (stacks/orgs/acme/_defaults.yaml). This configuration provides account ID lookups for components that need them:

vars:
  # Static account-map variable to replace the account-map component
  # This provides account ID lookups for components that need them (e.g., cloudtrail)
  # Set to false since we're using static mapping instead of the account-map component
  account_map_enabled: false
  account_map:
    # Name of AWS partition
    aws_partition: aws
    # Name of the root account (used for organization management)
    root_account_account_name: core-root
    # Name of the audit account (used by components like cloudtrail)
    audit_account_account_name: core-audit
    # Identity account name (used by components like ecr)
    identity_account_account_name: core-root
    # Map of all account names (tenant-stage format) to their account IDs
    # TODO: Automate population of this map (e.g., from account component outputs)
    full_account_map:
      core-artifacts: "__ARTIFACTS_ACCOUNT_NUMBER__"
      core-audit: "__AUDIT_ACCOUNT_NUMBER__"
      core-auto: "__AUTO_ACCOUNT_NUMBER__"
      core-dns: "__DNS_ACCOUNT_NUMBER__"
      core-network: "__NETWORK_ACCOUNT_NUMBER__"
      core-root: "__ROOT_ACCOUNT_NUMBER__"
      core-security: "__SECURITY_ACCOUNT_NUMBER__"
      plat-dev: "__DEV_ACCOUNT_NUMBER__"
      plat-prod: "__PROD_ACCOUNT_NUMBER__"
      plat-sandbox: "__SANDBOX_ACCOUNT_NUMBER__"
      plat-staging: "__STAGING_ACCOUNT_NUMBER__"

Replace each placeholder (e.g., __ROOT_ACCOUNT_NUMBER__) with the actual 12-digit AWS account ID from the output above.

Root Account Naming Convention

The root_account_account_name variable should always be set to core-root in your stack configuration, even if your actual AWS account has a different display name. This value is used internally by components for account lookups and must match the key in full_account_map.

To verify which account is your organization's management (root) account:

1. Navigate to AWS Organizations → AWS accounts
2. Look for the account labeled "Management account"
3. Use this account's ID for the core-root entry in full_account_map

As you continue through the setup process, keep an eye out for other placeholder values in your stack configurations and replace them with actual values as needed.

Stopgap: Deploy the Identity Layer Before Continuing

Before proceeding with the remaining account steps, you need to deploy the Identity layer. The Identity layer provisions permission sets with AWS Identity Center that allow you to access each member account, which is required for deploying account settings, CloudTrail, and ECR. We're working on improving this documentation flow and the SuperAdmin profile, but for now, the Identity layer must be deployed at this point.

Deploy the Identity Layer

Deploy the Identity layer to provision permission sets for accessing each member account. Return here to finish account settings, CloudTrail, and ECR after the Identity layer is deployed. Deploy Identity Layer

5 Deploy Accounts Settings

Once you've created the accounts, you'll need to provision the baseline configuration within the accounts themselves. Run the following:

Loading workflow...

The workflows will kick off several sequential Terraform runs to provision all the AWS member account settings for member accounts in the Organization.

6 Unsubscribe from Marketing Emails (Optional)

For each new account, unsubscribe the account's email address from AWS marketing emails:

1. Go to AWS Marketing Preferences
2. Click "Unsubscribe from Email"
3. Enter the account's email address
4. Check "Unsubscribe from all AWS marketing emails"

Root User Credentials

With centralized root access enabled, member accounts do not require individual root credentials. If you need per-account root credentials, see Create Account Root Users.

Next Steps

Now that all accounts are deployed and configured, you're ready to set up CloudTrail for audit logging across your organization. Setup CloudTrail