How customer feedback shaped the AWS Cloud Development Kit version 2

The DevOps movement has blurred the line between runtime code and infrastructure code, and it’s no surprise that engineers want to write both in the same language. This is why we created the AWS Cloud Development Kit (CDK), which enables you to define your cloud Infrastructure as Code (IaC) using the familiarity and expressive power of the same programming languages you use for your applications. Like many innovations at AWS, the CDK was born out of our relentless drive to simplify and reinvent. We had an internal problem to solve and the proof of concept was so compelling, it led to the creation of the AWS CDK as an open source project for anyone to use. It’s the same mindset that led to this significant update to CDK, which includes productivity improvements for developers working with CDK projects.

Customers of all shapes and sizes are sharing their success stories using the CDK. For example, Amazon Prime Video and IMDb TV describe how they use the CDK to seamlessly provision their environments and fine-grained IAM task roles. Audi and Stedi explain how they use the CDK to drastically improve their development and feedback cycles, reducing the time it takes to go from brand-new to fully-deployed infrastructure. HDI and VMWare leverage CDK Pipelines to model their CI/CD pipelines-as-code, which allows them to maintain the CDK project as well as the pipeline that delivers it in the same code repository. Liberty Mutual has created a software accelerator of common infrastructure patterns using the CDK, which gives staff a common language with which to collaborate, and new hires and engineers with little cloud experience proven patterns to hit the ground running. Momenta uses the CDK to strengthen the management of their Kubernetes clusters, and Vendia uses the CDK to trigger dynamic infrastructure deployment based on user actions in their service, rather than a traditional CI/CD pipeline triggered by development or ops teams.

Based on the feedback from these customers and thousands of other CDK users, we’ve been working hard on the next version of the AWS CDK.

Introducing AWS CDK version 2

We are thrilled to announce the general availability of the AWS Cloud Development Kit (CDK) version 2, the next major version of the open source software development framework for defining your cloud application resources in TypeScript, Python, Java, C#, and Go (in developer preview).

The most important thing you need to know about CDK v2 is that it introduces packaging changes that make it easier for you to consume the CDK and stay up to date with new features as we evolve it going forwards. 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. If you write your own CDK construct libraries, you only need to take a minimum peer dependency on this single package and let library consumers choose which exact AWS CDK version to use.

The second thing to know is CDK v2 only includes stable APIs, which fully comply with Semantic Versioning (semver), so you can confidently update to new minor versions. In the CDK v2, the Layer 2 constructs (or “L2s”) for experimental modules were removed from aws-cdk-lib, and are now available as separate packages. For example, @aws-cdk/aws-amplify-alpha clearly indicates the pre-production status by using the -alpha qualifier. You can see the full list of experimental modules in the @aws-cdk/ namespace of the v2 API reference. Only after the new module has matured and has been put through its paces in several real-world scenarios will we include it into aws-cdk-lib as stable. This means that every method, class, and property in aws-cdk-lib is guaranteed to exist until the next major version update, and you can update to new minor versions at any time without having to touch your code. You can read more about experimental construct libraries in a previous blog post.

If you are new to the CDK, get started quickly with this step-by-step tutorial, or check out the migration guide and the CDK Migration Workshop to update your existing CDK projects to CDK v2. Migrating from the latest minor version of an AWS CDK v1 application to v2 is relatively painless. You need to start by re-bootstrapping your AWS accounts, which is a one-time action. Then for most projects, all you need to do is update your import statements, synthesize, and deploy.

What’s New in the CDK

Apart from the new packaging format, CDK v1 and CDK v2 are functionally equivalent, and we will continue to update the AWS Construct Library with new features every week. Over the course of 2021, the AWS CDK team and over 500 members of the CDK community have made more than 3,000 contributions to the framework. Some of our favorite features, which are available in all CDK versions, include:

