Experimental construct libraries are now available in Amazon CDK v2

{"value":"The AWS CDK v2 experimental APIs are now available as separate packages, in addition to the existing stable APIs.\n\nThe [AWS Cloud Development Kit (AWS CDK)](https://aws.amazon.com/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](https://aws.amazon.com/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.\n\nIn April of 2021, we [announced](https://aws.amazon.com/blogs/developer/announcing-aws-cloud-development-kit-v2-developer-preview/) the developer preview of AWS CDK v2. In AWS CDK v1, we partitioned the [AWS Construct Library](https://docs.aws.amazon.com/cdk/api/latest/docs/aws-construct-library.html) into many small packages, roughly one per service, so that you only needed to download the packages for those services you wanted to use.\n\nThe 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.\n\nBased 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.\n\nWe 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](https://semver.org/) 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.\n\nFor 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](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-construct-library.html). 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.\n\n### **Alpha modules lifecycle**\n\nWe 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.\n\nYou 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](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-construct-library.html) includes these namespaces as well.\n\nOnce 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.\n\n### **Installing the alpha modules**\n\nThe 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-foobar-alpha``` module for a hypothetical AWS service called ```FooBar```.\n\n*TypeScript/JavaScript*\n\n\nBash\n\n```\nnpm install @aws-cdk/aws-foobar-alpha\n```\n\n*Python*\n\nBash\n\n```\npip install aws-cdk.aws-foobar-alpha\n```\n*Java*\n\nAdd the following to the``` <dependencies>``` container of ```pom.xml```.\n\nXML\n\n```\n<dependency>\n <groupId>software.amazon.awscdk</groupId>\n <artifactId>foobar-alpha</artifactId>\n <version>${version}</version>\n</dependency>\n```\n*.NET*\n\nBash\n\ndotnet add package Amazon.CDK.AWS.FooBar.Alpha\n\n*Go*\n\n\nBash\n\n```\ngo get github.com/aws/aws-cdk-go/awscdkfoobaralpha/v2\n```\n\n### **Using the alpha modules**\n\nThe following examples show how to import the ```FooBar``` service into your code. Imports for the ```core``` and ```s3``` libraries are shown for comparison.\n\n*TypeScript/JavaScript*\n\nTypeScript\n\n```\nimport { App, Stack } from 'aws-cdk-lib';\nimport { aws_s3 as s3 } from 'aws-cdk-lib';\nimport * as foobar_alpha from '@aws-cdk/aws-foobar-alpha';\n```\n\n*Python*\n\nPython\n\n```\nfrom aws_cdk import App, Stack\nfrom aws_cdk import aws_s3 as s3\nfrom aws_cdk import aws_foobar_alpha as foobar_alpha\n```\n\n*Java*\n\nJava\n\n```\nimport software.amazon.awscdk.App;\nimport software.amazon.awscdk.Stack;\nimport software.amazon.awscdk.services.s3.Bucket;\nimport software.amazon.awscdk.services.foobar.alpha.FooBarConstruct;\n\n```\n\n*.NET*\n\nASP.NET (C#)\n\n```\nusing Amazon.CDK;\nusing Amazon.CDK.AWS.S3;\nusing Amazon.CDK.AWS.FooBar.Alpha;\n```\n*Go*\n\nGo\n\n```\nimport (\n \"github.com/aws/aws-cdk-go/awscdk\"\n \"github.com/aws/aws-cdk-go/awscdk/v2/awss3\"\n \"github.com/aws/aws-cdk-go/awscdkfoobaralpha/v2\"\n)\n\n```\n\n\n### **Versioning**\n\nAlpha 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```).\n\nAt 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```).\n\nGenerally, 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.\n\n\n### **Things to know**\n\nHere are some things to keep in mind:\n\n- 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\n- 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\n- You can upgrade each alpha module to receive new features without needing to upgrade other unrelated alpha modules\n- 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.\n- The release notes ([e.g., https://github.com/aws/aws-cdk/releases/tag/v2.0.0-rc.26](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\n\n### **Conclusion**\n\nThis 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](https://github.com/aws/aws-cdk-rfcs/blob/master/text/0249-v2-experiments.md) RFC. For more information, see [Migrating to AWS CDK v2](https://docs.aws.amazon.com/cdk/latest/guide/work-with-cdk-v2.html) topic in developer guide and the [v2 API reference](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-construct-library.html). As always, we welcome bug reports, feature requests, and pull requests in the [aws-cdk](https://github.com/aws/aws-cdk/) GitHub repository.\n\n##### **About the authors**\n\n\n\n\n**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.\n\n\n\n\n**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.","render":"<p>The AWS CDK v2 experimental APIs are now available as separate packages, in addition to the existing stable APIs.</p>\n<p>The <a href=\"https://aws.amazon.com/cdk/\" target=\"_blank\">AWS Cloud Development Kit (AWS CDK)</a> 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 <a href=\"https://aws.amazon.com/cloudformation/\" target=\"_blank\">AWS CloudFormation</a>. 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.</p>\n<p>In April of 2021, we <a href=\"https://aws.amazon.com/blogs/developer/announcing-aws-cloud-development-kit-v2-developer-preview/\" target=\"_blank\">announced</a> the developer preview of AWS CDK v2. In AWS CDK v1, we partitioned the <a href=\"https://docs.aws.amazon.com/cdk/api/latest/docs/aws-construct-library.html\" target=\"_blank\">AWS Construct Library</a> into many small packages, roughly one per service, so that you only needed to download the packages for those services you wanted to use.</p>\n<p>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 <code>npm install</code> or <code>pip install</code> another package. Additionally, it was very important that all these packages were on the exact same version to avoid interoperability issues.</p>\n<p>Based on customer feedback about the v1 package experience, we have consolidated all of the stable AWS Construct Libraries into a single package, called <code>aws-cdk-lib</code>. 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.</p>\n<p>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 <a href=\"https://semver.org/\" target=\"_blank\">Semantic Versioning</a> 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 <code>aws-cdk-lib</code> library.</p>\n<p>For the CDK v2 Developer Preview release, the higher-level constructs (L2s) for experimental modules were removed from <code>aws-cdk-lib</code>, but were not available separately yet. Now, these modules available as separate packages, for example <code>@aws-cdk/aws-amplify-alpha</code>, to clearly indicate their pre-production status using the <code>-alpha</code> qualifier. You can see the full list of experimental modules in the <a href=\"https://docs.aws.amazon.com/cdk/api/v2/docs/aws-construct-library.html\" target=\"_blank\">v2 API reference</a>. Only after the new module has matured and has been put through its paces in several real-world scenarios will we include it into <code>aws-cdk-lib</code> as stable. This means that every method, class, and property in <code>aws-cdk-lib</code> 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.</p>\n<h3><a id=\"Alpha_modules_lifecycle_14\"></a><strong>Alpha modules lifecycle</strong></h3>\n<p>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 <code>aws-cdk-lib</code> 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 <code>aws-cdk-lib</code> from day one. To continue the above example, the <code>aws-amplify</code> module included with <code>aws-cdk-lib</code> will contain the L1 classes from day one, whereas the independently-released <code>@aws-cdk/aws-amplify-alpha</code> module will contain the experimental L2 constructs.</p>\n<p>You can see that alpha modules are released under <code>@aws-cdk/</code> namespace with the alpha qualifier, to clearly distinguish them from the stable modules under the <code>aws-cdk-lib/</code> namespace. The <a href=\"https://docs.aws.amazon.com/cdk/api/v2/docs/aws-construct-library.html\" target=\"_blank\">v2 API reference</a> includes these namespaces as well.</p>\n<p>Once the experimental L2 construct library is declared stable and is moved to <code>aws-cdk-lib</code>, there will be no new releases of the alpha module (e.g., <code>@aws-cdk/aws-amplify-alpha)</code>. Previous versions will still be preserved. In the aforementioned example, the stable constructs will be moved to <code>aws-cdk-lib/aws-amplify</code> module.</p>\n<h3><a id=\"Installing_the_alpha_modules_22\"></a><strong>Installing the alpha modules</strong></h3>\n<p>The alpha modules are denoted with an <code>-alpha </code>identifier, to clearly separate them from stable modules. The following examples will walk through installing the <code>@aws-cdk/aws-foobar-alpha</code> module for a hypothetical AWS service called <code>FooBar</code>.</p>\n<p><em>TypeScript/JavaScript</em></p>\n<p>Bash</p>\n<pre><code class=\"lang-\">npm install @aws-cdk/aws-foobar-alpha\n</code></pre>\n<p><em>Python</em></p>\n<p>Bash</p>\n<pre><code class=\"lang-\">pip install aws-cdk.aws-foobar-alpha\n</code></pre>\n<p><em>Java</em></p>\n<p>Add the following to the<code> &lt;dependencies&gt;</code> container of <code>pom.xml</code>.</p>\n<p>XML</p>\n<pre><code class=\"lang-\">&lt;dependency&gt;\n &lt;groupId&gt;software.amazon.awscdk&lt;/groupId&gt;\n &lt;artifactId&gt;foobar-alpha&lt;/artifactId&gt;\n &lt;version&gt;${version}&lt;/version&gt;\n&lt;/dependency&gt;\n</code></pre>\n<p><em>.NET</em></p>\n<p>Bash</p>\n<p>dotnet add package Amazon.CDK.AWS.FooBar.Alpha</p>\n<p><em>Go</em></p>\n<p>Bash</p>\n<pre><code class=\"lang-\">go get github.com/aws/aws-cdk-go/awscdkfoobaralpha/v2\n</code></pre>\n<h3><a id=\"Using_the_alpha_modules_70\"></a><strong>Using the alpha modules</strong></h3>\n<p>The following examples show how to import the <code>FooBar</code> service into your code. Imports for the <code>core</code> and <code>s3</code> libraries are shown for comparison.</p>\n<p><em>TypeScript/JavaScript</em></p>\n<p>TypeScript</p>\n<pre><code class=\"lang-\">import { App, Stack } from 'aws-cdk-lib';\nimport { aws_s3 as s3 } from 'aws-cdk-lib';\nimport * as foobar_alpha from '@aws-cdk/aws-foobar-alpha';\n</code></pre>\n<p><em>Python</em></p>\n<p>Python</p>\n<pre><code class=\"lang-\">from aws_cdk import App, Stack\nfrom aws_cdk import aws_s3 as s3\nfrom aws_cdk import aws_foobar_alpha as foobar_alpha\n</code></pre>\n<p><em>Java</em></p>\n<p>Java</p>\n<pre><code class=\"lang-\">import software.amazon.awscdk.App;\nimport software.amazon.awscdk.Stack;\nimport software.amazon.awscdk.services.s3.Bucket;\nimport software.amazon.awscdk.services.foobar.alpha.FooBarConstruct;\n\n</code></pre>\n<p><em>.NET</em></p>\n<p>ASP.NET (C#)</p>\n<pre><code class=\"lang-\">using Amazon.CDK;\nusing Amazon.CDK.AWS.S3;\nusing Amazon.CDK.AWS.FooBar.Alpha;\n</code></pre>\n<p><em>Go</em></p>\n<p>Go</p>\n<pre><code class=\"lang-\">import (\n &quot;github.com/aws/aws-cdk-go/awscdk&quot;\n &quot;github.com/aws/aws-cdk-go/awscdk/v2/awss3&quot;\n &quot;github.com/aws/aws-cdk-go/awscdkfoobaralpha/v2&quot;\n)\n\n</code></pre>\n<h3><a id=\"Versioning_129\"></a><strong>Versioning</strong></h3>\n<p>Alpha modules are released separately from <code>aws-cdk-lib</code>, but their versioning mirrors that of <code>aws-cdk-lib</code>. For each release of <code>aws-cdk-lib</code> (e.g., <code>2.x.y</code>), the latest version of all alpha modules will also be released, with a corresponding alpha qualifier (e.g., <code>2.x.y-alpha.0</code>).</p>\n<p>At the time of publishing this blog post, the <code>aws-cdk-lib</code> module is still in developer preview. Hence, each released version of <code>aws-cdk-lib</code> will be suffixed with an <code>-rc</code> pre-release tag (e.g., <code>2.0.0-rc.24</code>) and each released alpha module will receive an <code>-alpha</code> prerelease tag (e.g., <code>2.0.0-alpha.2</code>). Once <code>aws-cdk-lib</code> is generally available, its pre-release tag will be removed (e.g., <code>2.0.1</code>), and the alpha modules versioning will be updated to match the current release (e.g., <code>2.0.1-alpha.1</code>).</p>\n<p>Generally, using versions of alpha modules that match the <code>aws-cdk-lib</code> version ensures compatibility; however, you can also use a newer version of <code>aws-cdk-lib</code> than the version of the alpha modules, allowing you to get new features from <code>aws-cdk-lib</code> without needing to also take on new (potentially breaking) changes from the alpha modules.</p>\n<h3><a id=\"Things_to_know_138\"></a><strong>Things to know</strong></h3>\n<p>Here are some things to keep in mind:</p>\n<ul>\n<li>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 <code>aws-cdk-lib</code>) will offer stable APIs that will not change in backwards-incompatible ways</li>\n<li>Unlike the AWS CDK v1 independent modules, the v2 alpha modules’ versions do not need to exactly match each other or the main <code>aws-cdk-lib</code> module. Co-dependent alpha modules (e.g., <code>aws-apigatewayv2</code> and <code>aws-apigatewayv2-integrations</code>) should be upgraded in tandem</li>\n<li>You can upgrade each alpha module to receive new features without needing to upgrade other unrelated alpha modules</li>\n<li>The main v2 changelog (<code>CHANGELOG.v2.md</code>) will include only changes from stable modules, in the standard format. A separate changelog (<code>CHANGELOG.v2.alpha.md</code>) will be created to track all changes to alpha modules.</li>\n<li>The release notes (<a href=\"https://github.com/aws/aws-cdk/releases/tag/v2.0.0-rc.26\" target=\"_blank\">e.g., https://github.com/aws/aws-cdk/releases/tag/v2.0.0-rc.26</a>) for each release will contain the combined notes for both stable and alpha modules, clearly delineated</li>\n</ul>\n<h3><a id=\"Conclusion_148\"></a><strong>Conclusion</strong></h3>\n<p>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 <a href=\"https://github.com/aws/aws-cdk-rfcs/blob/master/text/0249-v2-experiments.md\" target=\"_blank\">CDKv2 Experiments</a> RFC. For more information, see <a href=\"https://docs.aws.amazon.com/cdk/latest/guide/work-with-cdk-v2.html\" target=\"_blank\">Migrating to AWS CDK v2</a> topic in developer guide and the <a href=\"https://docs.aws.amazon.com/cdk/api/v2/docs/aws-construct-library.html\" target=\"_blank\">v2 API reference</a>. As always, we welcome bug reports, feature requests, and pull requests in the <a href=\"https://github.com/aws/aws-cdk/\" target=\"_blank\">aws-cdk</a> GitHub repository.</p>\n<h5><a id=\"About_the_authors_152\"></a><strong>About the authors</strong></h5>\n<p><img src=\"https://dev-media.amazoncloud.cn/5f3efa3f451c4368ab8c386743a302ac_image.png\" alt=\"image.png\" /></p>\n<p><strong>Nick Lynch is a Senior Software Developer at AWS</strong>. He works on the AWS Cloud Development Kit (AWS CDK) and focuses on enabling developers to build their infrastructure faster.</p>\n<p><img src=\"https://dev-media.amazoncloud.cn/e4b9f895525d4d909c00402bfb734976_image.png\" alt=\"image.png\" /></p>\n<p><strong>Alex Pulver is a Senior Partner Solutions Architect at AWS SaaS Factory team</strong>. 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.</p>\n"}