This is the AWS CDK v2 Developer Guide. The older CDK v1 entered maintenance on June 1, 2022 and ended support on June 1, 2023.
# AWS CDK reference
This section contains reference information for the AWS Cloud Development Kit (AWS CDK).
## API reference
The [API Reference](https://docs.aws.amazon.com/cdk/api/v2) contains information about the AWS Construct Library and other APIs provided by the AWS Cloud Development Kit (AWS CDK). Most of the AWS Construct Library is contained in a single package called by its TypeScript name: `aws-cdk-lib`. The actual package name varies by language. Separate versions of the API reference are provided for each supported programming language.
The CDK API reference is organized into sub-modules. There are one or more sub-modules for each AWS service.
Each sub-module has an overview that includes information about how to use its APIs. For example, the [S3](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3-readme.html) overview demonstrates how to set default encryption on an Amazon Simple Storage Service (Amazon S3) bucket.
# AWS CDK versioning
This topic provides reference information on how the AWS Cloud Development Kit (AWS CDK) handles versioning.
Version numbers consist of three numeric version parts: *major*.*minor*.*patch*, and broadly follow [semantic versioning](https://semver.org) principles with a few caveats described in [AWS Construct Library semantic versioning clarifications](https://docs.aws.amazon.com/cdk/v2/guide/versioning.html#aws-construct-lib-semver). This means that breaking changes to APIs we consider stable are limited to major releases.
Minor and patch releases are backward compatible. The code written in a previous version with the same major version can be upgraded to a newer version within the same major version. It will continue to build and run, producing a functionally equivalent result. For some advanced use cases, small changes to your code will be required as noted in the next topic.
## AWS CDK Toolkit compatibility
Each version of the main AWS Construct Library (`aws-cdk-lib`) is compatible with the AWS CDK Toolkit CLI (`aws-cdk-cli`) and Toolkit Library (`@aws-cdk/toolkit-lib`) version that was current at the time of the AWS Construct Library’s release. It is also compatible with any newer version of the AWS CDK Toolkit. Each version of the AWS Construct Library maintains this compatibility until the library’s *End of Life* date. Therefore, as long as you’re using a supported AWS Construct Library version, it is always safe to upgrade your AWS CDK Toolkit version.
Each version of the AWS Construct Library might also work with AWS CDK Toolkit versions older than the version that was current at the time of the AWS Construct Library’s release. However, this is not guaranteed. Compatibility depends on the AWS Construct Library’s cloud assembly schema version. The AWS CDK generates a cloud assembly during synthesis and the AWS CDK Toolkit consumes it for deployment. The schema that defines the format of the cloud assembly is strictly specified and versioned. Therefore, an older version of the AWS CDK Toolkit would need to support the cloud assembly schema version of the AWS Construct Library for them to be compatible.
When the cloud assembly version required by the AWS Construct Library is not compatible with the version supported by the AWS CDK Toolkit, you receive an error message like the following:
```
Cloud assembly schema version mismatch: Maximum schema version supported is 3.0.0, but found 4.0.0.
Please upgrade your CLI in order to interact with this app.
```
To resolve this error, update the AWS CDK Toolkit to a version compatible with the required cloud assembly version, or to the latest available version. The alternative (downgrading the AWS Construct Library modules your app uses) is generally not recommended.
**Note**
For more information on the exact combinations of versions that work together, see the [compatibility table](https://github.com/aws/aws-cdk-cli/blob/main/COMPATIBILITY.md) in the *aws-cdk-cli GitHub repository*.
## AWS Construct Library versioning
The modules in the AWS Construct Library move through various stages as they are developed from concept to mature API. Different stages offer varying degrees of API stability in subsequent versions of the AWS CDK.
Except for scenarios where the caveats documented in the next topic apply, APIs in the main AWS Construct Library (`aws-cdk-lib`) are stable, and the library broadly follows semantic versioning principles. The library includes AWS CloudFormation (L1) constructs for all AWS services, which are auto-generated from [CloudFormation resource provider schemas](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/resource-type-schemas.html) and might sometimes include backward incompatible updates. It also includes higher-level (L2 and L3) constructs and the core CDK classes like `App` and `Stack`, which are all stable. APIs will not be removed from this package (though they might be deprecated) until the next major release of the CDK. When a breaking change is required to a stable API, an entirely new API will be added.
New APIs under development for a service already incorporated in `aws-cdk-lib` are identified using a `Beta` suffix, where `N` starts at 1 and is incremented with each breaking change to the new API. `Beta` APIs are never removed, only deprecated, so your existing app continues to work with newer versions of `aws-cdk-lib`. When the API is deemed stable, a new API without the `Beta` suffix is added.
When higher-level (L2 or L3) APIs begin to be developed for an AWS service that previously had only L1 APIs, those APIs are initially distributed in a separate package. The name of such a package has an "Alpha" suffix, and its version matches the first version of `aws-cdk-lib` it is compatible with, with an `alpha` sub-version. When the module supports the intended use cases, its APIs are added to `aws-cdk-lib`.
## AWS Construct Library semantic versioning clarifications
While the AWS Construct Library broadly follows semantic versioning principles, there are some important caveats specific to our implementation. In general the AWS Construct Library maintains stability for API consumers, but sometimes adds additional burdens to construct authors to enable the necessary evolution of the framework.
+ **Security impacting changes**
To meet our security bar, we might be required to change APIs in backward incompatible ways or remove them entirely. This prevents affected APIs from being used and forces implementations to be updated.
+ **Features are described by intent**
We aim to minimize unexpected changes, but will favor *intent over implementation stability*. The AWS Construct Library does not guarantee that constructs always synthesize to the exact same CloudFormation template or use the exact same set of resources. This especially applies to higher-level constructs, where the same goal can often be achieved in different ways.
+ **Implementing Interfaces and Abstract Classes**
Interfaces and abstract classes in the AWS Construct Library are stable for **consumers**, but not for **implementors**. This means that you can safely rely on interfaces like `s3.IBucket` to provide at least the same functionality as at the time (AWS Construct Library version) that you started consuming the interface or abstract class. However, periodically, new (abstract) members will be added to interfaces and abstract classes. For anyone **implementing** them, this creates an additional implementation burden to consider when upgrading, since the implementation wouldn’t be implementing the new members yet. Strictly treating additions to interfaces and abstract classes for implementors as breaking changes would unduly limit the evolvability of the AWS Construct Library. In most cases, implementors should prefer to extend concrete classes like `s3.Bucket`.
+ **L1 constructs, generated code, and other APIs marked as external**
Parts of the AWS Construct Library are generated from data sources coming directly from AWS services. To keep these APIs aligned with reality, generated code might contain backward incompatible changes. Most of the time, data sources are updated to correctly reflect reality and rectify incorrect representation. *Your IDE’s IntelliSense will display external APIs with the `@stability — external` annotation.*
+ **Semantically correct programs only**
We ensure that correct programs continue to work with newer versions. Programs that are formally incorrect but happen to work due to implementation details are not covered. For example, if your program relies on [TypeScript’s structural typing rules](https://www.typescriptlang.org/docs/handbook/type-compatibility.html) to pass unexpected object types, or synthesizes successfully but produces a CloudFormation template that fails to deploy, we may introduce changes that cause these programs to fail without considering them breaking changes.
+ **Specific language bindings**
Language bindings can contain backward incompatible changes in a very limited number of situations. These are caused by upstream type changes that are backward compatible in other supported languages. These types changes are allowed, as doing otherwise would severely limit the evolvability of the library.
The following list describes all known instances:
+ **Golang - Changing from typed slice to any slice: ** A list of a single type is changing to a list of multiple types (union types in TypeScript). In `Go`, these are typed as a slice of any (`*[]any`). Due to Go’s typing assignment rules, changing from `*[]string ` to `` is not an automatic conversion. Therefore, this type widening requires consumer code to change. See [Working with any slice](https://docs.aws.amazon.com/cdk/v2/guide/work-with-cdk-go.html#go-cdk-idioms) for strategies.
## Language binding stability
Over time, we might add support to the AWS CDK for additional programming languages. Although the API described in all the languages is the same, the way that API is expressed varies by language and might change as the language support evolves. For this reason, language bindings are deemed experimental for a time until they are considered ready for production use.
| Language | Stability |
| --- | --- |
| TypeScript | Stable |
| JavaScript | Stable |
| Python | Stable |
| Java | Stable |
| C\$1/.NET | Stable |
| Go | Stable |
# Supported Node.js versions for the AWS CDK
The AWS Cloud Development Kit (AWS CDK) runs on Node.js. This includes the AWS CDK CLI (`aws-cdk-cli`), AWS Construct Library (`aws-cdk-lib`), as well as broader ecosystem tools such as JSII, Projen, and CDK8s.
## Version support policy
The AWS CDK supports Node.js Long Term Support (LTS) versions. When a Node.js version reaches its community End-of-Life (EOL), the AWS CDK continues to support it for an additional 6 months before ending support.
After support ends, the AWS CDK team will no longer provide security patches, bug fixes, or compatibility updates for that Node.js version. Using the AWS CDK with an unsupported Node.js version may result in unexpected behavior, errors, or security vulnerabilities.
For upcoming Node.js release and EOL dates, see the [Node.js release schedule](https://github.com/nodejs/Release#release-schedule).
## Supported Node.js versions
The following table lists Node.js versions currently supported by the AWS CDK.
| Node.js version | Node.js EOL date | CDK support end date |
| --- | --- | --- |
| 24.x | 2028-04-30 | 2028-10-30 |
| 22.x | 2027-04-30 | 2027-10-30 |
| 20.x | 2026-04-30 | 2026-10-30 |
## Node.js versions no longer supported
The following Node.js versions are no longer supported by the AWS CDK.
| Node.js version | Node.js EOL date | CDK support ended |
| --- | --- | --- |
| 18.x | 2025-05-30 | 2025-11-30 |
| 16.x | 2023-09-11 | 2025-05-30 |
| 14.x | 2023-04-30 | 2025-05-30 |
# AWS CDK video resources
Enjoy these videos presented by members of the AWS CDK team.
**Note**
Since the AWS CDK is always evolving, some of the code presented in these videos may not work quite the same way it did when the video was recorded. This is especially true for modules that were under active development at the time. It’s also possible that we’ve since added a better way to achieve the same result. Consult this Developer Guide and the [AWS CDK API Reference](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-construct-library.html) for up-to-date information.
## Infrastructure *is* Code with the AWS CDK
[](http://www.youtube.com/watch?v=https://www.youtube.com/embed/ZWCvNFUN-sU?rel=0)
## Deep dive into AWS Cloud Development Kit (AWS CDK)
[](http://www.youtube.com/watch?v=https://www.youtube.com/embed/9As_ZIjUGmY?rel=0)
## Contributing to the AWS Construct Library
[](http://www.youtube.com/watch?v=https://www.youtube.com/embed/LsYlf7ggyrY?rel=0)
## Faster deployments with CDK Pipelines
[](http://www.youtube.com/watch?v=https://www.youtube.com/embed/1ps0Wh19MHQ?rel=0)
## How to contribute to the AWS CDK using GitPod
[](http://www.youtube.com/watch?v=https://www.youtube.com/embed/u6XcIgs-Nok?rel=0)