Experimental construct libraries are now available in AWS CDK v2

The AWS CDK v2 experimental APIs are now available as separate packages, in addition to the existing stable APIs.

The AWS Cloud Development Kit (AWS CDK) is an open-source software development framework to model and provision your cloud application resources using familiar programming languages. With the AWS CDK, you can define your infrastructure as code and provision it through AWS CloudFormation. AWS CDK provides high-level components that preconfigure cloud resources with proven defaults, so you can build cloud applications without needing to be an expert. It also enables you to compose and share your own custom components that incorporate your organization’s requirements, which helps teams start new projects faster.

In April of 2021, we announced the developer preview of AWS CDK v2. In AWS CDK v1, we partitioned the AWS Construct Library into many small packages, roughly one per service, so that you only needed to download the packages for those services you wanted to use.

The downside of this approach was that every time you wanted to add a new AWS service to your application, you had to go back to your terminal to npm install or pip install another package. Additionally, it was very important that all these packages were on the exact same version to avoid interoperability issues.

Based on customer feedback about the v1 package experience, we have consolidated all of the stable AWS Construct Libraries into a single package, called aws-cdk-lib. You get access to all the stable AWS CDK constructs by installing this package, and third-party construct libraries only need to take a dependency on this package as well.

We also introduced changes to how we handle experimental classes, methods, and properties. In v1, we followed semantic versioning for all non-experimental code, but where APIs were marked as experimental, we reserved the right to make breaking changes when we felt that the APIs could be improved significantly. Although this gave us the benefit of easily adapting the APIs, customers were sometimes caught off guard by the changes when they didn’t notice the experimental banner on a module. Existing tools don’t provide a way to clearly identify specific modules as experimental, in a way that works across all of the AWS CDK supported runtime languages. In v2, we strictly follow Semantic Versioning and no longer make breaking changes to any APIs in minor version releases. Instead, we introduced a new lifecycle in which new, experimental construct libraries go through an incubation period as a library completely independent from the main aws-cdk-lib library.

For the CDK v2 Developer Preview release, the higher-level constructs (L2s) for experimental modules were removed from aws-cdk-lib, but were not available separately yet. Now, these modules available as separate packages, for example @aws-cdk/aws-amplify-alpha, to clearly indicate their pre-production status using the -alpha qualifier. You can see the full list of experimental modules in 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.

Alpha modules lifecycle

We will create a new alpha module the first time L2 constructs are created for a new service (or core module). After an alpha module stabilizes, it will be moved to aws-cdk-lib and have a guaranteed backwards compatibility within the AWS CDK major version. The AWS CloudFormation (L1) classes are always defined as stable, hence will be included in aws-cdk-lib from day one. To continue the above example, the aws-amplify module included with aws-cdk-lib will contain the L1 classes from day one, whereas the independently-released @aws-cdk/aws-amplify-alpha module will contain the experimental L2 constructs.

You can see that alpha modules are released under @aws-cdk/ namespace with the alpha qualifier, to clearly distinguish them from the stable modules under the aws-cdk-lib/ namespace. The v2 API reference includes these namespaces as well.

Once the experimental L2 construct library is declared stable and is moved to aws-cdk-lib, there will be no new releases of the alpha module (e.g., @aws-cdk/aws-amplify-alpha). Previous versions will still be preserved. In the aforementioned example, the stable constructs will be moved to aws-cdk-lib/aws-amplify module.

Installing the alpha modules

The alpha modules are denoted with an -alpha identifier, to clearly separate them from stable modules. The following examples will walk through installing the @aws-cdk/aws-amplify-alpha module for the AWS Amplify service.

TypeScript/JavaScript

npm install @aws-cdk/aws-amplify-alpha

Python

pip install aws-cdk.aws-amplify-alpha

Java

Add the following to the <dependencies> container of pom.xml.

<dependency>
    <groupId>software.amazon.awscdk</groupId>
    <artifactId>amplify-alpha</artifactId>
    <version>${version}</version>
</dependency>

.NET

dotnet add package Amazon.CDK.AWS.Amplify.Alpha

go get github.com/aws/aws-cdk-go/awscdkamplifyalpha/v2