• API reference improvements – There are now more code example snippets, in all supported programming languages, throughout the CDK API Reference to help you learn how to use the CDK faster. Previously code snippets were only available on the README overview page for packages with higher-level L2 constructs, but now there are code examples on every page of the API reference.
• Faster development iterations – The new CDK Watch command improves the speed of the edit-compile-test loop for your CDK application during development by watching your changes and deploying them automatically in the background for you while you keep working in the code. The new “watch” mode will also inspect the assets in your application, identifying those that can be updated in-place without a full CloudFormation stack update, and perform a hotswap using AWS service APIs directly. You can also preserve successfully provisioned resources by disabling automatic stack rollbacks, further reducing deployment and iteration time.
• Unit testing in all languages – A benefit of describing your application’s IaC using a general purpose programming language is the ability to write unit tests for your infrastructure like you write tests for your application. CDK v1 in TypeScript shipped with a library that made it easy to make assertions on your infrastructure. The new assertions library is now available in all supported languages, and provides additional functions for writing fine grained unit tests to validate resources defined in CDK generated CloudFormation templates.
• Pipelines-as-code – CDK Pipelines is a high-level construct library that makes it easy to set up a continuous deployment pipeline for your CDK applications, so you can transition from running cdk deploy on your command line to issuing git push commands to trigger infrastructure changes. Pipelines created with CDK Pipeline are self-mutating so thy automatically update themselves if you add new CDK applications or stages in the source code.
• Go CDK (dev preview) – To scale the CDK across multiple programming languages, and maintain feature parity and API consistency, we designed the JavaScript Interoperability Interface (jsii), a modified TypeScript compiler which allows developers to author modules once and package them into idiomatic modules for all supported languages. Go, currently in developer preview, is the latest language added, joining Java, .NET, and Python.
• Reusable community constructs – The CDK community is sharing their cloud architecture knowledge as reusable construct libraries on public package managers like npm and PyPi. The Construct Hub is a new online registry that makes it easy to discover these open-source building blocks for cloud applications, helping you get started faster by not starting from scratch. On Construct Hub you can find and use construct libraries for CDK for CloudFormation (AWS CDK), CDK for Kubernetes (CDK8s) and CDK for Terraform (CDKtf).

API Reference Improvements

The AWS Construct Library is built in layers of abstraction. The CloudFormation resource constructs, or “L1” layer, is automatically generated, including the API documentation, from the public CloudFormation resource specification so that you always have access to every resource type and property, as they become available. You’ll recognize the “L1” constructs by their Cfn* prefix. On top of the “L1” layer, the CDK team and the open source community add CDK constructs, or the “L2” layer, which provide more intent based APIs, sensible default values, and convenient methods for cross service integration. One of the requirements for adding CDK “L2” constructs to the AWS Construct Library is to write a README document which provides an overview on how to define the service in CDK projects, including code samples.

Customers tell us they love the detailed overview pages in the CDK API Reference because of the useful code samples, but are disappointed in the lack of code samples for services that don’t have “L2” constructs yet. We heard you, and are happy to announce there are now more code samples, in all supported programming languages, throughout the CDK API Reference to help you learn how to use the CDK faster. Every construct, struct, class, interface, and enum sub-page in the API reference now has a code sample to better illustrate how to use it in your project. This applies to both “L1” and “L2” constructs. These code samples are not only available in TypeScript, but in all CDK supported programming language.

For example, the screenshot below shows a TypeScript code snippet for how to use the Lambda Function “L2” construct class.

You also get code examples for using all the “L1” constructs. The Python example that follows shows you how to use the CfnJob construct class in the AWS Glue construct library.

In addition to “L1” and “L2” construct pages, code snippets are available throughout the CDK API reference. The next Java example shows how to define the properties for an Athena Workgroup.

Faster Development Iterations

Developers spend a majority of their time in the “edit-compile-test“ loop when authoring software, and an important driver of productivity in this phase is speed of iteration. That’s why we’ve introduced three new options for the CDK CLI, --watch , --hotswap and --no-rollback. Use the cdk watch command to continuously monitor your project to perform the fastest form of deployment on the stacks that change, as they change. CDK hotswap inspects the assets and stack resources in your project and identifies those that can be updated in-place without a full CloudFormation stack update, and uses AWS service APIs to directly make the changes instead. CDK hotswap speeds up your development iterations when used with the following asset types in your CDK project: AWS Lambda function handler code, Amazon ECS tasks, and AWS Step Functions state machines. Read the Deploying stacks topic in the CDK Developer Guide to learn more about speeding up your CDK development iterations.

