Skip to content

Commit 0a1328d

Browse files
milldrosterman
milldr
and
osterman
authored
DEV-3477: Account Documentation (#785)
Co-authored-by: Erik Osterman (CEO @ Cloud Posse) <[email protected]>
1 parent 3ab7327 commit 0a1328d

File tree

6 files changed

+588
-405
lines changed

6 files changed

+588
-405
lines changed

‎docs/layers/accounts/deploy-accounts.mdx‎

Lines changed: 91 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -41,7 +41,7 @@ This step-by-step process outlines how to deploy AWS accounts using `atmos` work
4141
</Step>
4242

4343
<Step>
44-
## <StepNumber/> Deploy the AWS Organization:
44+
## <StepNumber/> Deploy the AWS Organization
4545

4646
<AtmosWorkflow workflow="deploy/organization" fileName="accounts" />
4747

@@ -50,34 +50,109 @@ This step-by-step process outlines how to deploy AWS accounts using `atmos` work
5050
<Step>
5151
## <StepNumber/> Confirm the Root Account is configured as an Organization
5252

53-
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](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_enable-ram.html) is enabled, which is required for connecting the Organization.
53+
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](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_enable-ram.html) is enabled, which is required for connecting the Organization.
54+
55+
**Check Organization Status:**
56+
57+
```bash
58+
# Check if AWS Organization exists and get its details
59+
aws organizations describe-organization
60+
61+
# Or specifically check if RAM for Organizations is enabled
62+
aws organizations describe-organization --query 'Organization.FeatureSet'
63+
```
64+
65+
The `FeatureSet` should return `ALL` if RAM for Organizations is enabled, or `CONSOLIDATED_BILLING` if it's not enabled.
66+
</Step>
67+
68+
<Step>
69+
## <StepNumber/> Confirm Root Account Name
70+
71+
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.
72+
73+
<details>
74+
<summary><strong>Why this is needed?</strong></summary>
75+
76+
The root account has two different names:
77+
78+
- **AWS Account Name**: The name you typed when originally creating the AWS account (often "root" but can be different)
79+
- **Account Alias**: The deterministic name set in the account configuration (e.g., "core-root")
80+
</details>
81+
82+
The account-map component needs to know the actual AWS account name to properly map accounts.
83+
84+
**To find your root account name:**
85+
86+
```bash
87+
# Make sure you're using a user with access to your root account, such as SuperAdmin
88+
aws organizations list-accounts \
89+
--query "Accounts[?Id=='$(aws organizations describe-organization --query 'Organization.MasterAccountId' --output text)'].Name" \
90+
--output text
91+
```
92+
93+
**To configure the account-map:**
94+
95+
Update `stacks/catalog/account-map.yaml` to set the correct root account name:
96+
97+
```yaml
98+
components:
99+
terraform:
100+
account-map:
101+
vars:
102+
root_account_aws_name: "your-actual-root-account-name" # The name from the AWS Organizations output
103+
root_account_account_name: "core-root" # This should always be "core-root"
104+
```
105+
106+
<Note title="Common Issue">
107+
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.
108+
109+
```console
110+
The given key does not identify an element in this collection value
111+
```
112+
</Note>
54113
</Step>
55114

56115
<Step>
57116
## <StepNumber/> Raise Account Limits
58117

59118
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.
60119

