diff --git a/docs/layers/accounts/deploy-accounts.mdx b/docs/layers/accounts/deploy-accounts.mdx index e96b9bb26..482f9405d 100644 --- a/docs/layers/accounts/deploy-accounts.mdx +++ b/docs/layers/accounts/deploy-accounts.mdx @@ -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. -| 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) | @@ -40,57 +43,73 @@ This guide walks through deploying AWS accounts using `atmos` workflows. Before - 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. + 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: - - 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` - ## Import the AWS Organization + ## 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: + + + :::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. ::: + + ## 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. + + + + ## 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: This workflow creates all AWS member accounts in the AWS Organization using the configuration in your stack files. + + + ## 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. + + @@ -98,12 +117,13 @@ This guide walks through deploying AWS accounts using `atmos` workflows. Before 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** @@ -167,16 +187,16 @@ This guide walks through deploying AWS accounts using `atmos` workflows. Before - ## Deploy Accounts Settings + ## Deploy Account Settings Once you've created the accounts, you'll need to provision the baseline configuration within the accounts themselves. Run the following: - + The workflows will kick off several sequential Terraform runs to provision all the AWS member account settings for member accounts in the Organization. - + ## Unsubscribe from Marketing Emails (Optional) diff --git a/examples/snippets/stacks/workflows/quickstart/foundation/accounts.yaml b/examples/snippets/stacks/workflows/quickstart/foundation/accounts.yaml index 42357feb8..60c4529b4 100644 --- a/examples/snippets/stacks/workflows/quickstart/foundation/accounts.yaml +++ b/examples/snippets/stacks/workflows/quickstart/foundation/accounts.yaml @@ -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.