Export Amplify backends to CDK and use with existing deployment pipelines

Today, AWS Amplify announces the ability to export Amplify CLI-generated backends as a Cloud Development Kit (CDK) stack and incorporate into existing CDK deployment pipelines. This new capability allows frontend developers to build their app backend quickly and, each time it is ready to ship, hand it over to DevOps teams to deploy to production.

Note: This is an advanced topic, it is recommended to first complete Amplify’s getting started guide and AWS CDK’s getting started guide. This guide specifically focuses on using an existing CDK-based deployment pipeline. Also check out how to override Amplify-generated resources using CDK or how to extend Amplify backend with custom AWS resources using AWS CDK or CloudFormation.

AWS Amplify is the fastest and easiest way to build cloud-powered mobile and web apps on AWS. Amplify comprises a set of tools and services that enables frontend web and mobile developers to leverage the power of AWS services to build innovative and feature-rich applications. The AWS Amplify CLI is a command line toolchain that helps frontend developers create app backends in the cloud. The AWS Cloud Development Kit (AWS CDK) is an open-source software development framework to define cloud infrastructure in familiar programming languages. CDK Pipelines is a high-level construct library that makes it easy to set up a continuous deployment pipeline for your CDK applications, powered by AWS CodePipeline.

Many developers need the ability to use Amplify with existing DevOps guidelines and tools. For example, some organizations require apps to be deployed to production with an existing deployment systems that enforces organizational DevOps and security guidelines. Now, frontend developers can use the Amplify CLI to iterate on their app backend quickly and, prior to each production deployment, run “amplify export” to provide an exported Amplify backend for an existing deployment system. A new “Amplify Exported Backend” CDK construct is now also available that allows DevOps engineers to incorporate Amplify backends as a deployment stage with only a few lines of code.

What we’ll learn

• How to build an app backend in minutes using Amplify and export it to CDK
• How to use an exported Amplify backend in an existing CDK stack or pipeline

Pre-requisites:

• Install the latest Amplify CLI; version 7 and above required.
  • Open terminal and run npm i -g @aws-amplify/cli
• Amplify CLI is already configured
  • If you haven’t configured the Amplify CLI yet, follow this guide on our documentation page

1. Initialize your Amplify backend

First, run create a new directory and initialize your Amplify project:

mkdir mytodoapp
cd mytodoapp
amplify init -y

An Amplify project is your starting point for developing your app backend. After an Amplify project is initialized, you can easily add backend resources such as a GraphQL API backed by Amazon DynamoDB via amplify add api.

2. Add a GraphQL API backend for a Todo app

Next, we need to store our todo list data somewhere. Amplify CLI provides the “API category” to help you create a GraphQL API and its underlying resources. Run amplify add api to create your GraphQL API:

amplify add api

(For the purposes of this demo, you can accept all the defaults.)
As you go through the CLI, you’ll be asked to edit your GraphQL schema. The GraphQL schema is going to define your data model and therefore also the underlying infrastructure that Amplify will generate for you.

You should see a GraphQL schema like this:

type Todo @model {
  id: ID!
  name: String!
  description: String
}

Now, we’re pretty much set! Usually, when we’d be running “amplify push” at this point to create our cloud resources and deploy.

In this particular demo though, we want to showcase the ability to “export” the amplify project and deploy it through your own CDK-based CI/CD pipeline.

3. Set up CDK-based CI/CD pipeline

For this demo, I’ve prepared a CDK-based pipeline for you to use. If you’re looking to rebuild this from scratch, I highly recommend reading CDK Pipelines: Continuous delivery for AWS CDK applications. This part is typically managed by your DevOps engineers or already exists in a similar fashion if your organization has a centralized deployment system.

Let’s change directory to a parent directory, where we’ll setup a new folder for our CDK pipeline.

cd ..

Fork the GitHub repo and the clone it to your local environment.

Fork renebrandel/mycdkpipeline ⎘

git clone git@github.com:<YOUR_GITHUB_USERNAME>/mycdkpipeline.git
cd mycdkpipeline

Now, let’s update all the necessary node dependencies to ensure your project is set up correctly.

npm install

4. Walk through of the CDK Pipeline code

Let’s take a look at the CDK pipelines project. This entire file structure is here to help you initialize your pipeline and then subsequent commits via Git will automatically trigger new deployment with the latest changes to the stacks and deployment stages.

