Organization Structure

src/config/organization-structure.ts is where you define your entire AWS Organization hierarchy: which Organizational Units exist, which accounts belong to each OU, and which SCPs attach at the root, OU, or account level.

The OrganizationConstruct in the foundation package reads this object and creates or updates OUs, accounts, and SCP attachments on every deploy. It also publishes the resolved organization identifiers as CloudFormation stack outputs so later stacks can consume them as StackSet targets. OU IDs are published by default; account IDs are opt-in per account with publishAccountIdOutput.

Built-in OUs

The starter ships with six top-level OUs that match common AWS multi-account patterns:

SuspendedOU nests a CloseAccountOU (close-account-ou), which makes seven OUs in total. The two model different offboarding states, covered in Suspended vs. close-account OU below.

There is no log archive OU or account. The ObservabilityAccount in the Security OU runs the organization trail (it is the CloudTrail delegated administrator), keeps the log buckets, and receives the CIS alarm notifications on one security-alerts topic. See Delegated Administrators.

You can rename, add, or remove OUs by editing the organizationalUnits map. The OU key (e.g. SecurityOU) becomes the stack output name (SecurityOUId) and the TypeScript property name on orgVars; changing a key is a compile-time-checked rename.

The SecurityAccount, ObservabilityAccount, FinOpsAccount, and LandingZoneAccount keys are referenced by other stacks and delegated-admin config, so they set publishAccountIdOutput: true. Renaming those keys is a compile-time-checked change you will see reflected in delegated-admins.ts and the StackSet targeting.

Options

The OrganizationStructure type has a single required top-level key:

Each OrganizationRootStructure:

Each OrganizationalUnitStructure entry:

Each AccountStructure entry:

Each BudgetStructure:

Example

const mailDomain = landingZoneSettings.mailDomain.toLowerCase();

export const organizationStructure = {
  root: {
    budgetAlertRecipients: [`aws+finops@${mailDomain}`],
    serviceControlPolicies: [
      criticalSecurityGuardrailsSCP,
      protectTaggedCloudFormationStacksSCP,
      denyAllOutsidePrimaryAndSecondaryRegionsSCP,
    ],
    organizationalUnits: {
      SecurityOU: {
        name: 'security-ou',
        accounts: {
          SecurityAccount: {
            serviceControlPolicies: [protectSecurityHubConfigurationSCP],
            name: 'security-account',
            email: `aws+security@${mailDomain}`,
            publishAccountIdOutput: true,
          },
          // Runs the organization trail and keeps its logs.
          ObservabilityAccount: {
            name: 'observability-account',
            email: `aws+observability@${mailDomain}`,
            publishAccountIdOutput: true,
          },
        },
      },
      FinOpsOU: {
        name: 'finops-ou',
        accounts: {
          FinOpsAccount: {
            name: 'finops-account',
            email: `aws+finops@${mailDomain}`,
            publishAccountIdOutput: true,
          },
        },
      },
      InfrastructureOU: {
        name: 'infrastructure-ou',
        accounts: {
          LandingZoneAccount: {
            name: 'landingzone-account',
            email: `aws+landingzone@${mailDomain}`,
            publishAccountIdOutput: true,
          },
        },
      },
      DevelopmentOU: {
        name: 'workload-dev-ou',
        accounts: {
          SandboxAccount: {
            name: 'Sandbox',
            email: `sandbox@${mailDomain}`,
          },
        },
      },
      ProductionOU: {
        name: 'workload-prod-ou',
        // One budget for the combined cost of every account in this OU.
        budget: { monthlyLimit: 500 },
        accounts: {
          WorkloadAlphaAccount: {
            name: 'Workload Alpha',
            email: `aws+workload-alpha@${mailDomain}`,
          },
          // Account emails don't have to use the organization mail domain;
          // any unique, valid address works.
          WorkloadBetaAccount: {
            name: 'Workload Beta',
            email: 'team-beta+aws@example.org',
          },
        },
      },
      // Quarantines accounts for investigation: the lockdown SCP locks out their users
      // and workload roles while administrators and landing-zone automation keep
      // working, and security services stay on. Child OUs inherit the SCP.
      SuspendedOU: {
        name: 'suspended-ou',
        serviceControlPolicies: [lockdownSuspendedAccountsSCP],
        organizationalUnits: {
          // Moving an account here triggers the close-account automation, which closes
          // the account permanently. Security Hub CSPM, GuardDuty and Inspector are turned
          // off here, and Macie stops managing these accounts.
          CloseAccountOU: {
            name: 'close-account-ou',
          },
        },
      },
    },
  },
} satisfies OrganizationStructure;

export type LandingZoneOrganizationStructure = typeof organizationStructure;

The OU and account name fields are the display names shown in the AWS Organizations console; they are plain strings, not derived from organizationName. The map keys (SecurityOU, SecurityAccount) are what become the typed orgVars.<Key>Id outputs.

Budgets

An optional budget on the root, an OU, or an account creates a monthly AWS Budgets cost budget in the management account, which sees the cost of every member account. On an account it tracks that account. On an OU it tracks the combined cost of every account under it, nested OUs included. On the root it tracks the whole organization, including the management account and accounts the structure does not define. An OU or account without its own budget is only tracked by a budget above it.

