Skip to main content
Sponsor @cloudposse

Deploying AWS Accounts

This step-by-step process outlines how to deploy AWS accounts using atmos workflows and ClickOps steps. It covers necessary preparations, such as configuring the AWS Organization, increasing account quotas, and verifying account configurations. The guide details the deployment processes and post-deployment configurations, including setting up account settings, enabling AWS RAM for Organizations, and performing certain manual configurations via ClickOps.

StepsActions
Deploy AWS Organizationatmos workflow deploy/organization -f accounts
Prepare accounts creationClick Ops
Deploy accountsatmos workflow deploy/accounts -f accounts
Deploy accounts settingsatmos workflow deploy/account-settings -f accounts
Finalize account setupClick Ops

1 Prepare Account Deployment​

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:

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

2 Deploy the AWS Organization​

deploy/organization:
These are the commands included in the deploy/organization workflow in the examples/snippets/stacks/workflows/accounts.yaml file:
    No commands found

Too many commands? Consider using the Atmos workflow! 🚀

3 Confirm the Root Account is configured as an Organization​

The previous step will create the AWS Organization and configure the core-root account as the "root" account. Take the time now to verify that the root account is configured as an AWS Organization and that AWS RAM for Organizations is enabled, which is required for connecting the Organization.

Check Organization Status:

# Check if AWS Organization exists and get its details
aws organizations describe-organization

# Or specifically check if RAM for Organizations is enabled
aws organizations describe-organization --query 'Organization.FeatureSet'

The FeatureSet should return ALL if RAM for Organizations is enabled, or CONSOLIDATED_BILLING if it's not enabled.

4 Confirm Root Account Name​

After deploying the AWS Organization, verify the account name of the root (a.k.a. management/payer) account and ensure it's set in the account-map catalog. This is the human-readable account name, not the account alias. While we default to root, it may have been set to your company name or another custom label when the account was originally created.

Why this is needed?

The root account has two different names:

  • AWS Account Name: The name you typed when originally creating the AWS account (often "root" but can be different)
  • Account Alias: The deterministic name set in the account configuration (e.g., "core-root")

The account-map component needs to know the actual AWS account name to properly map accounts.

To find your root account name:

# Make sure you're using a user with access to your root account, such as SuperAdmin
aws organizations list-accounts \
  --query "Accounts[?Id=='$(aws organizations describe-organization --query 'Organization.MasterAccountId' --output text)'].Name" \
  --output text

To configure the account-map:

Update stacks/catalog/account-map.yaml to set the correct root account name:

components:
  terraform:
    account-map:
      vars:
        root_account_aws_name: "your-actual-root-account-name"  # The name from the AWS Organizations output
        root_account_account_name: "core-root"  # This should always be "core-root"
Common Issue:

If you encounter an error such as the following in subsequent deployments, it's usually because the root_account_aws_name is not correctly set in the account-map configuration.

The given key does not identify an element in this collection value

5 Raise Account Limits​

If you haven't already completed the Account Quota increase, now is the time to do so. To deploy all accounts, we need to request an increase of the Account Quota from AWS support, which requires an AWS Organization to be created first.

From the root account (not SuperAdmin), increase the account quota to 20+ for the Cloud Posse reference architecture, or more depending on your business use-case.

Alternative: Use AWS CLI

You can also use the AWS CLI to request the quota increase:

aws service-quotas request-service-quota-increase \
  --service-code organizations \
  --quota-code L-29A42BEB \
  --desired-value 20

Where L-29A42BEB is the quota code for "Accounts per organization".

Terraform Alternative:

This quota increase can also be requested through our account-quotas component, but it's generally faster to handle this manually or through the API since it's a one time request.

6 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:

deploy/accounts:
These are the commands included in the deploy/accounts workflow in the examples/snippets/stacks/workflows/accounts.yaml file:
    No commands found

Too many commands? Consider using the Atmos workflow! 🚀

Info:

With the addition of support for dynamic Terraform roles, our baseline cold start refarch layer now depends on/requires that we have aws-teams and aws-team-roles stacks configured. This is because account-map uses those stacks to determine which IAM role to assume when performing Terraform in the account, and almost every other component uses account-map (indirectly) to chose the role to assume. However, these components do not need to be deployed yet.

These deployments will create all AWS member accounts and store relevant account metadata as "mappings" in the Terraform outputs of the account-map component. Rather than querying this account component each time we need an Account ID or role, we provision a static component account-map.

Important:

Always run atmos terraform apply account-map -s core-gbl-root after provisioning accounts.

7 Deploy Accounts Settings​

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

deploy/account-settings:
These are the commands included in the deploy/account-settings workflow in the examples/snippets/stacks/workflows/accounts.yaml file:
    No commands found

Too many commands? Consider using the Atmos workflow! 🚀

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

8 ClickOps to Complete Account Setup​

For each new account, you will need to perform some manual configurations via ClickOps. These configurations include setting up the root account credentials, enabling MFA, and unsubscribing the account's email address from all marketing emails.

  1. Reset the root user password:

    1. Perform a password reset by attempting to log in to the AWS console as a "root user" using that account's email address

    2. Click the "Forgot password?" link

    3. You will receive a password reset link via email, which should be forwarded to the shared Slack channel for automated messages. Click the link

    4. Enter a new password

      Tip:

      Use 1Password to create a password 26-38 characters long, including at least 3 of each class of character: lower case, uppercase, digit, and symbol

    5. Save the email address and generated password as web login credentials in 1Password

    6. Finally, record the account number in a separate field of the 1Password item, and save it. This is optional but recommended.

  2. Configure MFA:

    1. Log in to the AWS console using the new password
    2. Choose "My Security Credentials" from the account dropdown menu
    3. Set up Multi-Factor Authentication (MFA) to use a Virtual MFA device
    4. Save the MFA TOTP key in 1Password with 1Password's "One-Time Password" field
    5. Enter the generated MFA codes in AWS to verify the MFA device
    6. Save the Virtual MFA ARN in the same 1Password entry. We will need this to set up the MFA device for SuperAdmin in Leapp

  3. Enable any necessary optional regions

  4. Optional, but highly recommended - unsubscribe the account's email address from all 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"

For more details, review the detailed "AWS Cold Start" documentation.