Migrate from AWS CDK v1 to v2

Support for AWS CDK v1 will officially end on June 1, 2023 so if you haven’t already it’s a good idea to migrate to v2. As far as migrations go, this was fairly painless and straightforward.

The main changes involve updating dependencies and imports and removing feature flags that are now active by default.

Step 1: Install v2 of the CDK Toolkit

Install the latest version of the CDK Toolkit. For this example I will use version aws-cdk@2.53.0. You can install it globally since it is compatible with CDK v1 apps as well.

Step 2: Update dependencies in your package.json

Remove all v1 packages for individual AWS services and replace them with the aws-cdk-lib.

Depending on your app, you may need to install experimental modules like aws-amplify-alpha that are not included in the aws-cdk-lib and need a specific import. Once the module is stable for v2 it will be moved into aws-cdk-lib.

{
  "dependencies": {
    "aws-cdk-lib": "2.53.0",
    "@aws-cdk/aws-amplify-alpha": "2.53.0-alpha.0",
    "constructs": "10.1.179"
  }
}

Constructs have been moved into a separate library and must be added as a individual dependency in peerDependencies and devDependencies along with the aws-cdk-lib.

{
  "peerDependencies": {
    "aws-cdk-lib": "2.53.0",
    "constructs": "10.1.179"
  },
  "devDependencies": {
    "aws-cdk-lib": "2.53.0",
    "constructs": "10.1.179"
  }
}

Step 3: Update imports

import * as cdk from 'aws-cdk-lib'
import { Construct } from 'constructs'
import * as amplify from '@aws-cdk/aws-amplify-alpha'

Step 4: Update Feature Flags

Remove any of the following v1 feature flags from your cdk.json

• @aws-cdk/core:enableStackNameDuplicates
• aws-cdk:enableDiffNoFail
• @aws-cdk/aws-ecr-assets:dockerIgnoreSupport
• @aws-cdk/aws-secretsmanager:parseOwnedSecretName
• @aws-cdk/aws-kms:defaultKeyPolicies
• @aws-cdk/aws-s3:grantWriteWithoutAcl
• @aws-cdk/aws-efs:defaultEncryptionAtRest

Step 5: Bootstrap

Deploy the CDK staging stack

cdk bootstrap

Step 6: Test and Deploy

Run cdk diff to compare your stack with the deployed stack. If everything looks okay run

cdk deploy

Success! You have officially migrated to AWS CDK v2! Go update all of your lambda functions to use Node.js 18.