Skip to main content

Adding a New Business Unit

Use this checklist to onboard a new business unit (BU).

NOTE
Step 3 can be in 1 PR
Steps 2 - 7 can be in 1 PR
Steps 10 and 11 can be in 1 PR

Step 1: Request Accounts Created in Modernisation Platform

Request member accounts for both environments:

  • container-platform-bu-nonlive
  • container-platform-bu-live

Guide: Modernisation Platform new account guide

MP Account Request Example modernisation-platform #13641

Step 2: RAM Share MP TGW and Route53 Profile to New Accounts

Once MP have confirmed the AWS accounts have been created in Step 1, share the MP TGW and the VPC Endpoints Route53 Profile to the new accounts.

Code example:
RAM Share for MP TGW: ram.tf
RAM Share for VPC Endpoints Route53 Profile: vpc-endpoints.tf.tf

Raise the PR with the Modernisation Platform team and merge it before moving to the next step. You can raise the changes in a single PR.

PR example for MP TGW RAM Share: modernisation-platform#13655
PR example for MP VPC Endpoints Route53 RAM Share: modernisation-platform#13516

Step 3: Add to CP accounts.json

Add both new accounts to terraform/environments/cloud-platform/accounts.json in the modernisation-platform-environments repository.

Step 4: Create the Terraform Workspace

The workspace is created automatically in the container-platform-bu application folder. Because Terraform is run from the cloud-platform application folder, create the workspace there as well.

Use generate-account-workspaces.sh so all accounts in accounts.json get corresponding workspaces.

Use AWS credentials for the platform-engineer-admin role in the cloud-platform-development account (any role with state access to cloud-platform is sufficient).

TIP
Use the flag --dry-run on the script to show what changes would be done to the Terraform workspaces. The script scans the cloud-platform root and all subdirectories for *.tf files and assumes a workspace needs to exist against that directory.

Step 5: Add Root Subdomain

In the cloud-platform root folder, add the BU subdomain in environment-configuration.tf.

Step 6: Add BU to Skip Plan Evaluator

Add the new accounts to .github/config/skip-plan-evaluator-workspaces.json in the modernisation-platform-environments repository.

Step 7: Add the VPC CIDR

Please refer to the Cloud Platform CIDR Allocation page to find the pre-assinged or a unassigned CIDR range for the business unit. If picking a unassigned range, please remember to update the page.

Add the allocated VPC CIDR to the vpc_cidr block in network/locals.tf.

Step 8: Merge the Modernisation Environments Repository PR

Merge the PR and deploy to the new cluster environments.

Expected behavior at this stage:

  • cluster plan fails until the VPC is built
  • cluster-core apply fails with a Route53 hosted zone error

PR example: modernisation-platform-environments#17400 (requires MP approval)

At this point, the TGW attachements will have been built in the new accounts. Take a note of TGW attachment IDs as this will be needed in the next step.

Step 9: Add New TGW Attachments to TGW Route Tables in MP

Code example: container_platform_tgw_connections.tf

PR example: modernisation-platform#13440

Get approval and merge.

Step 10: Add Route 53 Records for the New BU Subdomain

Code example: route53.tf

Get the hosted zone NS records from each new BU account and add them to route53.tf.

Step 11: Add the New BU to External DNS

Code example: cluster-core/external-dns.tf

Step 12: Apply Workflows to Build Out Clusters

PR example: modernisation-platform-environments#17412

Approve and merge the PR, then apply the cloud-platform and container-platform workflows.

Step 13: Add the New BU Accounts to Identity

Add the new container-platform-<bu>-nonlive and container-platform-<bu>-live account names to the identity Terraform configuration in the container-platform-environments repository.

This change should include:

  • adding new providers for the BU accounts
  • creating a namespace_team_access_assignments local for the BU
  • adding the BU to named clusters
  • adding access entries for the BU accounts

PR example: container-platform-environments#10

This page was last reviewed on 3 August 2026. It needs to be reviewed again on 3 February 2027 by the page owner #cloud-platform-notify .