When you are iterating on your infrastructure code in your development environment, the CDK --no-rollback command allows you to preserve successfully provisioned resources by disabling automatic stack rollbacks, further reducing deployment and iteration time. By default, if a resource fails to be created or updated, the deployment will roll back before the CLI returns. All changes made up to that point will be undone (resources that were created will be deleted, updates that were made will be changed back) in order to leave the stack in a consistent state at the end of the operation. If you are using the CDK CLI to iterate on a development stack in your development account, you can shorten your development cycles with the no-rollback flag by telling CloudFormation to maintain the state of the successfully created resources while you remediate the issue with the failed resources and try to provision them again. To learn more, refer to the CloudFormation documentation.

Unit testing in all languages

Because the AWS CDK enables you to define your infrastructure in general-purpose programming languages, you can also write automated unit tests for your infrastructure code, just like you do for your application code. Automated testing is an essential element in software development, and testing your infrastructure code provides benefits such as ensuring that you will create exactly the resources you expect in the AWS cloud and helping to prevent regressions from being introduced to your infrastructure.

The new CDK assertions library provides a robust set of APIs to precisely verify the CloudFormation templates synthesized by your CDK app. Additionally, the assertions module is available for every language supported by the CDK. The assertions library provides several tools to both assert that certain parts of a template matches given objects and to retrieve certain parts of of a template. Using these tools, you can assert that resources with a given type and properties exist, assert that certain outputs exist, and assert that a template has a given number of resources. Check out the Testing CDK applications in any language blog post to get started validating the infrastructure configurations in your CDK applications.# Prepare the stack for assertions.

Python assertions

# Prepare the stack for assertions.
template = Template.from_stack(processor_stack)

# Assert it creates the function with the correct properties...
template.has_resource_properties(
     "AWS::Lambda::Function",
     {
          "Handler": "handler",
          "Runtime": "nodejs14.x",
     },
)

# Creates the subscription...
template.resource_count_is("AWS::SNS::Subscription", 1)

# Gives permission to SNS to invoke the function for the topic...
template.has_resource_properties(
     "AWS::Lambda::Permission",
     {
          "Action": "lambda:InvokeFunction",
          "Principal": "sns.amazonaws.com",
     },
)

Java assertions

// Prepare the stack for assertions.
final Template template = Template.fromStack(processorStack);

// Assert it creates the function with the correct properties...
template.hasResourceProperties("AWS::Lambda::Function", Map.of(
"Handler", "handler",
"Runtime", "nodejs14.x"
));

// Creates the subscription...
template.resourceCountIs("AWS::SNS::Subscription", 1);

// Gives permission to SNS to invoke the function for the topic...
template.hasResourceProperties("AWS::Lambda::Permission", Map.of(
"Action", "lambda:InvokeFunction",
"Principal", "sns.amazonaws.com"
));

TypeScript assertions

// Prepare the stack for assertions.
const template = Template.fromStack(processorStack);

// Assert it creates the function with the correct properties...
template.hasResourceProperties("AWS::Lambda::Function", {
Handler: "handler",
Runtime: "nodejs14.x",
});

// Creates the subscription...
template.resourceCountIs("AWS::SNS::Subscription", 1);

// Gives permission to SNS to invoke the function for the topic...
template.hasResourceProperties("AWS::Lambda::Permission", {
Action: "lambda:InvokeFunction",
Principal: "sns.amazonaws.com",
});

CI/CD pipelines-as-code

The continuous integration and continuous deployment pipeline is an indispensable tool for achieving high velocity software delivery with high quality. The pipeline brings together your runtime code, your infrastructure code, and your automated tests into a workflow that ensures your application works as expected before it reaches production. A CDK best practice is to store all aspects of your application in a code repository and version control everything. With CDK Pipelines, released earlier this year, you can model your pipelines-as-code and version control it in your CDK project along with your infrastructure code, runtime code, and test code.

CDK Pipelines is a high-level construct library with an opinionated implementation of a continuous deployment pipeline for your CDK applications. It makes some choices for you, but you can put in less effort to use it. It is powered by AWS CodePipeline, a fully managed continuous delivery service that helps automate your release pipelines for fast and reliable application as well as infrastructure updates. No servers need to be provisioned or setup, and you only pay for what you use. The pipeline created by CDK pipelines is self-mutating. This means you only need to run cdk deploy one time to get the pipeline started. After that, the pipeline automatically updates itself if you add new CDK applications or stages in the source code. You can read more about CDK Pipelines in the Developer Guide, and learn how to use it for specific use cases such as, parallel and dynamic SaaS deployments and data lake ETL jobs.

