diff --git a/docs/layers/accounts/deploy-accounts.mdx b/docs/layers/accounts/deploy-accounts.mdx
index 9944864d7..2f476c03f 100644
--- a/docs/layers/accounts/deploy-accounts.mdx
+++ b/docs/layers/accounts/deploy-accounts.mdx
@@ -2,7 +2,7 @@
title: "Deploying AWS Accounts"
sidebar_label: "Deploy Accounts"
sidebar_position: 4
-description: Deploy AWS accounts with `atmos` workflows and ClickOps.
+description: Deploy AWS accounts with `atmos` workflows.
---
import Intro from '@site/src/components/Intro';
import KeyPoints from '@site/src/components/KeyPoints';
@@ -16,79 +16,59 @@ import ActionCard from '@site/src/components/ActionCard';
import PrimaryCTA from '@site/src/components/PrimaryCTA';
-This step-by-step process outlines how to deploy AWS accounts using `atmos` workflows and ClickOps steps. It covers necessary preparations, such as configuring the AWS Organization, increasing account quotas, and verifying account configurations. The guide details the deployment processes and post-deployment configurations, including setting up account settings, enabling AWS RAM for Organizations, and performing certain manual configurations via ClickOps.
+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 |
-| ------------------------- | ---------------------------------------------------- |
-| Deploy AWS Organization | `atmos workflow deploy/organization -f quickstart/foundation/accounts` |
-| Prepare accounts creation | Click Ops |
-| 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 |
+| Steps | Actions |
+| ---------------------------- | --------------------------------------------------------------------------- |
+| Validate prerequisites | Review account configuration |
+| Import AWS Organization | `atmos workflow deploy/organization -f quickstart/foundation/accounts` |
+| 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) |
- ## Prepare Account Deployment
+ ## Validate Prerequisites for Account Deployment
- 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.
+ Before deploying accounts, verify that you have completed all prerequisites from the [Prepare AWS Organization](/layers/accounts/prepare-aws-organization/) guide:
+
+
+ - AWS Organization has been created via ClickOps
+ - AWS RAM sharing with AWS Organization is enabled
+ - Account quota increase has been requested (and ideally approved)
+ - 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.
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)
+ - 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`
- ## Deploy the AWS Organization
-
-
-
-
-
-
- ## Confirm the Root Account is configured as an Organization
-
- 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.
+ ## Import the AWS Organization
- **Check Organization Status:**
+ 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.
- ```bash
- # Check if AWS Organization exists and get its details
- aws organizations describe-organization
+ Run the organization workflow, which will import the existing AWS Organization into Terraform state:
- # Or specifically check if RAM for Organizations is enabled
- aws organizations describe-organization --query 'Organization.FeatureSet'
- ```
-
- The `FeatureSet` should return `ALL` if RAM for Organizations is enabled, or `CONSOLIDATED_BILLING` if it's not enabled.
-
-
-
- ## Raise Account Limits
-
- 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.
-
- 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.
-
- **Alternative: Use AWS CLI**
+
- You can also use the AWS CLI to request the quota increase:
+ This workflow 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.
+ :::tip Verify Import
+ After the workflow completes, verify the organization was imported successfully:
```bash
- aws service-quotas request-service-quota-increase \
- --service-code organizations \
- --quota-code L-E619E033 \
- --desired-value 20
+ atmos terraform plan account -s core-gbl-root
```
-
- Where `L-E619E033` is the quota code for "Default maximum number of accounts" under "AWS Organizations" in "us-east-1".
+ The plan should show no changes for the organization resource, indicating it was imported correctly.
+ :::
diff --git a/docs/layers/accounts/prepare-aws-organization.mdx b/docs/layers/accounts/prepare-aws-organization.mdx
index ba2f35570..abd88e9d5 100644
--- a/docs/layers/accounts/prepare-aws-organization.mdx
+++ b/docs/layers/accounts/prepare-aws-organization.mdx
@@ -59,15 +59,73 @@ From the root account:
For more details, see [Centralized Root Access](/layers/identity/centralized-root-access/).
1. ### 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](https://docs.aws.amazon.com/accounts/latest/reference/manage-acct-regions.html).
-1. ### Prepare for Account Quota Increase
- In order to deploy all accounts, you need to request an increase of the Account Quota from AWS support. This requires an AWS Organization to be created first, which we will create with Terraform in the [Deploy Accounts guide](/layers/accounts/deploy-accounts/#-prepare-account-deployment). This request can take a few days to process, so it's important to get it started early so that it doesn't become a blocker.
+1. ### 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](https://console.aws.amazon.com/organizations/v2/home)
+ 1. Click **Create an organization**
+ 1. Select **Create an organization with all features enabled** (this enables AWS RAM for Organizations)
+ 1. Confirm the organization creation
+
+
+ :::tip Verify Organization Creation
+ After creating the organization, verify it was created successfully:
+ ```bash
+ aws organizations describe-organization
+ ```
+ The `FeatureSet` should return `ALL` if all features are enabled.
+ :::
+
+1. ### 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](https://console.aws.amazon.com/organizations/v2/home/accounts)
+ 1. Locate the management account (marked with a star)
+ 1. Verify the account name matches your expected root account name
+ 1. If needed, rename the account by clicking the account and selecting **Edit**
+
+
+1. ### 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](https://console.aws.amazon.com/ram/home#Settings:)
+ 1. Enable **Enable sharing with AWS Organizations**
+ 1. Confirm the setting is enabled
+
+
+ **Alternative: Use AWS CLI**
+ ```bash
+ aws ram enable-sharing-with-aws-organization
+ ```
+
+ Verify the setting:
+ ```bash
+ aws organizations describe-organization --query 'Organization.FeatureSet'
+ ```
+ This should return `ALL`.
+
+1. ### 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+](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.
+
+ **Alternative: Use AWS CLI**
+ ```bash
+ 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".
- At this time we don't need to request the increase, but we should be prepared to do so as soon as the AWS Organization is created.
+ :::caution Processing Time
+ Account quota increases can take several days to be approved. Plan accordingly and submit this request as early as possible.
+ :::
- Now that your AWS Organization is prepared with MFA, SuperAdmin credentials, and billing access configured,
- you're ready to initialize the Terraform state backend that will store all infrastructure state.
+ 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