Skip to content

Feature: New Docs for account setup #896

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Benbentwo merged 2 commits into from
Mar 23, 2026
Merged

Feature: New Docs for account setup #896

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
617e81b
Feature: New Docs for account setup
Benbentwo Mar 23, 2026
0949bdf
update docs on imports
Benbentwo Mar 23, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
86 changes: 53 additions & 33 deletions docs/layers/accounts/deploy-accounts.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,13 +19,16 @@ import PrimaryCTA from '@site/src/components/PrimaryCTA';
This guide walks through deploying AWS accounts using `atmos` workflows. Before starting, ensure you have completed the [Prepare AWS Organization](/layers/accounts/prepare-aws-organization/) guide, which creates the AWS Organization, enables AWS RAM sharing, and raises account limits.
</Intro>

| 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) |
| Steps | Actions |
| --------------------------------- | -------------------------------------------------------------------------------- |
| Validate prerequisites | Review account configuration |
| Deploy Organization | `atmos workflow deploy/organization -f quickstart/foundation/accounts` |
| Deploy Organizational Units | `atmos workflow deploy/organizational-units -f quickstart/foundation/accounts` |
| Deploy accounts | `atmos workflow deploy/accounts -f quickstart/foundation/accounts` |
| Deploy Service Control Policies | `atmos workflow deploy/scps -f quickstart/foundation/accounts` |
| Update Account ID Placeholders | Update `_defaults.yaml` with real account IDs |
| Deploy account settings | `atmos workflow deploy/aws-account-settings -f quickstart/foundation/accounts` |
| Finalize account setup | Click Ops (optional) |

<Steps>
<Step>
Expand All @@ -40,70 +43,87 @@ This guide walks through deploying AWS accounts using `atmos` workflows. Before
- Terraform state backend has been initialized
</TaskList>

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.
Next, review the account configuration in the stack catalog. The reference architecture uses individual **instanced components** for each account (`aws-account/core-artifacts`, `aws-account/plat-dev`, etc.) rather than a single monolithic component. Each account is defined as a separate component instance, inheriting shared defaults from `stacks/catalog/aws-account/defaults.yaml`.

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

<TaskList>
- 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`
- Check that `stacks/catalog/aws-account/defaults.yaml` has the values you expect, especially account email format
- Run `atmos describe component aws-account/core-artifacts -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 aws-account/core-artifacts -s core-gbl-root`
Copy link
Copy Markdown

@chatgpt-codex-connector chatgpt-codex-connector bot Mar 23, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Move the initial aws-account plan after OU deployment

This checklist now tells readers to run atmos terraform plan aws-account/core-artifacts -s core-gbl-root before the organization and OU workflows have run, but the same page later says the aws-account/* components read OU IDs from aws-organizational-unit/* via !terraform.state (docs/layers/accounts/deploy-accounts.mdx, lines 84-88). On a fresh quickstart setup there is no OU state yet, so this "validation" step will fail and block the documented flow instead of helping users verify their account config.

Useful? React with 👍 / 👎.

</TaskList>
</Step>

<Step>
## <StepNumber/> Import the AWS Organization
## <StepNumber/> Deploy the AWS Organization

The AWS Organization was created manually as part of the [Prepare AWS Organization](/layers/accounts/prepare-aws-organization/) guide. Now we need to import this existing organization into Terraform so it can be managed as infrastructure-as-code.
The AWS Organization was created manually as part of the [Prepare AWS Organization](/layers/accounts/prepare-aws-organization/) guide. The `aws-organization` component uses the `import_resource_id` variable to import the existing organization into Terraform state on the first apply — no manual `terraform import` command is needed.

Import the existing AWS Organization into Terraform state using the following command. Replace `ORG_ID` with your AWS Organization ID (e.g., `o-abc123def4`):
Before running this workflow, ensure `import_resource_id` is set to your AWS Organization ID in the stack configuration. You can find your Organization ID in the AWS Console under **AWS Organizations** → **Settings**, or by running:

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

:::info Finding Your Organization ID
You can find your Organization ID in the AWS Console under **AWS Organizations** → **Settings**, or by running:
```bash
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.
This workflow also enables RAM sharing with the AWS Organization.

:::tip Verify Import
After the import completes, verify the organization was imported successfully:
<AtmosWorkflow workflow="deploy/organization" fileName="quickstart/foundation/accounts" />

:::tip Verify Deployment
After the workflow completes, verify the organization is under management with no drift:
```bash
atmos terraform plan account -s core-gbl-root
atmos terraform plan aws-organization -s core-gbl-root
```
The plan should show no changes for the organization resource, indicating it was imported correctly.
The plan should show no changes, indicating the organization was imported and configured correctly.
:::
</Step>

<Step>
## <StepNumber/> Deploy Organizational Units

Organizational Units (OUs) group your accounts by function. The reference architecture uses separate `aws-organizational-unit/*` instanced components for each OU (e.g. `core` and `plat`). The OU IDs are consumed by the account components via `!terraform.state`.

Like the organization component, each `aws-organizational-unit/*` component supports `import_resource_id` if you need to adopt existing OUs into Terraform management.

<AtmosWorkflow workflow="deploy/organizational-units" fileName="quickstart/foundation/accounts" />
</Step>

<Step>
## <StepNumber/> 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.
Review the account configuration one final time before creating accounts. Each account is provisioned as a separate instanced component (e.g. `aws-account/core-artifacts`, `aws-account/plat-dev`). In particular, check the email addresses and account names.

Each `aws-account/*` component also supports `import_resource_id` if you need to adopt existing accounts into Terraform management.

Once confident, begin the accounts deployment:

<AtmosWorkflow workflow="deploy/accounts" fileName="quickstart/foundation/accounts" />

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

<Step>
## <StepNumber/> Deploy Service Control Policies

Service Control Policies (SCPs) set permission guardrails across your organization. This workflow deploys policies that prevent accounts from leaving the organization and restrict IAM user creation.

<AtmosWorkflow workflow="deploy/scps" fileName="quickstart/foundation/accounts" />
</Step>

<Step>
## <StepNumber/> 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:
To get your account IDs, run the output command for any account component:

```bash
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
atmos terraform output aws-account/core-audit -s core-gbl-root
atmos terraform output aws-account/plat-dev -s core-gbl-root
# ... repeat for each account
```

**Update the Static Account Map**
Expand Down Expand Up @@ -167,16 +187,16 @@ This guide walks through deploying AWS accounts using `atmos` workflows. Before
</Step>

<Step>
## <StepNumber/> Deploy Accounts Settings
## <StepNumber/> Deploy Account Settings

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

<AtmosWorkflow workflow="deploy/account-settings" fileName="quickstart/foundation/accounts" />
<AtmosWorkflow workflow="deploy/aws-account-settings" fileName="quickstart/foundation/accounts" />

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

<Step>
## <StepNumber/> Unsubscribe from Marketing Emails (Optional)

Expand Down
1 change: 1 addition & 0 deletions examples/snippets/stacks/workflows/quickstart/foundation/accounts.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -96,6 +96,7 @@ workflows:
description: Deploy Service Control Policies
steps:
- command: terraform deploy aws-scp/deny-leaving-organization -s core-gbl-root
- command: terraform deploy aws-scp/deny-creating-users -s core-gbl-root

deploy/aws-account-settings:
description: Apply AWS Account settings for best practices.
Expand Down
Loading