Managing Logical Environments in AWS CDK: Using Qualifiers to Avoid Conflicts

Infrastructure as Code or IaC is an essential tool in modern DevOps. If you're working with AWS as your primary cloud provider, you're very likely working with one of the two tools AWS offers for IaC: CloudFormation or CDK.

While CDK provides some extra capabilities compared to CloudFormation, it requires some infrastructure to already exist in order to perform certain functionality. This infrastructure was optional in CDK v1 but is mandatory in CDK 2 to provision any stacks. The process of creating these infrastructure components is called bootstrapping.

Assuming that you have CDK tooling already set up on your machine, it's relatively easy to perform the bootstrapping process:

cdk bootstrap aws://{account-id}/{region}
cdk bootstrap aws://123456789012/ap-southeast-2

By default, this will create a stack with the name CDKToolkit:

 

 

 This stack include some resource like an ECR repository and S3 bucket:

 

 

 

As shown in the screenshots, the resources include a default qualifier "hnb659fds", which aside of being a random ugly string, this default is challenging when we have multiple logical environments like dev and test in the same AWS account because we'll have to use the same resources to serve these logical environments.

If it's required to separate these environments and have two different sets of CDK resources, we need to distinguish between these environments by specifying a qualifier. At the same time, we need to ensure that stack names don't conflict.

To achieve this, CDK CLI provides two parameters:

1. --qualifier: replaces the default "hnb659fds" string in resource names.
2. --toolkit-stack-name: overrides the default stack name.

For example, to bootstrap two separate logical environments, we can use:

cdk bootstrap aws://123456789012/ap-southeast-2 --qualifier dev --toolkit-stack-name CDKToolkit-dev
cdk bootstrap aws://123456789012/ap-southeast-2 --qualifier test --toolkit-stack-name CDKToolkit-test

This results in creating stacks and resources as shown:

The next question is: How to target a specific bootstrap qualifier when you deploy?
One way is to update cdk.json configuration file to set the bootstrap identifier:

cdk.json
"context": {
    "@aws-cdk/core:bootstrapQualifier": "test"
  }

If you prefer to set this value dynamically, for example to pass the environment name in a CI pipeline as an environment variable, you can use code instead: (This example uses C#)

var qualifier = Environment.GetEnvironmentVariable("CDK_QUALIFIER");
var synthesizer = new DefaultStackSynthesizer(new DefaultStackSynthesizerProps() { Qualifier = qualifier });
var stack = new Stack(app, "my-stack", new StackProps() { Synthesizer = synthesizer });

This method allows you to set up multiple environments within a single AWS account, enabling the application of distinct policies to CDK assets for logical divisions like dev and test or for separate teams sharing the account.