Skip to main content

Preparing Your AWS Organization

The Cold Start involves more manual steps than other layers. Read through the following steps and see the detailed documentation for edge cases.

In short, the steps are...

#StepsActions
1Install requirements
2Vendor componentstask workflow vendor -f baseline
3Configure AWS-Root super-admin-userClick Ops
Cold Start

The set up process for the "baseline" or "account" layer is commonly referred to as the Cold Start.

Prerequisites​

Follow the prerequisites steps in the How-to Get Started guide.

Start your Geodesic shell before continuing.

AWS Organizations Setup​

AWS Organizations enables multi-account governance using foundational Organizational Units (OUs) as recommended by AWS Security Reference Architecture (SRA). The OU model groups accounts by function (Security, Infrastructure, Workloads), not by environment.

Prerequisite ClickOps (Management Account Only)​

The management account (aws-admin) is adopted — not vended by Terraform. One-time manual setup required:

  1. Enable AWS Organizations​

    In the AWS Management Console, navigate to AWS Organizations and enable it. This establishes the management account as the org root. Organizations can be enabled without infrastructure changes; it is the prerequisite for all subsequent Terraform provisioning.

  2. Create super-admin-user (if not present)​

    Create an IAM user (super-admin-user) with AdministratorAccess policy and MFA enabled. This user bootstraps Terraform authentication until IAM Identity Center assumes the role.

  3. Enable Business Class Support (Optional)​

    Navigate to AWS Support and enable Business support. This accelerates AWS account limit increases required for large landing zones.

For additional edge cases (MFA setup, secondary regions), see detailed cold-start guide.

Terraform-Managed Infrastructure​

All subsequent account structure is provisioned by Terraform:

  • Organizational Units (OUs): Security, Infrastructure, Workloads (with Prod/Non-Prod children) — AWS SRA recommended model
  • Account vending: b2b-prod and b2b-non-prod accounts created and moved to appropriate OUs
  • Tag Policy: enforces FOCUS 1.2-compliant tags (CostCenter, Owner, Environment, ManagedBy) at org root
  • Baseline SCPs: deny org leave, deny root user actions, require mandatory tags

See infra/terraform/aws/accounts/ for the complete Terraform root module. The Organizations module sources terraform-aws/modules/organizations — pinned to release tags in production, local submodule for development iteration.

IAM Identity Center Setup​

Once Organizations is enabled, enable IAM Identity Center in Sydney (ap-southeast-2) via the AWS Console. Choose "Enable with AWS Organizations" to enable org-level SSO. See IAM Identity Center guide for permission-set provisioning (all managed by Terraform thereafter).