Recipients get an email when actual or forecasted cost for the month exceeds the limit. A budget picks its recipients from the first of these that is set:

1. The budget's own emailAddresses.
2. The nearest budgetAlertRecipients on an OU above it (an OU budget includes its own OU's list).
3. budgetAlertRecipients on the root.

Without any of these, an account budget alerts the account's email, and an OU or root budget alerts the email of each account the structure defines under it, up to 10. Each list holds 1 to 10 addresses, the maximum AWS Budgets allows per notification (Adding email recipients to a budget notification). The starter sets budgetAlertRecipients on the root to the FinOps account email and one 500 USD budget on ProductionOU.

Suspended vs. close-account OU

The structure distinguishes two offboarding states, and the CloseAccountOU nests inside SuspendedOU on purpose.

• SuspendedOU quarantines an account while keeping it, so administrators can investigate. The lockdownSuspendedAccountsSCP denies every principal except administrators, the StackSet execution roles, and the landing zone's own automation. Existing resources keep running, but the account's own users and workload roles can no longer call AWS. Landing zone StackSets that target the whole organization keep deploying, and Security Hub CSPM, GuardDuty, Inspector, and Macie stay on, so the security baseline and detection continue during the investigation. StackSets that target specific OUs are removed from the account when it leaves those OUs: CdkBootstrapStackSet (Development and Production OUs) deletes the CDK bootstrap, including its asset bucket, so workloads can't deploy until the account moves back and is bootstrapped again. ServiceQuotasStackSet removes its stack, but the raised quotas stay.
• CloseAccountOU permanently closes an account. When this OU exists in the structure, the organization phase (LandingZoneOrganizationStack, in the management account) closes its active accounts every 8 hours. It inherits the lockdown SCP, turns Security Hub CSPM, GuardDuty, and Inspector off, and stops managing Macie. Accounts waiting for closure remain locked down; failed closures are retried on the next run.

Closed accounts remain visible in the OU with SUSPENDED status for the 90-day post-closure period. AWS can still bill resources left in a closed account, so clean up costly resources before moving an account here. If you do not want the automation at all, remove the CloseAccountOU from the structure; suspended accounts then simply stay isolated.

How it's used

The OrganizationConstruct in the organization phase (LandingZoneOrganizationStack) reads this object and:

1. Creates the AWS Organization if it does not exist
2. Creates OUs and accounts as specified
3. Attaches SCPs at root, OU, and account levels
4. Creates the monthly budgets
5. Publishes every OU ID as a <Key>Id stack output, plus an account <Key>Id output for each account marked publishAccountIdOutput: true

The landing zone stacks run from the landing zone account and read those outputs cross-account at deploy time, exposed to them as typed orgVars properties. LandingZoneOrganizationStack just has to be deployed before the stacks that consume its outputs.

Things to know

• Keep the FinOpsOU → FinOpsAccount entry. FinOpsAccount is registered as the delegated administrator for Compute Optimizer, Cost Optimization Hub, and Resource Explorer in delegated-admins.ts, and the FinOps StackSet targets it by its published account ID.
• Keep the SecurityOU accounts. The security account administers the security services, and the observability account runs the organization trail. Never suspend or close the management, landing zone, security, or observability accounts.
• Account email addresses must be globally unique across all of AWS. The aws+<alias>@<domain> pattern is a reliable way to generate unique addresses under a single domain.
• AWS Organizations limits SCPs to 10 directly attached per attachment point (root, OU, or account). Inherited SCPs do not count against a child's own quota. OrganizationConstruct validates the structure at synth time: it fails when a node configures more than 10 SCPs or a policy document exceeds 10,240 characters, and warns when a node or policy approaches the limit. This check excludes FullAWSAccess and other policies attached outside the configuration. With FullAWSAccess attached, configure at most 9 additional SCPs at that attachment point, and check existing attachments before deploying.
• Account IDs are opt-in. OU IDs are always published, but an account only gets a <Key>Id output (and an orgVars.<Key>Id property) when you set publishAccountIdOutput: true. Reserve it for accounts other stacks reference by ID, such as the security, observability, FinOps, and landing zone accounts. A StackSet that targets a whole OU never needs one. Keep published outputs within the CloudFormation per-stack output limit.
• Renaming an account or OU key (e.g. WorkloadAlphaAccount → AppAlphaAccount) changes the stack output name and breaks every stack that references orgVars.WorkloadAlphaAccountId. The TypeScript type LandingZoneOrganizationStructure makes these renames compile-time errors, so you'll catch them before deploy.
• Declared accounts move only through this file. To suspend or close an account declared here, move its entry under SuspendedOU or CloseAccountOU and deploy the organization phase. Don't move a declared account in the AWS Organizations console: the next update to that account's resource, such as a tag change, moves it back to its configured parent. Accounts this file doesn't declare can be moved in the console.
• Removing an account from the structure never closes or moves it. AWS Organizations does not allow programmatic account deletion, and the structure only manages membership. Once an account is closed, remove its entry.
• Budgets. AWS Budgets sends each new recipient address a verification email, and alerts start once it is confirmed; the status shows on the budget's page in the Budgets console. Changing a budget's recipients recreates the budget, and removing the budget from the structure deletes it. An OU budget covers the accounts the structure places under the OU; an account moved in outside the structure is not included. A root budget fails synthesis when the structure defines no account and no recipients are set.