Go CDK (Developer Preview)

A central value proposition of the CDK is to meet developers where they are and enable them to express their infrastructure code in the programming languages where they are most comfortable. To maintain feature parity and API consistency across multiple programming languages, we designed the jsii, an open source framework that allows JavaScript classes (authored in TypeScript) to be re-used from a variety of other programming languages. Earlier this year, Go was added to the family of programming languages available in the CDK, joining TypeScript, Python, Java, and .NET. Read the getting started with the AWS Cloud Development Kit and Go blog post to learn more.

package main

import (
     "github.com/aws/aws-cdk-go/awscdk"
     "github.com/aws/aws-cdk-go/awscdk/awssns"
     "github.com/aws/constructs-go/constructs/v3"
     "github.com/aws/jsii-runtime-go"
)

type HelloCdkGoStackProps struct {
     awscdk.StackProps
}

func NewHelloCdkGoStack(scope constructs.Construct, id string, props *HelloCdkGoStackProps) awscdk.Stack {
     var sprops awscdk.StackProps
     if props != nil {
          sprops = props.StackProps
     }
     stack := awscdk.NewStack(scope, &id, &sprops)

     // The code that defines your stack goes here

     // as an example, here's how you would define an AWS SNS topic
     awssns.NewTopic(stack, jsii.String("MyTopic"), &awssns.TopicProps{
          DisplayName: jsii.String("MyCoolTopic"),
})

return stack
}

func main() {
      app := awscdk.NewApp(nil)

      NewHelloCdkGoStack(app, "HelloCdkGoStack", &HelloCdkGoStackProps{
           awscdk.StackProps{
                Env: env(),
           },
      })

     app.Synth(nil)
}

Find and publish construct libraries

This year, we announced the launch of Construct Hub, an online registry of open-source Cloud Development Kit (CDK) libraries published by the open-source community as well as cloud service providers. You can find construct libraries to integrate with most AWS services as well as third-party offerings such as Datadog, MongoDB, Aqua Security, and more.

Construct Hub helps builders create cloud applications faster by reusing existing building blocks. Each library includes documentation, API reference, and code samples in TypeScript, Python, Java and .NET. You can also find installation instructions for each programming language, a list of dependencies, number of downloads, licensing information, and helpful links.

Use Construct Hub to find construct libraries for CDK for CloudFormation (AWS CDK), CDK for Kubernetes (CDK8s) and CDK for Terraform (CDKtf). To find AWS CDK V2 construct libraries on Construct Hub you can filter the results based on version. Learn how you can contribute to Construct Hub by following the contributing guide.

AWS CDK v1 Maintenance Policy

With the announcement of AWS CDK v2 as generally available, we are also sharing our support plan for AWS CDK v1, which follows the published AWS SDKs and Tools maintenance policy. AWS will continue to fully support CDK v1 for the next 6 months, at which point CDK v1 will enter maintenance mode. Between now and 6/1/2022, AWS will provide regular releases that include support for new services, API updates for existing services, as well as bug and security fixes for both CDK v1 and v2.

On June 1, 2022, CDK v1 enter maintenance mode. During maintenance mode, AWS CDK v1 releases will contain new and updated resource level “L1” constructs and critical bug fixes only. CDK v1 will not receive higher-level “L2” construct updates for new or existing services while in maintenance mode. Maintenance mode has a duration of 12 months.

On June 1, 2023, CDK v1 will reach end-of-support. After this date, the AWS CDK v1 will no longer receive updates or releases. Previously published releases will continue to be available via public package managers and the code will remain on GitHub. Use of a CDK version which has reached end-of-support is done at your own discretion. We recommend you upgrade to the new major version.

Summary

We are excited about CDK v2, how it makes managing package versions easier, and allows you to update to newer versions of the AWS CDK on a regular cadence with confidence. We want to thank our customers and the CDK community for all the constructive feedback we received for AWS CDK v1. Your feedback was so helpful in shaping this next major version and we’d love for you to keep telling us how we can continue to improve the CDK. As always, we welcome bug reports, feature requests, and pull requests on the aws-cdk GitHub repository.

For more information about the CDK, refer to the v2 developer guide, v2 API reference, and the CDK Workshop.