AWS CDK Landing Zone

Landing Zone Settings

Configure the core settings for your AWS CDK Landing Zone deployment, including organization name, mail domain, management account ID, and regions.

src/config/landing-zone-settings.ts contains the core deployment boundary for your landing zone. These values are read by every stack and StackSet to wire names, targets, and regions correctly.

Two account IDs anchor the deployment. The management account is your AWS Organizations root, where the organization phase runs. The landing zone account is a dedicated member account that deploys the StackSet stacks as the CloudFormation StackSets delegated administrator, so day-to-day provisioning does not run from the management account. See Stacks for how the two phases relate.

After changing this file, re-run pnpm exec projen to regenerate the npm scripts and GitHub Actions workflow with the updated values.

Options

OptionTypeRequiredDescription
organizationNamestringYesShort organization slug used for resource names and tags. Use lowercase and dashes.
mailDomainstringYesEmail domain used to generate root email addresses for new AWS accounts (e.g. aws+log@your-org.com).
managementAccountIdstringYes12-digit AWS Organizations management account ID. The organization phase deploys here.
landingZoneAccountIdstringNo*12-digit ID of the dedicated member account that deploys the landing-zone StackSets as the CloudFormation StackSets delegated administrator. Leave it unset only for the very first organization-phase deploy; set it before you deploy the landing-zone phase. *Required to deploy the landingzone phase.
primaryRegionstringYesPrimary AWS Region where the CDK app and landing-zone resources deploy.
secondaryRegionsstring[]YesAdditional active Regions that receive multi-region StackSet deployments. Pass [] if you only use one region.
externalAdminsLandingZoneExternalAdmin[]NoEnables an ExternalAccessStackSet that grants one or more third-party accounts admin access across organization accounts. Each entry takes accountId (string, required), managedPolicyName (string, optional, default ReadOnlyAccess), and roleName (string, optional, default ExternalLandingZoneAdmin-<accountId>).
organizationAccountLimitnumberNoDesired AWS Organizations maximum-accounts quota. When set, the Provision Management StackSet requests it against the management account. The request is idempotent and approval is asynchronous.

Example

export const landingZoneSettings: LandingZoneSettings = {
  organizationName: 'acme',
  mailDomain: 'acme.com',
  managementAccountId: '123456789012',
  landingZoneAccountId: '234567890123',
  primaryRegion: 'eu-west-1',
  secondaryRegions: ['us-east-1'],
  externalAdmins: [
    {
      accountId: '111122223333',
      managedPolicyName: 'ReadOnlyAccess',
    },
  ],
  organizationAccountLimit: 120,
};

How it's used

These settings flow into every part of the landing zone:

  • organizationName and mailDomain prefix the generated OU and account names defined in organization-structure.ts
  • managementAccountId, landingZoneAccountId, and primaryRegion are embedded in the generated organization:* and landingzone:* npm scripts and the two-account GitHub Actions deployment workflow by pnpm exec projen
  • primaryRegion and secondaryRegions determine which regions the region-guardrail SCP allows (see Service Control Policies) and which regions multi-region StackSets such as Account Security and Central Alerts target
  • externalAdmins deploys an ExternalAccessStackSet across the organization when set
  • organizationAccountLimit is passed into the ProvisionManagementStackSet, which requests the quota against the management account when set

Things to know

  • Re-run pnpm exec projen after every change to this file, as the generated workflow and npm scripts embed managementAccountId, landingZoneAccountId, and primaryRegion directly
  • landingZoneAccountId has a bootstrapping quirk: leave it unset for the first organization-only deploy, then set it to the ID of the LandingZoneAccount that the organization phase creates and re-run pnpm exec projen before deploying the landing-zone phase. Install walks through this ordering
  • organizationName should be stable: changing it renames all OU and account resources, which CloudFormation handles as a delete-and-recreate
  • Email addresses for accounts must be globally unique across all of AWS; the mailDomain approach using aws+<alias>@your-domain.com keeps them namespaced under your domain
← ConfigurationOrganization Structure →