The Great Migration: Upgrading CDK v1 to v2

At long last, CDK v2 is here and ready for import! Announced at Re:Invent 2021, CDK v2 boasts a single package import, stable APIs, and up-to-date API reference documentation.

If you have no idea what the heck CDK is or what I'm referring to, take a step back and read up on it. If you are just getting started with CDK, you can stop reading here; I'd highly recommend you jump right into v2, no need to bother with any of this v1 nonsense.

If you're like me and you've been living, breathing, and loving the CDK since its v1 days (or maybe you just have a few CDK v1 projects you casually maintain, no need to be a guru) then this post is for you! I've spent the last few weeks migrating my enterprise projects from v1 to v2, and today I want to share the process for updating - both python and typescript, we keep things inclusive here on my blog - the "gotcha's" I ran into, and highlight some of the new key features of v2 along the way.

A quick note here - in my expert opinion, the v1 to v2 migration is not highly complex. I do think the migration guide provided by AWS provides you with a great starting point, therefore I will not go into all the intricate details since it is included there for you. Instead, I am hoping to leave you with some anecdotal evidence in what I hope to be simple and straightforward language. Let's dive in!

Initial Setup
I'll preface this by saying python is my bread & butter, so it stands to reason that most of the projects I have been updating are in python. Sincerest apologies to my node friends.

If you're a Typescript developer, you need to make sure you are on 3.8 or later. For all languages, you will need to bootstrap your account with the new modern toolkit stack, which is backwards compatible, in order to take advantage of v2. This should be pretty easy to do, however do make sure to review the permissions and bucket encryption for the modern toolkit as they have changed to specified permissions and a customer-managed key.

Additionally, just make sure to run your npm or yarn install commands to install the new v2 dependencies. Reminder you can specify versions by explicitly stating @2.x.x.

Upgrading your Python & Typescript Projects
The biggest change you will notice from v1 to v2 is the package import. Instead of having to individually bring in each construct you want to use into your requirements.txt or package.json file, all STABLE constructs are now included in the aws-cdk-lib package.

# CDK v1 requirements.txt
aws-cdk.core
aws-cdk.aws_iam
aws-cdk.aws_s3

# CDK v2 requirements.txt
aws-cdk-lib==2.18.0

//CDK v1 package.json
"devDependencies": {
    "@aws-cdk/core": "^1.150.0",
    "@aws-cdk/aws-iam": "^1.150.0",
    "@aws-cdk/aws-s3": "^1.150.0"
 }

//CDK v2 package.json
"devDependencies": {
    "aws-cdk-lib": "^2.18.0"
 }

Along with this, your import statements will also change. You can see examples of what this looks like for python and typescript in the migration guide.

The next biggest change you may see is in your cdk.json, which is luckily the same in both languages. Most of the feature flags you may have been using in v1 have been removed, so for most folks the context in your cdk.json file can be removed. Your json file in v1 may have looked something like:

{
  "app": "python3 app.py",
  "context": {
    "@aws-cdk/core:enableStackNameDuplicates": "true",
    "aws-cdk:enableDiffNoFail": "true"
  }
}

Removing the feature flags for v2 we are left with:

{
  "app": "python3 app.py"
}

If you need backwards compatibility, you can still take advantage of one of the four remaining feature flags.

Gotcha's
Do not forget to check and update your tests! I fall victim to this every time; I update the code and the package files for v2, make sure the documentation is updated and then…forget to double check and run the tests. You will need to update the imports in the tests just as you did in the code. If you are taking advantage of the assertions library, @aws-cdk/assert, this is still required as a separate package, it is NOT part of the aws-cdk-lib package.

You are also welcome to continue using experimental constructs just as you might have in v1. As of this blog post release date, you will notice quite a few of these constructs in alpha, most notably for myself was the language-specific constructs like the python and go lambda function constructs. These can easily be identified in the AWS CDK v2 documentation with the legacy @aws-cdk package prefix followed by an -alpha tag at the end, and will need to be brought in as single packages as in v1; they are NOT included in the aws-cdk-lib package. Also note that there is a separate construct package for your Construct, Dependable, and Node classes, so if you need these makes sure you include the construct package.

What has tripped me (and several others, as I have come to learn) up is it is not always clear which v1 constructs are experimental, and which ones are stable. For instance, I was using the GlueDB resource in v1 and when I moved to v2, I realized the construct was experimental. There are some Glue resources that are stable and some that are experimental in v2, so I had to find and bring in the appropriate glue alpha package separately to utilize GlueDB. Unfortunately, I do not have the time to compare side-by-side every single CDK construct that has or has not changed, so I would recommend that you reference the AWS CDK documentation and the CDK Construct Hub for your specific use cases if you have any concerns.

All in all, my experience upgrading from CDK v1 to v2 was a fairly smooth one, and I'm hoping it was the same for you! If you've been migrating your projects, let me know if this helped, or if you ran into anything else I didn’t cover. If you jumped on this shortly after I posted it, I'd also love to hear your story at CDK Day 2022 on May 26th. CFPs are open until April 20th, please reach out to me if you're interested in presenting or need help with a topic idea. Happy migrating!