Main entry point of your CDK app. Initializes your CDK pipeline. Some other stack in your pipeline. This is where your “other” backend resources, outside of your Amplify project could live. A pipeline contains multiple “stages”. CDK Pipelines usually includes “Source”, “Build”, “UpdatePipeline”, “PublishAssets” stages. You can define your own stages here. The actual stack that defines the pipeline and which stages are assigned to it.

There are two important files that we should mainly focus on a) my-pipeline-stack.ts which defines your pipeline including pipeline stages and b) the amplify-stage.ts which is a deployment stage that will contain your Amplify stack.

(This is just an example pipeline. Because an exported Amplify backend is just like any other CDK construct, you can use it like any other CDK construct.)

5. Configure the CDK pipeline

In my-pipeline-stack.ts, you’re creating a new pipeline and adding two stages to it. Make sure to update the code snippet on line 20 to use your GitHub username. This needs to be the same as your forked repo:

input: CodePipelineSource.gitHub('<YOUR_GITHUB_USERNAME>/mycdkpipeline', 'main'),

To have AWS CodePipeline read from this GitHub repo, you also need to have a GitHub personal access token stored as a plaintext secret (not a JSON secret) in AWS Secrets Manager under the name github-token. For instructions, see Tutorial: Creating and Retrieving a Secret. The token should have the scopes repo and admin:repo_hook.

6. Export your Amplify backend into CDK project

Let’s cd back to our Amplify project:

cd ../mytodoapp

Then, export the Amplify project to CDK:

amplify export --out ../mycdkpipeline/lib

Now you should see a set of files Amplify-related files exported to mycdkpipeline/lib/amplify-export-mytodoapp. These files include CloudFormation templates of Amplify-generated resources, Assets such as GraphQL resolver code, functions code, and more.

To make it easily consumable within your CDK app, we can use the AmplifyExportedBackend construct to incorporate it into our app. Go to stages/amplify-stage.ts and import the CDK construct and use it to create a new Amplify stack. Your amplify-stage.ts file should look something like this:

import { CfnOutput, cfnTagToCloudFormation, Construct, Stage, StageProps } from '@aws-cdk/core';
import { AmplifyExportedBackend } from '@aws-amplify/cdk-exported-backend';
import * as path from 'path'
import * as cdk from '@aws-cdk/core'

export class AmplifyStage extends Stage {
  
  constructor(scope: Construct, id: string, props?: StageProps) {
    super(scope, id, props);
    
    // ADD AMPLIFY EXPORTED BACKEND STACK HERE
    const amplifyStack = new AmplifyExportedBackend(this, "amplifyexportedbackend", {
      path: path.resolve(__dirname, '..', 'amplify-export-mytodoapp'),
      amplifyEnvironment: "dev"
    })
  }
}

7. Deploy your CDK pipeline

Commit all your CDK pipeline changes to git and push it to GitHub.

git add .
git commit -a -m "Initial commit"
git push

If this is your first time setting up a CDK pipeline, you will also need to bootstrap an environment (a combination of AWS account ID and region) before your initial deployment. Learn more about CDK Bootstrapping.

npx cdk bootstrap --profile default # REPLACE WITH YOUR PROFILE

Next, deploy your pipeline to the cloud:

npx cdk deploy

Once the deployment is complete, you should see a new CDK pipeline show up in the AWS CodePipeline console.

8. Iterate on your Amplify project and export again!

Yes, you can keep using the Amplify CLI; this is not a one way door! “Export” is not an “eject” workflow! Frontend developers can keep using Amplify CLI to iterate on their app fast and whenever they are ready to hand the backend over to the DevOps team or submit it to a centralized deployment pipeline, they can run amplify export again.

Let’s try by adding auth resources to our Amplify backend:

amplify add auth

(For the purposes of this demo, feel free to accept all the default selections)

Then export the stack again to the CDK pipeline:

amplify export --out ../mycdkpipeline/lib/

To trigger a new build, all you have to do is commit the changes to Git. Then your CI/CD pipeline automatically picks up the changes and deploys them. No code changes needed!

git add .
git commit -a -m "Added Amplify auth"
git push

You can follow the deployment progress by checking out your CodePipeline console.

🥳 Success

You’ve set up a CI/CD pipeline that can deploy Amplify backends. Your frontend team can still leverage Amplify CLI to generate client-side code for their GraphQL API, iterate quickly locally, and hand over a production-ready backend to the DevOps when needed.

Review our documentation for more details. Also feel free to share your feedback with us GitHub or join our community on Discord.