Migrating from AWS CDK v1 to CDK v2

Sami Jaballah — Sun, 16 Feb 2025 09:40:02 +0000

If you’re currently using CDK v1 in your daily work, you’ve probably hit a roadblock trying to implement new AWS features. AWS isn’t adding those to CDK v1 anymore—so to keep up with the latest and greatest, you’ll need to migrate to CDK v2. It might sound like a hassle, but don’t worry—I’ve got your back. Let’s go through this step-by-step and get you up to speed, Python style.

Why Should You Care About CDK v2?

Alright, let’s address the big question: why even bother migrating to CDK v2? Well, here are three solid reasons:

Simplified Dependencies: No more pulling in tons of packages for different AWS services. CDK v2 bundles everything into a single package: aws-cdk-lib. How awesome is that?

Stay Updated: CDK v1 isn’t getting any love anymore. If you want to keep up with the latest AWS features and updates, v2 is where it’s at.

Better Developer Experience: AWS has introduced some stability guarantees and cleaned up APIs, making it easier for us to write and maintain our infrastructure code.

What’s New in CDK v2?

1. Consolidated Package Structure
Remember the days of importing a separate package for each AWS service? That’s history now. CDK v2 unifies everything into aws-cdk-lib.

Example:

CDK v1:

from aws_cdk import core
from aws_cdk.aws_s3 import Bucket

CDK v2:

from aws_cdk import Stack
from aws_cdk.aws_s3 import Bucket

2. Goodbye to Deprecated APIs

Some APIs and constructs from v1 didn’t make the cut in v2. For instance, core.Construct has been replaced by constructs.Construct. A little cleanup never hurts, right?

3. Shiny New Features

There are some great new features, like improved stability guarantees for low-level (L1) constructs and better testing capabilities with assertions.

Let’s Get Migrating: Step-by-Step Guide

Ready to dive in? Follow these steps to upgrade your Python CDK project to v2.

1. Update Your Dependencies

Start by upgrading your project dependencies to use CDK v2. Open your requirements.txt or Pipfile and update them:

aws-cdk-lib>=2.0.0
constructs>=10.0.0

Then, install the new dependencies:

pip install -r requirements.txt

2. Fix Your Imports

This is where the magic happens. Go through your code and replace aws_cdk.core with aws_cdk.Stack, and adjust other imports to use aws-cdk-lib.

Example:

Before (CDK v1):

from aws_cdk import core
from aws_cdk.aws_s3 import Bucket

After (CDK v2):

from aws_cdk import Stack
from aws_cdk.aws_s3 import Bucket

3. Refactor Deprecated Constructs

Some constructs have been replaced or removed. For example, core.Construct is now constructs.Construct. Update your code accordingly.

Example:

Before:

class MyBucket(core.Construct):
    def __init__(self, scope: core.Construct, id: str):
        super().__init__(scope, id)
        Bucket(self, "MyBucket")

After:

from constructs import Construct

class MyBucket(Construct):
    def __init__(self, scope: Construct, id: str):
        super().__init__(scope, id)
        Bucket(self, "MyBucket")

4. Remove Unnecessary Feature Flags

CDK v2 has removed or integrated several feature flags that were necessary in v1. To clean up your cdk.json file, remove any obsolete flags.

Example:

Before:

{
  "app": "python3 app.py",
  "context": {
    "@aws-cdk/core:newStyleStackSynthesis": true,
    "@aws-cdk/aws-ec2:uniqueImds": true,
    "@aws-cdk/core:stackRelativeExports": true,
    "@aws-cdk/aws-secretsmanager:parseOwnedSecretName": true,
    "@aws-cdk/aws-kms:defaultKeyPolicies": true,
    "@aws-cdk/core:enableStackNameDuplicates": true,
    "aws-cdk:enableDiffNoFail": true,
    "@aws-cdk/aws-ecr-assets:dockerIgnoreSupport": true,
    "@aws-cdk/aws-s3:grantWriteWithoutAcl": true,
    "@aws-cdk/aws-efs:defaultEncryptionAtRest": true
  }
}

After:

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

Removing these flags ensures your project stays aligned with CDK v2 best practices.

Test Your Migration

Finally, make sure everything works as expected. Run these commands:

cdk synth
cdk diff

Fix any issues that pop up, and you’re good to go!

Migration Verification Checklist

All imports updated to aws-cdk-lib
Construct imports moved to constructs package
Feature flags removed
Property names verified
Tests passing
cdk diff shows expected changes

Wrapping It Up

And there you have it! Migrating from CDK v1 to v2 isn’t as scary as it might seem. With unified dependencies, better APIs, and future-proofing, this upgrade is worth the effort. Take it one step at a time, and don’t hesitate to ask for help if you hit a roadblock.

Have you already migrated to CDK v2? Or are you planning to? Share your experience (or any questions) in the comments below!

Useful links to help you along the way:

AWS CDK v2 Migration Guide
AWS CDK Python Reference

DEV Community: Sami Jaballah