61-
From the `root` account (not `SuperAdmin`), increase the [account quota to 20+](https://us-east-1.console.aws.amazon.com/servicequotas/home/services/organizations/quotas) for the Cloud Posse reference architecture, or more depending on your business use-case
120+
From the `root` account (not `SuperAdmin`), increase the [account quota to 20+](https://us-east-1.console.aws.amazon.com/servicequotas/home/services/organizations/quotas) for the Cloud Posse reference architecture, or more depending on your business use-case.
62121

122+
**Alternative: Use AWS CLI**
123+
124+
You can also use the AWS CLI to request the quota increase:
125+
126+
```bash
127+
aws service-quotas request-service-quota-increase \
128+
--service-code organizations \
129+
--quota-code L-29A42BEB \
130+
--desired-value 20
131+
```
132+
133+
Where `L-29A42BEB` is the quota code for "Accounts per organization".
134+
135+
<Note title="Terraform Alternative">
136+
This quota increase can also be requested through our [account-quotas](/components/library/aws/account-quotas/) component, but it's generally faster to handle this manually or through the API since it's a one time request.
137+
</Note>
63138
</Step>
64139

65140
<Step>
66141
## <StepNumber/> Deploy Accounts
67142

68-
<Note title="Important">
143+
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.
144+
145+
Once confident, begin the accounts deployment:
146+
147+
<AtmosWorkflow workflow="deploy/accounts" fileName="accounts" />
148+
149+
<Note title="Info">
69150
With the addition of support for dynamic Terraform roles, our `baseline` cold start refarch layer now depends
70151
on/requires that we have `aws-teams` and `aws-team-roles` stacks configured. This is because `account-map` uses those
71152
stacks to determine which IAM role to assume when performing Terraform in the account, and almost every other component
72153
uses `account-map` (indirectly) to chose the role to assume. However, these components do _not_ need to be deployed yet.
73154
</Note>
74155

75-
Again verify the "account" configuration in `stacks/catalog/account.yaml`. In the next step, we will create and configure all accounts in the AWS Organization using the configuration in that stack file.
76-
77-
Once confident, begin the accounts deployment:
78-
79-
<AtmosWorkflow workflow="deploy/accounts" fileName="accounts" />
80-
81156
These deployments will create all AWS member accounts and store relevant account metadata as "mappings" in the Terraform
82157
outputs of the `account-map` component. Rather than querying this `account` component each time we need an Account ID or
83158
role, we provision a static component `account-map`.
@@ -86,14 +161,19 @@ This step-by-step process outlines how to deploy AWS accounts using `atmos` work
86161
Always run `atmos terraform apply account-map -s core-gbl-root` after provisioning accounts.
87162
</Note>
88163

164+
</Step>
165+
166+
<Step>
167+
## <StepNumber/> Deploy Accounts Settings
168+
89169
Once you've created the accounts, you'll need to provision the baseline configuration within the accounts themselves. Run the following:
90170

91171
<AtmosWorkflow workflow="deploy/account-settings" fileName="accounts" />
92172

93173
The workflows will kick off several sequential Terraform runs to provision all the AWS member account settings for
94174
member accounts in the Organization.
95175
</Step>
96-
176+
97177
<Step>
98178
### <StepNumber/> ClickOps to Complete Account Setup
99179

‎docs/layers/accounts/faq.mdx‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@ sidebar_label: FAQ
44
sidebar_position: 10
55
---
66
import Intro from '@site/src/components/Intro';
7+
import Steps from '@site/src/components/Steps';
78

89
<Intro>
910
Frequently asked questions about managing AWS accounts with Cloud Posse's reference architecture.
@@ -52,3 +53,67 @@ This component manages the state of all AWS accounts, so apply with extreme caut
5253
### How can you create a Tenant?
5354

5455
[Follow the documentation for creating a new Organizational Unit](/layers/accounts/tutorials/how-to-add-a-new-organizational-unit/)
56+
57+
### Why does `account-map` fail with "The given key does not identify an element in this collection value"?
58+
59+
This is a common error you may encounter when reading from `account-map`:
60+
61+
```bash
62+
Acquiring state lock. This may take a few moments...
63+
module.iam_roles.module.account_map.data.utils_component_config.config[0]: Reading...
64+
module.iam_roles.module.account_map.data.utils_component_config.config[0]: Read complete after 0s [id=xyx]
65+
module.iam_roles.module.account_map.data.terraform_remote_state.data_source[0]: Reading...
66+
module.iam_roles.module.account_map.data.terraform_remote_state.data_source[0]: Read complete after 5s
67+
module.iam_roles.data.awsutils_caller_identity.current[0]: Reading...
68+
module.iam_roles.data.awsutils_caller_identity.current[0]: Read complete after 1s [id=123]
69+
70+
Planning failed. Terraform encountered an error while generating this plan.
71+
72+
╷
73+
│ Error: Invalid index
74+
│
75+
│ on ../account-map/modules/iam-roles/main.tf line 46, in locals:
76+
│ 46: is_root_user = local.current_identity_account == local.account_map.full_account_map[local.root_account_name]
77+
│ ├────────────────
78+
│ │ local.account_map.full_account_map is map of string with 12 elements
79+
│ │ local.root_account_name is "core-root"
80+
│
81+
│ The given key does not identify an element in this collection value.
82+
╵
83+
Releasing state lock. This may take a few moments...```
84+
```
85+
86+
This error typically occurs when the `root_account_aws_name` is not correctly configured in the `account-map` component. The root account has two different names:
87+
88+
<Steps>
89+
- **AWS Account Name**: The name you typed when originally creating the AWS account (often "root" but can be different)
90+
- **Account Alias**: The deterministic name set in the account configuration (e.g., "core-root")
91+
</Steps>
92+
93+
To fix this:
94+
95+
<Steps>
96+
1. Find your root account name using AWS Organizations:
97+
```bash
98+
aws organizations list-accounts \
99+
--query "Accounts[?Id=='$(aws organizations describe-organization --query 'Organization.MasterAccountId' --output text)'].Name" \
100+
--output text
101+
```
102+
103+
2. Update `stacks/catalog/account-map.yaml`:
104+
```yaml
105+
components:
106+
terraform:
107+
account-map:
108+
vars:
109+
root_account_aws_name: "your-actual-root-account-name" # The name from step 1
110+
root_account_account_name: "core-root" # This should always be "core-root"
111+
```
112+
113+
3. Reapply the account-map:
114+
```bash
115+
atmos terraform apply account-map -s core-gbl-root
116+
```
117+
</Steps>
118+
119+
For more details, see [the account deployment documentation](/layers/accounts/deploy-accounts/#confirm-root-account-name).

0 commit comments

Comments
 (0)