Preparing Your AWS Organization

The Cold Start involves more manual steps than other layers. Read through the following steps carefully.

Cold Start

The set up process for the "baseline" or "account" layer is commonly referred to as the Cold Start.

About Placeholder Values

The reference architecture includes placeholder values that you'll need to replace with your actual configuration. Common placeholders include:

• Account IDs like 111111111111, 123456789012, or 000000000000 — Replace with your actual AWS account IDs after creating accounts
• Underscored values like _example_ or __REPLACE_ME__ — These indicate values that require your input. Search for _ACCOUNT_NUMBER__ to find items to replace like __DEV_ACCOUNT_NUMBER__
• Example domains like example.com or acme.com — Replace with your actual domain names
• Sample ARNs — Update with ARNs from your environment

You'll update these values at different points during setup. Each guide will call out when specific replacements are needed.

Before Running Terraform (ClickOps)

First, you'll need to perform some ClickOps to ensure things are set up before we use Terraform to manage AWS accounts.

From the root account:

1. Get Business Class Support

   Enable business support in the root account (in order to expedite requests to raise the AWS member account limits)

2. Set up MFA on Root Account

   Set up the Virtual MFA device on the root account following the AWS documentation.

   1. Navigate to the root account's security credentials
   2. Set up a Virtual MFA device
   3. Save the MFA TOTP key in 1Password using 1Password's TOTP field and built-in screen scanner to scan the QR code

3. Create the SuperAdmin IAM User

   Create a SuperAdmin IAM User. This break-glass user is used during cold start bootstrapping before IAM Identity Center is provisioned. After cold start, it should only be used if your IdP is completely unavailable—otherwise, use Permission Sets.

   1. Create the IAM user (do not enable "console login")
   2. Set up MFA for the user
   3. Create a single Access Key
   4. Store credentials in 1Password: Access Key ID, Secret Access Key, Assigned MFA device ARN, and TOTP key

4. Configure Atmos Auth for SuperAdmin

   Configure the superadmin profile to authenticate via Atmos during cold start. This allows you to run Atmos commands to deploy the foundation.

   1. Set the ATMOS_PROFILE environment variable to select the superadmin profile:

      export ATMOS_PROFILE=superadmin

   2. Configure your user credentials by running the following command. You'll be prompted to enter your Access Key ID, Secret Access Key, and MFA ARN from 1Password:

      atmos auth user configure

   3. Start an authenticated session. You'll be prompted to enter a one-time MFA token:

      atmos auth login

   4. Verify you can access the root account:

      atmos auth exec -- aws sts get-caller-identity

   Daily Usage

   Once the profile is set and user credentials are configured, you only need to run atmos auth login each day to start a new authenticated session.

   Atmos Profile Persistence

   Add export ATMOS_PROFILE=superadmin to your shell configuration (~/.zshrc or ~/.bashrc) to persist the setting across terminal sessions during cold start.

   After cold start is complete and Identity Center is configured, you'll switch to a different profile (e.g., devops or managers) as described in Configure Atmos Auth.

5. Enable IAM Access for Billing

   For billing users, you need to enable IAM access to billing information.

   1. As the root user, open AWS Billing Account Settings
   2. Scroll to "IAM user and role access to Billing information"
   3. Enable IAM access

6. Enable Centralized Root Access

   Enable centralized root access management to eliminate the need for per-account root credentials. This allows the management account to perform privileged root operations on member accounts without maintaining separate root passwords or MFA devices.

   1. Navigate to IAM → Root access management
   2. Enable Root credentials management
   3. Enable Privileged root actions

   For more details, see Centralized Root Access.

7. Enable Regions (Optional)

   The 17 original AWS regions are enabled by default. If you are using a region that is not enabled by default (such as Middle East/Bahrain), you need to enable it in your AWS account settings.

8. Create the AWS Organization

   Create the AWS Organization from the existing root account. This will convert your standalone account into an organization management account.

   1. Navigate to AWS Organizations
   2. Click Create an organization
   3. Select Create an organization with all features enabled (this enables AWS RAM for Organizations)
   4. Confirm the organization creation
   Verify Organization Creation

   After creating the organization, verify it was created successfully:

   aws organizations describe-organization

   The FeatureSet should return ALL if all features are enabled.

9. Confirm Root Account Name

   Verify the root account name matches your expected naming convention (typically core-root or similar). This is important for consistency across your infrastructure.

   1. Navigate to AWS Organizations → AWS accounts
   2. Locate the management account (marked with a star)
   3. Verify the account name matches your expected root account name
   4. If needed, rename the account by clicking the account and selecting Edit

10. Enable AWS RAM Sharing with AWS Organization

    Enable AWS Resource Access Manager (RAM) sharing for your organization. This is required for sharing resources like Transit Gateway, VPC subnets, and other resources across accounts.

    1. Navigate to AWS RAM Settings
    2. Enable Enable sharing with AWS Organizations
    3. Confirm the setting is enabled

    Alternative: Use AWS CLI

    aws ram enable-sharing-with-aws-organization

    Verify the setting:

    aws organizations describe-organization --query 'Organization.FeatureSet'

    This should return ALL.

11. Raise Account Limits

    Request an increase of the Account Quota from AWS support. This request can take a few days to process, so it's important to submit it early to avoid blockers during account deployment.

    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

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

    Where L-E619E033 is the quota code for "Default maximum number of accounts" under "AWS Organizations" in "us-east-1".

    Processing Time

    Account quota increases can take several days to be approved. Plan accordingly and submit this request as early as possible.

Next Steps

Now that your AWS Organization is prepared with MFA, SuperAdmin credentials, billing access configured, and the organization created with proper account limits, you're ready to initialize the Terraform state backend that will store all infrastructure state. Initialize Terraform Backend