How to deploy a simple multi-account architecture with AWS CDK v2

For large applications, AWS recommends a multi-account structure to create a clear separation of roles and resources. In this post, I will be talking about AWS CDK v2 and demonstrating how to deploy a simple multi-account architecture with AWS CDK v2.

Setting the scene

A common multi-account strategy is to have one account for each environment that hosts your application e.g. development, test, production etc and another account used to control application deployments into those environments.

With AWS CDK, deploying these complex architectures is made simpler and more manageable. With the latest version CDK v2, cross-account deployments can be done completely transparently, without having to switch between accounts and manually trigger pipelines.

Bootstrapping

To deploy CDK applications into an AWS account, the account first needs to be bootstrapped with the resources that the CDK needs to perform the deployment. The CDK CLI provides a command that automatically provisions these resources: cdk bootstrap. Running this command will create a CloudFormation stack that defines the required resources. By default, this stack is named CDKToolkit. It includes an S3 bucket for storing CloudFormation templates and other files, and IAM roles that have the permissions needed to deploy AWS resources.

cdk bootstrap aws://999999999999/ap-southeast-2

So, what happens if you share an account with other teams?

You can use the same bootstrap resources to deploy your applications alongside each other. However, version mismatching and workflow differences may mean that a different approach is required. To solve this problem, the CDK CLI allows you to set a “qualifier”, which is just a string added to the names of all the resources in the bootstrap stack. It lets you avoid resource name clashes with other teams, giving you your own bootstrap resources that stand independently. You’ll also want to change the stack name from CDKToolkit to something unique.

Trust is key

So now we can bootstrap one account, but how can we manage multiple? It’s not as simple as following the same process as our other accounts, because in our account structure, we want to perform application deployments from a centralised build account. To allow this, we need our other accounts to trust the build account.

cdk bootstrap aws://111111111111/ap-southeast-2 --trust 999999999999 --cloudformation-execution-policies "arn:aws:iam::aws:policy/AdministratorAccess"

Adding the --trust flag will configure a trust relationship on the bootstrapped IAM role used for CDK deployments. This trust relationship will allow principals in the build account (999999999999) to assume the role and execute API calls to CloudFormation.

The second flag (--cloudformation-execution-policies) specifies the permissions granted to the role. In this case, the role is given full administrator access, which is necessary to create, update, and delete all types of AWS resources. Therefore, it is important to put appropriate restrictions on the repository that stores your CDK application, so only trusted code and dependencies are deployed.

My accounts are bootstrapped, now what?

Now we can deploy our CDK application! In this example, we’re using CDK Pipelines, which is a high-level construct module included in the AWS CDK that simplifies the continuous delivery of CDK applications. I’ve followed this how-to guide created by AWS to produce an application that deploys a simple Lambda function, and I’ve extended it to deploy to three environments, each in a separate AWS account. You can view my solution on GitHub.

In the CdkPipelineStack, I’ve defined several stages to deploy our CDK application to other accounts. Each stage contains a pre-deployment step to require manual approval before continuing. Here’s what that looks like in the AWS Console:

After giving manual approval, the pipeline will deploy our Lambda stack into another account by assuming the cross-account roles we created during the bootstrapping step. The entire process is completely transparent and automated, giving you fully centralised control of your application deployments, and an account structure with strong boundaries between environments.

Summary

AWS CDK v2 means you can deploy complex architectures in a way which is manageable and straightforward. Cross-account deployments can be done completely transparently, without having to switch between accounts and manually trigger pipelines. The process I suggest following involves bootstrapping, setting a qualifier, changing the stack name from CDKToolkit and then setting two trust flags. Once done, you’re ready to deploy your CDK application!