Use AWS CDK v2 with the AWS Amplify CLI extensibility features (Preview)

With v11.0.0-beta of the Amplify CLI, you can now use AWS CDK v2 to extend or modify your Amplify backend stack. As a recap, at re:Invent 2021, Amplify CLI (v7+) announced a number of extensibility features that gave developers the flexibility to modify their Amplify backend using infrastructure-as-code providers such as AWS CDK or AWS CloudFormation. This gives you the benefits of both worlds – the speed and magic that Amplify provides with the CLI and Studio console, and the programmatic constructs made available using TypeScript in CDK.

A summary of the capabilities are:

Overrides: The ability to override Amplify-generated infrastructure with additional settings. Most commonly used to tweak a configuration setting for a specific service that is not exposed in the Amplify CLI interactive flows.
Custom: The ability to add any of the 175+ AWS services to an Amplify-created backend stack. Most commonly used for services that are not available in the Amplify CLI.
Export: The ability to export an Amplify backend as a CDK stack. Most commonly used when you want to use Amplify CLI’s GraphQL transformer or codegen capabilities, but use another deployment mechanism.

Get started

If you want to use Amplify CLI’s extensibility features, this tutorial is a great starting point. Alternatively you can fork this repo and deploy it on Amplify Hosting.

Upgrade Amplify project to AWS CDK v2

Please proceed to upgrade in a non-production environment

The major benefit of AWS CDK v2 is that it consolidates the AWS Construct Library into a single package called aws-cdk-lib, and eliminates the need to download individual packages for each AWS service used. Upgrading to AWS CDK v2, for most Amplify projects, can be accomplished with a one-time, safe re-bootstrapping of your AWS accounts and “import“ statement changes.

First, install the beta release of the Amplify CLI v11.

npm i @aws-amplify/cli@beta

Now let’s upgrade our project to use CDK v2. First let’s check the status of our project in the command line. Assuming you followed along the tutorial above, you should see the following resources after running amplify status:

nsswamin@c889f3b5b3b1 amplifycdkv2-demo % amplify status

    Current Environment: dev
    
┌──────────┬──────────────────────────┬───────────┬───────────────────┐
│ Category │ Resource name            │ Operation │ Provider plugin   │
├──────────┼──────────────────────────┼───────────┼───────────────────┤
│ Api      │ amplifycdkv2demo         │ No Change │ awscloudformation │
├──────────┼──────────────────────────┼───────────┼───────────────────┤
│ Auth     │ amplifycdkv2demo3397c632 │ No Change │ awscloudformation │
├──────────┼──────────────────────────┼───────────┼───────────────────┤
│ Function │ amplifycdkv2demo3397c632 │ No Change │ awscloudformation │
├──────────┼──────────────────────────┼───────────┼───────────────────┤
│ Custom   │ customResource93fda0b6   │ No Change │ awscloudformation │
└──────────┴──────────────────────────┴───────────┴───────────────────┘

GraphQL transformer version: 2

Upgrade overrides to CDK v2

Overrides are applied on resources that are created by the Amplify CLI. Currently, we support overrides for GraphQL API, Auth, and Storage. To migrate overrides to use CDK v2, open <your-app>/amplify/backend/package.json and upgrade the `cli-extensibility-helper` to beta:

 },
  "dependencies": {
    "@aws-amplify/cli-extensibility-helper": "beta"
  },

Once this is complete, run amplify push to complete the upgrade.

Upgrade custom stacks to CDK v2

Custom stacks allow you to use CDK to include any of the 175+ AWS services as part of your Amplify backend stack. The tutorial above, uses a custom stack that contains the SNS resource. To upgrade your custom stack, open your terminal and run the following command:

cd <your-app>/amplify/backend/custom/<custom-resource-name>

First, delete your node_modules folder and package-lock.json file, and make the following edits to your package.json file:

AWS CDK v2 consolidates the AWS Construct Library into a single package called aws-cdk-lib, and eliminates the need to download individual packages for each AWS service used. Make sure to remove all references to @aws-cdk/*** from your package.json.

  "dependencies": {
    "@aws-amplify/cli-extensibility-helper": "beta",
    "aws-cdk-lib":"~2.46.0", 
    "constructs": "^10.0.5"
  },

Open the amplify/backend/custom/cdk-stack.ts file:

Update all import statements to reference aws-cdk-lib instead of @aws-cdk
Remove usage of any deprecated APIs listed here.

Once this is complete, run amplify push to complete the upgrade.

Upgrade exported stacks to CDK v2

Exported Amplify backends allow you to integrate Amplify backends into your CDK app. To upgrade, open your CDK project and update your package.json to v0.0.6 of cdk-exported-backend and remove references of @aws/cdk/*.

"dependencies": {
    "@aws-amplify/cdk-exported-backend": "^0.0.6",
    "aws-cdk-lib": "~2.46.0",
    "constructs": "^10.0.0"
  }

Again, make sure you make the following changes in your lib/<cdk-filename>.ts file:

Update all import statements to reference aws-cdk-lib instead of @aws-cdk
Remove usage of any deprecated APIs listed here.

Full-stack CI/CD

If you are using Amplify’s full-stack CI/CD capabilities make sure you do the following:

Update Amplify Hosting’s live package updates to reference beta
Commit the changes you make to your overrides and custom stacks to a Git branch (preferably dev).

Support

We plan on making this feature generally available very soon, but in the meantime if there are feature requests or issues you face in the upgrade process, please cut a ticket here.

Front-End Web & Mobile