Using the alpha modules

The following examples show how to import the Amplify service into your code. Imports for the core and s3 libraries are shown for comparison.

TypeScript/JavaScript

import { App, Stack } from 'aws-cdk-lib';
import { aws_s3 as s3 } from 'aws-cdk-lib';
import * as amplify_alpha from '@aws-cdk/aws-amplify-alpha';

Python

from aws_cdk import App, Stack
from aws_cdk import aws_s3 as s3
from aws_cdk import aws_amplify_alpha as amplify_alpha

Java

import software.amazon.awscdk.App;
import software.amazon.awscdk.Stack;
import software.amazon.awscdk.services.s3.Bucket;
import software.amazon.awscdk.services.amplify.alpha.App;

.NET

using Amazon.CDK;
using Amazon.CDK.AWS.S3;
using Amazon.CDK.AWS.Amplify.Alpha;

import (
  "github.com/aws/aws-cdk-go/awscdk"
  "github.com/aws/aws-cdk-go/awscdk/v2/awss3"
  "github.com/aws/aws-cdk-go/awscdkamplifyalpha/v2"
)

Versioning

Alpha modules are released separately from aws-cdk-lib, but their versioning mirrors that of aws-cdk-lib. For each release of aws-cdk-lib (e.g., 2.x.y), the latest version of all alpha modules will also be released, with a corresponding alpha qualifier (e.g., 2.x.y-alpha.0).

At the time of publishing this blog post, the aws-cdk-lib module is still in developer preview. Hence, each released version of aws-cdk-lib will be suffixed with an -rc pre-release tag (e.g., 2.0.0-rc.24) and each released alpha module will receive an -alpha prerelease tag (e.g., 2.0.0-alpha.2). Once aws-cdk-lib is generally available, its pre-release tag will be removed (e.g., 2.0.1), and the alpha modules versioning will be updated to match the current release (e.g., 2.0.1-alpha.1).

Generally, using versions of alpha modules that match the aws-cdk-lib version ensures compatibility; however, you can also use a newer version of aws-cdk-lib than the version of the alpha modules, allowing you to get new features from aws-cdk-lib without needing to also take on new (potentially breaking) changes from the alpha modules.

Things to know

Here are some things to keep in mind:

Each of the alpha modules is independently published and versioned, so you can install and use only the alpha modules you need for your infrastructure. All other modules (available via aws-cdk-lib) will offer stable APIs that will not change in backwards-incompatible ways
Unlike the AWS CDK v1 independent modules, the v2 alpha modules’ versions do not need to exactly match each other or the main aws-cdk-lib module. Co-dependent alpha modules (e.g., aws-apigatewayv2 and aws-apigatewayv2-integrations) should be upgraded in tandem
You can upgrade each alpha module to receive new features without needing to upgrade other unrelated alpha modules
The main v2 changelog (CHANGELOG.v2.md) will include only changes from stable modules, in the standard format. A separate changelog (CHANGELOG.v2.alpha.md) will be created to track all changes to alpha modules.
The release notes (e.g., https://github.com/aws/aws-cdk/releases/tag/v2.0.0-rc.26) for each release will contain the combined notes for both stable and alpha modules, clearly delineated

Conclusion

This release enables you to use experimental modules in AWS CDK v2, and makes it even easier to migrate from v1. You can read about our thinking on some of the options we considered to make this transition in the CDKv2 Experiments RFC. For more information, see Migrating to AWS CDK v2 topic in developer guide and the v2 API reference. As always, we welcome bug reports, feature requests, and pull requests in the aws-cdk GitHub repository.

About the authors

Nick Lynch is a Senior Software Developer at AWS. He works on the AWS Cloud Development Kit (AWS CDK) and focuses on enabling developers to build their infrastructure faster.

Alex Pulver is a Senior Partner Solutions Architect at AWS SaaS Factory team. He works with AWS Partners at any stage of their software-as-a-service (SaaS) journey to help build new products, migrate existing applications, or optimize SaaS solutions on AWS. His areas of interest include builder experience (e.g., developer tools, DevOps culture, CI/CD), containers, security, IoT, and AWS multi-account strategy.

AWS Developer Tools Blog