Landing Zone Settings

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

Example

The starter ships the file with the optional settings commented out. Uncomment the ones you need:

export const landingZoneSettings: LandingZoneSettings = {
  organizationName: 'example-corp',
  mailDomain: 'example.com',
  managementAccountId: '111111111111',
  landingZoneAccountId: '222222222222',
  primaryRegion: 'eu-west-1',
  secondaryRegions: [],
  // externalAdmins: [
  //   {
  //     accountId: '111122223333',
  //     managedPolicyName: 'ReadOnlyAccess',
  //   },
  // ],
  // organizationAccountLimit: 120,
};

The audit log settings take CDK values. With them set, the object gains two lines such as auditLogRemovalPolicy: cdk.RemovalPolicy.RETAIN and auditLogRetention: cdk.Duration.days(730).

How it's used

These settings flow into every part of the landing zone:

• organizationName and mailDomain prefix the generated account email addresses and name the landing zone asset buckets; the OU and account display names in organization-structure.ts are plain strings
• 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 the multi-Region StackSets, such as Account Security, target. The landing zone also keeps one asset bucket per active Region, so adding or removing a secondary Region adds or removes that bucket in the same landingzone deployment
• 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
• auditLogRemovalPolicy and auditLogRetention apply to the organization trail that the Observability StackSet runs in the observability account, and to its log and access-log buckets and encryption key

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: it names the asset buckets, and changing it creates new ones
• 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
• Audit logs under RETAIN (the default). Removing the landing zone keeps the organization trail's log bucket, access-log bucket, and encryption key, so existing log files stay readable and the trail keeps delivering into the retained buckets. The CloudWatch Logs delivery and the CIS alarms are removed. Removing the organization stack also disables CloudTrail trusted access, which turns the organization trail into a management-account trail: member accounts are no longer logged until a reinstall restores it. Nothing deletes the retained buckets or key. A reinstall creates new buckets and a new key next to them, and the retained log files stay readable with the retained key.
• Audit logs under DESTROY. Removal empties and deletes the buckets and deletes the trail and its key. Use it only for an organization whose audit logs are disposable, such as a test organization. Empty a large bucket yourself first.
• Shorter retention deletes logs. auditLogRetention expires both the audit log files and the S3 server access logs after that many days, so lower it only when you keep copies elsewhere.
• Secondary Regions. Removing a Region from secondaryRegions removes the landing zone's StackSet instances there in the next landingzone deployment. The Region's asset bucket, and its entry in the region-guardrail SCP, stay until no landing-zone StackSet uses the Region anymore, so a deployment that fails during the removal can roll back. A later deployment then removes both.

Workload account quota requests belong in service-quotas.ts. Use organizationAccountLimit here only for the management account's Organizations account quota.