This article provides some guidance and tips for migrating your existing infrastructure setup from the AWS CDK v1 to v2.
We’ve recently performed this migration for the entire AWS CDK Java infrastructure for Stratospheric.
Adjusting the Java Infrastructure Setup
Every stable AWS CDK construct is now part of a single library. This simplifies the import for our Maven project as we don’t have to add a dependency for each AWS service, as was the case with the AWS CDK v1.
We now depend on a single artifact and hence can remove all previous dependency declarations:
<dependency> <groupId>software.amazon.awscdk</groupId> <artifactId>aws-cdk-lib</artifactId> <version>2.8.0</version> </dependency>
L1 constructs (the counterparts for CloudFormation’s
CfnXXXX entities) are now considered stable for all AWS services. If we want to use experimental L2 and L3 constructs, we need to import them specifically as
aws-cdk-lib only contains stable constructs.
Construct class that we use when defining our own L2 or L3 construct has moved to a dedicated package:
<dependency> <groupId>software.constructs</groupId> <artifactId>constructs</artifactId> <version>10.0.43</version> </dependency>
After replacing the old AWS CDK v1 dependency imports, we have to adjust the import statements for the Construct class and some other CDK-specific classes. We might have to adjust the infrastructure setup on rare occasions as some methods might no longer be available. For the Stratospheric setup, this happened in two places:
- the subnet type
- when passing dimensions for a CloudWatch metric, the dimensions method was replaced with dimensionsMap
From version 0.1.0 onwards, our cdk-constructs library only supports the AWS CDK v2.
Once the Maven project compiles, we can move to the next step and prepare the migration.
Preparing the Migration
To deploy our CDK constructs, we now need a 2.x version of the CDK Toolkit (which we install with NPM). The CDK v2 toolkit is backwards-compatible with CDK v1. However, the AWS CDK team suggests not installing v2 globally if you have projects using both v1 and v2. A better approach is to use npx (a package runner, which has been part of NPM since version 5.2) and create an alias:
alias cdk1="npx firstname.lastname@example.org" alias cdk="npx email@example.com"
Next, remove all feature flags in the
cdk.json file that are part of the context attribute and start with
@aws-cdk/ . There’s only a small subset of CDK v1 feature flags that can be used with CDK v2. You’ll find those flags as part of the AWS migration guide.
Performing the Migration
Before we can deploy our CDK v2 constructs, we have to re-bootstrap our account. Therefore, we run cdk bootstrap using the CDK v2 toolkit. This will override the CDK v1 bootstrapping and add some more AWS resources to our AWS account that the CDK needs internally.
Now it’s time to re-deploy our stacks. We can use the cdk diff command to ensure nothing changes except internal CDK metadata and updated hashes. Changes to the logical IDs of our resources would result in a replacement of these resources but are not expected. Carefully read the result of the diff before re-deploying the stacks.
Congrats, you’re now using the AWS CDK v2!
PS: If you’re stuck migrating to the AWS CDK v2, don’t hesitate to ask a question in our Stratospheric Slack community.
Tom, Philip, Björn