You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/layers/accounts/deploy-accounts.mdx
+53-33Lines changed: 53 additions & 33 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -19,13 +19,16 @@ import PrimaryCTA from '@site/src/components/PrimaryCTA';
19
19
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.
@@ -40,70 +43,87 @@ This guide walks through deploying AWS accounts using `atmos` workflows. Before
40
43
- Terraform state backend has been initialized
41
44
</TaskList>
42
45
43
-
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.
46
+
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`.
47
+
48
+
**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.
44
49
45
50
You should double-check the following:
46
51
47
52
<TaskList>
48
-
- Check that `stacks/catalog/account.yaml` has the values you expect, especially account email format
49
-
- Run `atmos describe component account -s core-gbl-root` to inspect the final component configuration (e.g. _after_ all the mixins have been imported)
50
-
- Plan the run with `atmos terraform plan account -s core-gbl-root`
53
+
- Check that `stacks/catalog/aws-account/defaults.yaml` has the values you expect, especially account email format
54
+
- 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)
55
+
- Plan the run with `atmos terraform plan aws-account/core-artifacts -s core-gbl-root`
51
56
</TaskList>
52
57
</Step>
53
58
54
59
<Step>
55
-
## <StepNumber/> Import the AWS Organization
60
+
## <StepNumber/> Deploy the AWS Organization
56
61
57
-
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.
62
+
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.
58
63
59
-
Import the existing AWS Organization into Terraform state using the following command. Replace `ORG_ID` with your AWS Organization ID (e.g., `o-abc123def4`):
64
+
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:
You can find your Organization ID in the AWS Console under **AWS Organizations** → **Settings**, or by running:
67
66
```bash
68
67
aws organizations describe-organization --query 'Organization.Id' --output text
69
68
```
70
-
:::
71
69
72
-
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.
70
+
This workflow also enables RAM sharing with the AWS Organization.
73
71
74
-
:::tip Verify Import
75
-
After the import completes, verify the organization was imported successfully:
After the workflow completes, verify the organization is under management with no drift:
76
76
```bash
77
-
atmos terraform plan account -s core-gbl-root
77
+
atmos terraform plan aws-organization -s core-gbl-root
78
78
```
79
-
The plan should show no changes for the organization resource, indicating it was imported correctly.
79
+
The plan should show no changes, indicating the organization was imported and configured correctly.
80
80
:::
81
81
</Step>
82
82
83
+
<Step>
84
+
## <StepNumber/> Deploy Organizational Units
85
+
86
+
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`.
87
+
88
+
Like the organization component, each `aws-organizational-unit/*` component supports `import_resource_id` if you need to adopt existing OUs into Terraform management.
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.
96
+
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.
97
+
98
+
Each `aws-account/*` component also supports `import_resource_id` if you need to adopt existing accounts into Terraform management.
This workflow creates all AWS member accounts in the AWS Organization using the configuration in your stack files.
105
+
</Step>
93
106
107
+
<Step>
108
+
## <StepNumber/> Deploy Service Control Policies
109
+
110
+
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.
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.
100
119
101
-
To get your account IDs, run:
120
+
To get your account IDs, run the output command for any account component:
102
121
103
122
```bash
104
-
atmos terraform output account -s core-gbl-root
105
-
## or if on the latest version with instanced components:
0 commit comments