Announcing Amazon Cloud Development Kit v2 Developer Preview

{"value":"The [AWS Cloud Development Kit](https://aws.amazon.com/cdk/) ([AWS CDK](https://aws.amazon.com/cn/cdk/?trk=cndc-detail)) v2 is now available for Developer Preview in TypeScript, Python, Java, C#, and Go. The [AWS CDK](https://aws.amazon.com/cn/cdk/?trk=cndc-detail) is an open-source software development framework to model and provision your cloud application resources using familiar programming languages. With the [AWS CDK](https://aws.amazon.com/cn/cdk/?trk=cndc-detail), you can define your infrastructure as code and provision it through [AWS CloudFormation](https://aws.amazon.com/cloudformation/). [AWS CDK](https://aws.amazon.com/cn/cdk/?trk=cndc-detail) 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 July of 2019, [we announced the general availability of AWS CDK v1](https://aws.amazon.com/blogs/aws/aws-cloud-development-kit-cdk-typescript-and-python-are-now-generally-available/) for Typescript and Python. Since that time, we have released support for additional languages in Java and C#, and we released language bindings for [Go in Developer Preview](https://aws.amazon.com/blogs/developer/getting-started-with-the-aws-cloud-development-kit-and-go/). We’re now announcing a preview release of v2, which introduces a couple of changes that make it easier for you to consume the [AWS CDK](https://aws.amazon.com/cn/cdk/?trk=cndc-detail) and stay up to date with new versions as we evolve it going forwards.\n\nMigrating from the latest minor version of an [AWS CDK](https://aws.amazon.com/cn/cdk/?trk=cndc-detail) 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. You may notice some minor changes to resources, but nothing that requires a resource replacement.\n\nThis post walks you through the changes between [AWS CDK](https://aws.amazon.com/cn/cdk/?trk=cndc-detail) v1 and v2.\n\n#### **The AWS Construct Library now comes in a single package**\n\nIn [AWS CDK](https://aws.amazon.com/cn/cdk/?trk=cndc-detail) v1, we were very careful to partition the [AWS Construct Library](https://docs.aws.amazon.com/cdk/api/latest/docs/aws-construct-library.html) into many small packages, 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, if you were using NPM, it was very important that all these packages were the exact same version, otherwise NPM might install multiple copies of some of the libraries, which then wouldn’t interoperate properly. We have heard feedback from customers telling us how hard it was to manage the dependency on [AWS CDK](https://aws.amazon.com/cn/cdk/?trk=cndc-detail) correctly.\n\nStarting in v2, we have consolidated all of the AWS Construct Library into a single package, called ```aws-cdk-lib```. You get access to all the [AWS CDK](https://aws.amazon.com/cn/cdk/?trk=cndc-detail) constructs by installing this package, and third-party construct libraries only need to take a dependency on this package as well.\n\nWe also extracted the constructs programming model into a separate library, called ```constructs```\n. This is the basis for a bigger ecosystem of interoperable construct libraries, and is already being used by sister projects like [cdk8s](https://cdk8s.io/) and [terraform-cdk](https://github.com/hashicorp/terraform-cdk).\n\nFor more information about the design choices for v2, see the [RFC in our GitHub repo](https://github.com/aws/aws-cdk-rfcs/blob/master/text/0079-cdk-2.0.md).\n\n#### **Removal of the construct compatibility layer**\n\nAs part of our effort to broaden the applicability of the [AWS CDK](https://aws.amazon.com/cn/cdk/?trk=cndc-detail) programming model to other domains such as Kubernetes, we extracted the base ```Construct``` class (and a few related types) from the [AWS CDK](https://aws.amazon.com/cn/cdk/?trk=cndc-detail) to an independent library called [constructs](https://github.com/aws/constructs).\n\nIf you’re defining your own construct or using any of the related APIs, you now have to make code changes to use the ```constructs``` library.\n\nAfter you declare this library as a new dependency, in most cases you just need to adjust your import statements to use the new classes. Most of the class and method names have been retained, and should make this easy to migrate.\n\nIf you’re using advanced [AWS CDK](https://aws.amazon.com/cn/cdk/?trk=cndc-detail) features such as hooking into the [AWS CDK app lifecycle](https://docs.aws.amazon.com/cdk/latest/guide/apps.html#lifecycle), more changes are required to achieve this. All of the details are available in the relevant [release notes](https://github.com/aws/aws-cdk-rfcs/blob/master/text/0192-remove-constructs-compat.md#release-notes).\n\n#### **New lifecycle for experimental APIs**\n\nWe’re also introducing changes to how we handle experimental classes, methods, and properties starting in v2.\n\nIn 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 package, or they simply chose to deploy production stacks with the experiments due to their perceived stability and general level of usefulness.\n\nIn [AWS CDK](https://aws.amazon.com/cn/cdk/?trk=cndc-detail) v2, we no longer make intentional breaking changes to any APIs in minor version releases. Instead, we’re introducing 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. The packages are distributed with a name clearly indicating their experimental status, like ```@aws-cdk-experiments/aws-xxx```\n, and are versioned with a version number 0.x to clearly indicate their pre-release status. Only after the new package has matured and has been put through its paces in several real-world scenarios will we include it into ```aws-cdk-lib```as a stable module.\n\nThis 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\nYou can read about our thinking on some of the options we considered to make this transition in the [GitHub repo](https://github.com/aws/aws-cdk-rfcs/blob/master/text/0249-v2-experiments.md).\n\nFor the Developer Preview release, the higher-level constructs (L2s) for experimental packages are removed from ```aws-cdk-lib```, but they aren’t available separately yet. The [AWS CloudFormation](https://aws.amazon.com/cn/cloudformation/?trk=cndc-detail) (L1) classes are included as usual. We know that a lot of work has been put into building and maintaining the experimental L2s, by both the community and the core team, and we’re working hard to get them released separately soon.\n\n#### **Deprecated APIs are removed**\n\nSince releasing CDK v1, we have fixed a number of bugs and defects in our code. As part of this effort, we have deprecated a number of symbols—classes, properties, and methods—and have provided better replacements for them.\n\nAs part of our cleanup efforts for CDK v2, these deprecated symbols are removed entirely. If you’re still using any of the [deprecated APIs](https://github.com/aws/aws-cdk/blob/master/DEPRECATED_APIs.md), you have to update your [AWS CDK](https://aws.amazon.com/cn/cdk/?trk=cndc-detail) applications and libraries to switch to the replacement versions.\n\n[AWS CDK](https://aws.amazon.com/cn/cdk/?trk=cndc-detail) already used standard language facilities for reporting deprecated APIs, so you may have already noticed APIs getting deprecated as you were working with the code: identifiers have a strike-through decoration, or the deprecations have shown up in your IDE’s list of warnings. If so, great! You don’t need to do anything about this when migrating to v2.\n\nIf you haven’t touched your code in a while or are using Python (which doesn’t have deprecation reporting in the IDE), we will soon release an update to the [AWS CDK](https://aws.amazon.com/cn/cdk/?trk=cndc-detail) CLI that warns you about the usage of deprecated APIs during the ```cdk synth``` operation, so you can confirm that you’re not using any deprecated APIs before upgrading.\n\n#### **Feature flags: New behavior becomes the default**\n\nIn [AWS CDK](https://aws.amazon.com/cn/cdk/?trk=cndc-detail) v1, we introduced the concept of [feature flags](https://docs.aws.amazon.com/cdk/latest/guide/featureflags.html). This allowed us to ship bug fixes and improvements to the [AWS CDK](https://aws.amazon.com/cn/cdk/?trk=cndc-detail) without changing the behavior of your [AWS CDK](https://aws.amazon.com/cn/cdk/?trk=cndc-detail) application in incompatible ways. This allowed new [AWS CDK](https://aws.amazon.com/cn/cdk/?trk=cndc-detail) apps to get our updated behavior, while existing [AWS CDK](https://aws.amazon.com/cn/cdk/?trk=cndc-detail) apps can opt in to the feature flags as needed. The complete list of feature flags is documented [on GitHub](https://github.com/aws/aws-cdk/blob/master/packages/@aws-cdk/cx-api/lib/features.ts).\n\nIn [AWS CDK](https://aws.amazon.com/cn/cdk/?trk=cndc-detail) v2, new and existing apps that are migrated to v2 have all the feature flags enabled. In most cases, it’s not possible to revert any of the features to their old behavior, but in cases where it’s impossible to upgrade to v2 without causing interruption or downtime to your AWS application, we have made it possible to revert to the old behavior. If you’re migrating your [AWS CDK](https://aws.amazon.com/cn/cdk/?trk=cndc-detail) application from v1 to v2, we recommend that you run the ```cdk diff``` command and see how this may impact your application.\n\n#### **New bootstrapping resources become the default**\n\nIn the course of building support for continuous deployments of [AWS CDK](https://aws.amazon.com/cn/cdk/?trk=cndc-detail) applications to multiple AWS accounts, we changed the bootstrap resources that [AWS CDK](https://aws.amazon.com/cn/cdk/?trk=cndc-detail) creates for you.\n\nIn v1, creating the new bootstrap resources and using them was optional and enabled via a feature flag in ```cdk.json\\n(namely @aws-cdk/core:newStyleStackSynthesis```).\n\nIn v2, the [new bootstrapping resources](https://docs.aws.amazon.com/cdk/latest/guide/bootstrapping.html#bootstrapping-templates) have become the default, and your stack templates will change slightly to take advantage of those new resources. The biggest changes are:\n\n- Assets no longer take up parameters in your CloudFormation template, so you can use as many assets as you want without being limited by the 50 parameter limit of CloudFormation templates.\n\n- Cross-account deployments are supported out of the box, so you can use credentials from one AWS account to assume a role and deploy an [AWS CDK](https://aws.amazon.com/cn/cdk/?trk=cndc-detail) app into another account (assuming the right trust relationship has been set up between the accounts).\n- The bootstrap resources now also contain an [Amazon Elastic Container Registry](https://aws.amazon.com/ecr/) (Amazon ECR) repository in which all asset images are pushed. This is opposed to them being pushed to a separate Amazon ECR repository per asset.\n\nBecause all [AWS CDK](https://aws.amazon.com/cn/cdk/?trk=cndc-detail) applications written with [AWS CDK](https://aws.amazon.com/cn/cdk/?trk=cndc-detail) v2 expect the new bootstrap resources to be available, if you haven’t already manually opted into the new bootstrap resources via the feature flag we mentioned, you have to re-bootstrap all your AWS accounts and Regions once by running ```cdk bootstrap``` with the v2 [AWS CDK](https://aws.amazon.com/cn/cdk/?trk=cndc-detail) CLI.\n\n#### **Migration from v1 to v2**\n\nIf you have an existing [AWS CDK](https://aws.amazon.com/cn/cdk/?trk=cndc-detail) application that you want to upgrade to v2, the migration process for your code is as follows:\n\n1. Update your package dependencies to depend on the new ```aws-cdk-lib``` and ```constructs``` libraries.\n2. Run your package manager to download the new dependencies.\n3. Change your ```import``` statements (the core [AWS CDK](https://aws.amazon.com/cn/cdk/?trk=cndc-detail) classes have moved to the root [AWS CDK](https://aws.amazon.com/cn/cdk/?trk=cndc-detail) namespace in all languages, and ```Construct``` has moved to a different namespace).\n4. Remove all feature flags from the context object in cdk.json.\n5. After you update your application code, install version 2 of the [AWS CDK](https://aws.amazon.com/cn/cdk/?trk=cndc-detail) CLI by running ```npm install -g aws-cdk@2.0.0-rc.1```.\n6. Re-bootstrap your application environments by running ```cdk bootstrap```.\n\nApart from the core classes, we have kept the AWS Construct Library names the same in most cases, so you shouldn’t expect this to cause disruptive resource replacements in your stacks. The following sections contain a description of what the changes look like for every language.\n\n##### **Typescript**\n\nFor [AWS CDK](https://aws.amazon.com/cn/cdk/?trk=cndc-detail) applications written in TypeScript, update your ```package.json``` file to look like the following code (don’t forget to move ```@aws-cdk/assert``` to the new version as well):\n\n```\\n{\\n \\"dependencies\\": {\\n \\"aws-cdk-lib\\": \\"^2.0.0-rc.1\\",\\n \\"@aws-cdk/assert\\": \\"^2.0.0-rc.1\\",\\n \\"constructs\\": \\"^10.0.0\\"\\n }\\n}\\n```\n\nFor construct libraries written in TypeScript, the```package.json``` should look slightly different. You need to establish the lowest version of ```aws-cdk-lib``` you require for your application (let’s say that is```\\n2.0.0-rc.1```) and then update your```package.json``` to look like the following code:\n\n```\\n{\\n \\"peerDependencies\\": {\\n \\"aws-cdk-lib\\": \\"^2.0.0-rc.1\\",\\n \\"constructs\\": \\"^10.0.0\\"\\n },\\n \\"devDependencies\\": {\\n \\"aws-cdk-lib\\": \\"2.0.0-rc.1\\", // <-- note: no ^ to make sure we test against the minimum version\\n \\"@aws-cdk/assert\\": ^2.0.0-rc1.1\\",\\n \\"constructs\\": \\"^10.0.0\\",\\n \\"typescript\\": \\"~3.9.0\\"\\n } \\n}\\n```\n\nInstall the new dependencies by running the following:\n\n```\\nBash\\nnpm install\\n# or\\nyarn install\\n```\n\nChange your imports to look like the following:\n\n```\\nimport { Construct } from 'constructs';\\nimport { App, Stack, aws_s3 as s3 } from 'aws-cdk-lib';\\n```\n\n##### **Python**\n\nFor [AWS CDK](https://aws.amazon.com/cn/cdk/?trk=cndc-detail) applications written in Python, update your setup.py to look like the following:\n\n```\\nPython\\ninstall_requires=[\\n \\"aws-cdk-lib>=2.0.0-rc1\\",\\n \\"constructs>=10.0.0\\",\\n # ...\\n]\\n```\n\n##### **Install the new dependencies:**\n\n```\\npip install -r requirements.txt\\n```\n\nRemember to uninstall any other versions of [AWS CDK](https://aws.amazon.com/cn/cdk/?trk=cndc-detail) via pip uninstall.\n\n##### **Change your imports to look like the following:**\n\n```\\nimport constructs\\nimport aws_cdk as cdk\\nfrom aws_cdk import aws_s3 as s3\\n```\n\n##### **Reference the classes as follows:**\n\n```\\nclass MyConstruct(constructs.Construct):\\n # ...\\n\\nclass MyStack(cdk.Stack):\\n # ...\\n\\ns3.Bucket(...)\\n```\n\n##### **Java**\n\nIn the ```pom.xml``` file, remove all```software.amazon.awscdk```\n dependencies and replace them with the following:\n\n```\\n<dependency>\\n <groupId>software.amazon.awscdk</groupId>\\n <artifactId>aws-cdk-lib</artifactId>\\n <version>2.0.0-rc.1</version>\\n</dependency>\\n<dependency>\\n <groupId>software.constructs</groupId>\\n <artifactId>constructs</artifactId>\\n <version>10.0.0</version>\\n</dependency>\\n```\n\nInstall the new dependencies:\n\n```\\nmvn package\\n```\n\nChange your imports to look like the following:\n\n```\\nimport software.constructs.Construct;\\nimport software.amazon.awscdk.Stack;\\nimport software.amazon.awscdk.StackProps;\\nimport software.amazon.awscdk.App;\\nimport software.amazon.awscdk.services.s3.Bucket;\\n```\n\n#### **.NET**\nIn the ```.csproj``` file, remove all ```Amazon.CDK.*``` references and replace them with the following:\n\n```\\n<PackageReference Include=\\"Amazon.CDK.Lib\\" Version=\\"2.0.0-rc.1\\" />\\n<PackageReference Include=\\"Constructs\\" Version=\\"10.0.0\\" />\\n```\n\nInstall the new dependencies:\n\n```\\ndotnet restore\\n```\n\nChange your imports to look like the following:\n\n```\\nusing Constructs;\\nusing Amazon.CDK;\\nusing Amazon.CDK.AWS.S3;\\n```\n\n#### **Changes to cdk.json**\n\nThese changes apply to all languages.\n\nRemove all feature flags from ```cdk.json```, because all feature flags created for v1 are now enabled by default. Only three of those feature flags can be disabled to revert back to the v1 behavior:\n\n- If your application uses multiple [Amazon API Gateway](https://aws.amazon.com/cn/api-gateway/?trk=cndc-detail) API keys and associates them to usage plans (only for the module ```@aws-cdk/aws-apigateway```), use @aws-cdk/aws-apigateway:usagePlanKeyOrderInsensitiveId.\n- If your application uses an Amazon Relational Database Service ([Amazon RDS](https://aws.amazon.com/cn/rds/?trk=cndc-detail)) DB instance or DB clusters, and explicitly specifies the identifier for these, use ```@aws-cdk/aws-rds:lowercaseDbIdentifier```.\n- If your application uses multiple stacks and if they refer to resources from one stack to the other, use the [AWS CloudFormation](https://aws.amazon.com/cn/cloudformation/?trk=cndc-detail) export functionality:```@awscdk/core:stackRelativeExports```.\n\nYou can disable these feature flags in your cdk.json with the following code:\n\n```\\n{\\n \\"context\\": {\\n \\"@aws-cdk/aws-rds:lowercaseDbIdentifier\\": false,\\n \\"@aws-cdk/aws-apigateway:usagePlanKeyOrderInsensitiveId\\": false,\\n \\"@aws-cdk/core:stackRelativeExports\\": false,\\n }\\n}\\n```\n\nUse the```cdk diff``` command to inspect changes to your templates to see if any of these flags need to be disabled.\n\n#### **Unexpected changes to synthesized infrastructure**\n\nWhen you run the ```cdk diff``` command to inspect changes that CDK will make, you may notice unexpected changes to your templates. These changes are the result of deprecated behavior being replaced by functionality that was previously hidden by feature flags.\n\nThese changes are probably not due to upgrading to v2, but due to upgrading from an older version of CDK. You will also see them when upgrading to the latest minor version in v1. If you are on an older ```1.x``` version, try upgrading to a recent 1.x version first, synthesize and deploy your application, and then proceed with the v2 upgrade.\n\nIf you run into a situation where you cannot deploy your stacks because of the difference between your v1 and v2-synthesized infrastructure, and it is not covered by one of the feature flags discussed in the previous section, please [let us know on GitHub](https://github.com/aws/aws-cdk/issues).\n\n#### **Summary**\n\nAlthough [AWS CDK](https://aws.amazon.com/cn/cdk/?trk=cndc-detail) v2 isn’t a major change in design, it makes managing package versions easier and allows you to update to newer versions of the [AWS CDK](https://aws.amazon.com/cn/cdk/?trk=cndc-detail) on a regular cadence. For more information, refer to the [v2 developer guide](https://docs.aws.amazon.com/cdk/latest/guide/work-with-cdk-v2.html) and the [https://docs.aws.amazon.com/cdk/api/v2/](v2 API reference). As always, we welcome bug reports, feature requests, and pull requests on the aws-cdk GitHub repository.\n\n<3 the AWS CDK team\\n\\nTAGS: [aws-cdk](https://aws.amazon.com/blogs/developer/tag/aws-cdk/), CDK, [Open Source](https://aws.amazon.com/blogs/developer/tag/open-source/)","render":"<p>The <a href=\\"https://aws.amazon.com/cdk/\\" target=\\"_blank\\">AWS Cloud Development Kit</a> ([AWS CDK](https://aws.amazon.com/cn/cdk/?trk=cndc-detail)) v2 is now available for Developer Preview in TypeScript, Python, Java, C#, and Go. The [AWS CDK](https://aws.amazon.com/cn/cdk/?trk=cndc-detail) is an open-source software development framework to model and provision your cloud application resources using familiar programming languages. With the [AWS CDK](https://aws.amazon.com/cn/cdk/?trk=cndc-detail), 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](https://aws.amazon.com/cn/cdk/?trk=cndc-detail) 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 July of 2019, <a href=\\"https://aws.amazon.com/blogs/aws/aws-cloud-development-kit-cdk-typescript-and-python-are-now-generally-available/\\" target=\\"_blank\\">we announced the general availability of AWS CDK v1</a> for Typescript and Python. Since that time, we have released support for additional languages in Java and C#, and we released language bindings for <a href=\\"https://aws.amazon.com/blogs/developer/getting-started-with-the-aws-cloud-development-kit-and-go/\\" target=\\"_blank\\">Go in Developer Preview</a>. We’re now announcing a preview release of v2, which introduces a couple of changes that make it easier for you to consume the [AWS CDK](https://aws.amazon.com/cn/cdk/?trk=cndc-detail) and stay up to date with new versions as we evolve it going forwards.</p>\\n<p>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. You may notice some minor changes to resources, but nothing that requires a resource replacement.</p>\n<p>This post walks you through the changes between AWS CDK v1 and v2.</p>\n<h4><a id=\\"The_AWS_Construct_Library_now_comes_in_a_single_package_8\\"></a><strong>The AWS Construct Library now comes in a single package</strong></h4>\\n<p>In AWS CDK v1, we were very careful to partition 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, 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 npm install or pip install another package. Additionally, if you were using NPM, it was very important that all these packages were the exact same version, otherwise NPM might install multiple copies of some of the libraries, which then wouldn’t interoperate properly. We have heard feedback from customers telling us how hard it was to manage the dependency on AWS CDK correctly.</p>\n<p>Starting in v2, we have consolidated all of the AWS Construct Library into a single package, called <code>aws-cdk-lib</code>. You get access to all the [AWS CDK](https://aws.amazon.com/cn/cdk/?trk=cndc-detail) 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 extracted the constructs programming model into a separate library, called <code>constructs</code><br />\\n. This is the basis for a bigger ecosystem of interoperable construct libraries, and is already being used by sister projects like <a href=\\"https://cdk8s.io/\\" target=\\"_blank\\">cdk8s</a> and <a href=\\"https://github.com/hashicorp/terraform-cdk\\" target=\\"_blank\\">terraform-cdk</a>.</p>\\n<p>For more information about the design choices for v2, see the <a href=\\"https://github.com/aws/aws-cdk-rfcs/blob/master/text/0079-cdk-2.0.md\\" target=\\"_blank\\">RFC in our GitHub repo</a>.</p>\\n<h4><a id=\\"Removal_of_the_construct_compatibility_layer_21\\"></a><strong>Removal of the construct compatibility layer</strong></h4>\\n<p>As part of our effort to broaden the applicability of the AWS CDK programming model to other domains such as Kubernetes, we extracted the base <code>Construct</code> class (and a few related types) from the [AWS CDK](https://aws.amazon.com/cn/cdk/?trk=cndc-detail) to an independent library called <a href=\\"https://github.com/aws/constructs\\" target=\\"_blank\\">constructs</a>.</p>\\n<p>If you’re defining your own construct or using any of the related APIs, you now have to make code changes to use the <code>constructs</code> library.</p>\\n<p>After you declare this library as a new dependency, in most cases you just need to adjust your import statements to use the new classes. Most of the class and method names have been retained, and should make this easy to migrate.</p>\n<p>If you’re using advanced AWS CDK features such as hooking into the <a href=\\"https://docs.aws.amazon.com/cdk/latest/guide/apps.html#lifecycle\\" target=\\"_blank\\">AWS CDK app lifecycle</a>, more changes are required to achieve this. All of the details are available in the relevant <a href=\\"https://github.com/aws/aws-cdk-rfcs/blob/master/text/0192-remove-constructs-compat.md#release-notes\\" target=\\"_blank\\">release notes</a>.</p>\\n<h4><a id=\\"New_lifecycle_for_experimental_APIs_31\\"></a><strong>New lifecycle for experimental APIs</strong></h4>\\n<p>We’re also introducing changes to how we handle experimental classes, methods, and properties starting in v2.</p>\n<p>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 package, or they simply chose to deploy production stacks with the experiments due to their perceived stability and general level of usefulness.</p>\n<p>In AWS CDK v2, we no longer make intentional breaking changes to any APIs in minor version releases. Instead, we’re introducing 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. The packages are distributed with a name clearly indicating their experimental status, like <code>@aws-cdk-experiments/aws-xxx</code><br />\\n, and are versioned with a version number 0.x to clearly indicate their pre-release status. Only after the new package 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 a stable module.</p>\\n<p>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<p>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\\">GitHub repo</a>.</p>\\n<p>For the Developer Preview release, the higher-level constructs (L2s) for experimental packages are removed from <code>aws-cdk-lib</code>, but they aren’t available separately yet. The [AWS CloudFormation](https://aws.amazon.com/cn/cloudformation/?trk=cndc-detail) (L1) classes are included as usual. We know that a lot of work has been put into building and maintaining the experimental L2s, by both the community and the core team, and we’re working hard to get them released separately soon.</p>\\n<h4><a id=\\"Deprecated_APIs_are_removed_46\\"></a><strong>Deprecated APIs are removed</strong></h4>\\n<p>Since releasing CDK v1, we have fixed a number of bugs and defects in our code. As part of this effort, we have deprecated a number of symbols—classes, properties, and methods—and have provided better replacements for them.</p>\n<p>As part of our cleanup efforts for CDK v2, these deprecated symbols are removed entirely. If you’re still using any of the <a href=\\"https://github.com/aws/aws-cdk/blob/master/DEPRECATED_APIs.md\\" target=\\"_blank\\">deprecated APIs</a>, you have to update your [AWS CDK](https://aws.amazon.com/cn/cdk/?trk=cndc-detail) applications and libraries to switch to the replacement versions.</p>\\n<p>AWS CDK already used standard language facilities for reporting deprecated APIs, so you may have already noticed APIs getting deprecated as you were working with the code: identifiers have a strike-through decoration, or the deprecations have shown up in your IDE’s list of warnings. If so, great! You don’t need to do anything about this when migrating to v2.</p>\n<p>If you haven’t touched your code in a while or are using Python (which doesn’t have deprecation reporting in the IDE), we will soon release an update to the AWS CDK CLI that warns you about the usage of deprecated APIs during the <code>cdk synth</code> operation, so you can confirm that you’re not using any deprecated APIs before upgrading.</p>\\n<h4><a id=\\"Feature_flags_New_behavior_becomes_the_default_56\\"></a><strong>Feature flags: New behavior becomes the default</strong></h4>\\n<p>In AWS CDK v1, we introduced the concept of <a href=\\"https://docs.aws.amazon.com/cdk/latest/guide/featureflags.html\\" target=\\"_blank\\">feature flags</a>. This allowed us to ship bug fixes and improvements to the [AWS CDK](https://aws.amazon.com/cn/cdk/?trk=cndc-detail) without changing the behavior of your [AWS CDK](https://aws.amazon.com/cn/cdk/?trk=cndc-detail) application in incompatible ways. This allowed new [AWS CDK](https://aws.amazon.com/cn/cdk/?trk=cndc-detail) apps to get our updated behavior, while existing [AWS CDK](https://aws.amazon.com/cn/cdk/?trk=cndc-detail) apps can opt in to the feature flags as needed. The complete list of feature flags is documented <a href=\\"https://github.com/aws/aws-cdk/blob/master/packages/@aws-cdk/cx-api/lib/features.ts\\" target=\\"_blank\\">on GitHub</a>.</p>\\n<p>In AWS CDK v2, new and existing apps that are migrated to v2 have all the feature flags enabled. In most cases, it’s not possible to revert any of the features to their old behavior, but in cases where it’s impossible to upgrade to v2 without causing interruption or downtime to your AWS application, we have made it possible to revert to the old behavior. If you’re migrating your AWS CDK application from v1 to v2, we recommend that you run the <code>cdk diff</code> command and see how this may impact your application.</p>\\n<h4><a id=\\"New_bootstrapping_resources_become_the_default_62\\"></a><strong>New bootstrapping resources become the default</strong></h4>\\n<p>In the course of building support for continuous deployments of AWS CDK applications to multiple AWS accounts, we changed the bootstrap resources that AWS CDK creates for you.</p>\n<p>In v1, creating the new bootstrap resources and using them was optional and enabled via a feature flag in <code>cdk.json (namely @aws-cdk/core:newStyleStackSynthesis</code>).</p>\\n<p>In v2, the <a href=\\"https://docs.aws.amazon.com/cdk/latest/guide/bootstrapping.html#bootstrapping-templates\\" target=\\"_blank\\">new bootstrapping resources</a> have become the default, and your stack templates will change slightly to take advantage of those new resources. The biggest changes are:</p>\\n<ul>\\n<li>\\n<p>Assets no longer take up parameters in your CloudFormation template, so you can use as many assets as you want without being limited by the 50 parameter limit of CloudFormation templates.</p>\n</li>\\n<li>\\n<p>Cross-account deployments are supported out of the box, so you can use credentials from one AWS account to assume a role and deploy an AWS CDK app into another account (assuming the right trust relationship has been set up between the accounts).</p>\n</li>\\n<li>\\n<p>The bootstrap resources now also contain an <a href=\\"https://aws.amazon.com/ecr/\\" target=\\"_blank\\">Amazon Elastic Container Registry</a> (Amazon ECR) repository in which all asset images are pushed. This is opposed to them being pushed to a separate Amazon ECR repository per asset.</p>\\n</li>\n</ul>\\n<p>Because all AWS CDK applications written with AWS CDK v2 expect the new bootstrap resources to be available, if you haven’t already manually opted into the new bootstrap resources via the feature flag we mentioned, you have to re-bootstrap all your AWS accounts and Regions once by running <code>cdk bootstrap</code> with the v2 [AWS CDK](https://aws.amazon.com/cn/cdk/?trk=cndc-detail) CLI.</p>\\n<h4><a id=\\"Migration_from_v1_to_v2_78\\"></a><strong>Migration from v1 to v2</strong></h4>\\n<p>If you have an existing AWS CDK application that you want to upgrade to v2, the migration process for your code is as follows:</p>\n<ol>\\n<li>Update your package dependencies to depend on the new <code>aws-cdk-lib</code> and <code>constructs</code> libraries.</li>\\n<li>Run your package manager to download the new dependencies.</li>\n<li>Change your <code>import</code> statements (the core [AWS CDK](https://aws.amazon.com/cn/cdk/?trk=cndc-detail) classes have moved to the root [AWS CDK](https://aws.amazon.com/cn/cdk/?trk=cndc-detail) namespace in all languages, and <code>Construct</code> has moved to a different namespace).</li>\\n<li>Remove all feature flags from the context object in cdk.json.</li>\n<li>After you update your application code, install version 2 of the AWS CDK CLI by running <code>npm install -g aws-cdk@2.0.0-rc.1</code>.</li>\\n<li>Re-bootstrap your application environments by running <code>cdk bootstrap</code>.</li>\\n</ol>\n<p>Apart from the core classes, we have kept the AWS Construct Library names the same in most cases, so you shouldn’t expect this to cause disruptive resource replacements in your stacks. The following sections contain a description of what the changes look like for every language.</p>\n<h5><a id=\\"Typescript_91\\"></a><strong>Typescript</strong></h5>\\n<p>For AWS CDK applications written in TypeScript, update your <code>package.json</code> file to look like the following code (don’t forget to move <code>@aws-cdk/assert</code> to the new version as well):</p>\\n<pre><code class=\\"lang-\\">{\\n &quot;dependencies&quot;: {\\n &quot;aws-cdk-lib&quot;: &quot;^2.0.0-rc.1&quot;,\\n &quot;@aws-cdk/assert&quot;: &quot;^2.0.0-rc.1&quot;,\\n &quot;constructs&quot;: &quot;^10.0.0&quot;\\n }\\n}\\n</code></pre>\\n<p>For construct libraries written in TypeScript, the<code>package.json</code> should look slightly different. You need to establish the lowest version of <code>aws-cdk-lib</code> you require for your application (let’s say that is<code> 2.0.0-rc.1</code>) and then update your<code>package.json</code> to look like the following code:</p>\\n<pre><code class=\\"lang-\\">{\\n &quot;peerDependencies&quot;: {\\n &quot;aws-cdk-lib&quot;: &quot;^2.0.0-rc.1&quot;,\\n &quot;constructs&quot;: &quot;^10.0.0&quot;\\n },\\n &quot;devDependencies&quot;: {\\n &quot;aws-cdk-lib&quot;: &quot;2.0.0-rc.1&quot;, // &lt;-- note: no ^ to make sure we test against the minimum version\\n &quot;@aws-cdk/assert&quot;: ^2.0.0-rc1.1&quot;,\\n &quot;constructs&quot;: &quot;^10.0.0&quot;,\\n &quot;typescript&quot;: &quot;~3.9.0&quot;\\n } \\n}\\n</code></pre>\\n<p>Install the new dependencies by running the following:</p>\n<pre><code class=\\"lang-\\">Bash\\nnpm install\\n# or\\nyarn install\\n</code></pre>\\n<p>Change your imports to look like the following:</p>\n<pre><code class=\\"lang-\\">import { Construct } from 'constructs';\\nimport { App, Stack, aws_s3 as s3 } from 'aws-cdk-lib';\\n</code></pre>\\n<h5><a id=\\"Python_139\\"></a><strong>Python</strong></h5>\\n<p>For AWS CDK applications written in Python, update your setup.py to look like the following:</p>\n<pre><code class=\\"lang-\\">Python\\ninstall_requires=[\\n &quot;aws-cdk-lib&gt;=2.0.0-rc1&quot;,\\n &quot;constructs&gt;=10.0.0&quot;,\\n # ...\\n]\\n</code></pre>\\n<h5><a id=\\"Install_the_new_dependencies_152\\"></a><strong>Install the new dependencies:</strong></h5>\\n<pre><code class=\\"lang-\\">pip install -r requirements.txt\\n</code></pre>\\n<p>Remember to uninstall any other versions of AWS CDK via pip uninstall.</p>\n<h5><a id=\\"Change_your_imports_to_look_like_the_following_160\\"></a><strong>Change your imports to look like the following:</strong></h5>\\n<pre><code class=\\"lang-\\">import constructs\\nimport aws_cdk as cdk\\nfrom aws_cdk import aws_s3 as s3\\n</code></pre>\\n<h5><a id=\\"Reference_the_classes_as_follows_168\\"></a><strong>Reference the classes as follows:</strong></h5>\\n<pre><code class=\\"lang-\\">class MyConstruct(constructs.Construct):\\n # ...\\n\\nclass MyStack(cdk.Stack):\\n # ...\\n\\ns3.Bucket(...)\\n</code></pre>\\n<h5><a id=\\"Java_180\\"></a><strong>Java</strong></h5>\\n<p>In the <code>pom.xml</code> file, remove all<code>software.amazon.awscdk</code><br />\\ndependencies and replace them with the following:</p>\n<pre><code class=\\"lang-\\">&lt;dependency&gt;\\n &lt;groupId&gt;software.amazon.awscdk&lt;/groupId&gt;\\n &lt;artifactId&gt;aws-cdk-lib&lt;/artifactId&gt;\\n &lt;version&gt;2.0.0-rc.1&lt;/version&gt;\\n&lt;/dependency&gt;\\n&lt;dependency&gt;\\n &lt;groupId&gt;software.constructs&lt;/groupId&gt;\\n &lt;artifactId&gt;constructs&lt;/artifactId&gt;\\n &lt;version&gt;10.0.0&lt;/version&gt;\\n&lt;/dependency&gt;\\n</code></pre>\\n<p>Install the new dependencies:</p>\n<pre><code class=\\"lang-\\">mvn package\\n</code></pre>\\n<p>Change your imports to look like the following:</p>\n<pre><code class=\\"lang-\\">import software.constructs.Construct;\\nimport software.amazon.awscdk.Stack;\\nimport software.amazon.awscdk.StackProps;\\nimport software.amazon.awscdk.App;\\nimport software.amazon.awscdk.services.s3.Bucket;\\n</code></pre>\\n<h4><a id=\\"NET_214\\"></a><strong>.NET</strong></h4>\\n<p>In the <code>.csproj</code> file, remove all <code>Amazon.CDK.*</code> references and replace them with the following:</p>\\n<pre><code class=\\"lang-\\">&lt;PackageReference Include=&quot;Amazon.CDK.Lib&quot; Version=&quot;2.0.0-rc.1&quot; /&gt;\\n&lt;PackageReference Include=&quot;Constructs&quot; Version=&quot;10.0.0&quot; /&gt;\\n</code></pre>\\n<p>Install the new dependencies:</p>\n<pre><code class=\\"lang-\\">dotnet restore\\n</code></pre>\\n<p>Change your imports to look like the following:</p>\n<pre><code class=\\"lang-\\">using Constructs;\\nusing Amazon.CDK;\\nusing Amazon.CDK.AWS.S3;\\n</code></pre>\\n<h4><a id=\\"Changes_to_cdkjson_236\\"></a><strong>Changes to cdk.json</strong></h4>\\n<p>These changes apply to all languages.</p>\n<p>Remove all feature flags from <code>cdk.json</code>, because all feature flags created for v1 are now enabled by default. Only three of those feature flags can be disabled to revert back to the v1 behavior:</p>\\n<ul>\\n<li>If your application uses multiple Amazon API Gateway API keys and associates them to usage plans (only for the module <code>@aws-cdk/aws-apigateway</code>), use @aws-cdk/aws-apigateway:usagePlanKeyOrderInsensitiveId.</li>\\n<li>If your application uses an Amazon Relational Database Service (Amazon RDS) DB instance or DB clusters, and explicitly specifies the identifier for these, use <code>@aws-cdk/aws-rds:lowercaseDbIdentifier</code>.</li>\\n<li>If your application uses multiple stacks and if they refer to resources from one stack to the other, use the AWS CloudFormation export functionality:<code>@awscdk/core:stackRelativeExports</code>.</li>\\n</ul>\n<p>You can disable these feature flags in your cdk.json with the following code:</p>\n<pre><code class=\\"lang-\\">{\\n &quot;context&quot;: {\\n &quot;@aws-cdk/aws-rds:lowercaseDbIdentifier&quot;: false,\\n &quot;@aws-cdk/aws-apigateway:usagePlanKeyOrderInsensitiveId&quot;: false,\\n &quot;@aws-cdk/core:stackRelativeExports&quot;: false,\\n }\\n}\\n</code></pre>\\n<p>Use the<code>cdk diff</code> command to inspect changes to your templates to see if any of these flags need to be disabled.</p>\\n<h4><a id=\\"Unexpected_changes_to_synthesized_infrastructure_260\\"></a><strong>Unexpected changes to synthesized infrastructure</strong></h4>\\n<p>When you run the <code>cdk diff</code> command to inspect changes that CDK will make, you may notice unexpected changes to your templates. These changes are the result of deprecated behavior being replaced by functionality that was previously hidden by feature flags.</p>\\n<p>These changes are probably not due to upgrading to v2, but due to upgrading from an older version of CDK. You will also see them when upgrading to the latest minor version in v1. If you are on an older <code>1.x</code> version, try upgrading to a recent 1.x version first, synthesize and deploy your application, and then proceed with the v2 upgrade.</p>\\n<p>If you run into a situation where you cannot deploy your stacks because of the difference between your v1 and v2-synthesized infrastructure, and it is not covered by one of the feature flags discussed in the previous section, please <a href=\\"https://github.com/aws/aws-cdk/issues\\" target=\\"_blank\\">let us know on GitHub</a>.</p>\\n<h4><a id=\\"Summary_268\\"></a><strong>Summary</strong></h4>\\n<p>Although AWS CDK v2 isn’t a major change in design, it makes managing package versions easier and allows you to update to newer versions of the AWS CDK on a regular cadence. For more information, refer to the <a href=\\"https://docs.aws.amazon.com/cdk/latest/guide/work-with-cdk-v2.html\\" target=\\"_blank\\">v2 developer guide</a> and the [https://docs.aws.amazon.com/cdk/api/v2/](v2 API reference). As always, we welcome bug reports, feature requests, and pull requests on the aws-cdk GitHub repository.</p>\\n<p>❤️ the AWS CDK team</p>\n<p>TAGS: <a href=\\"https://aws.amazon.com/blogs/developer/tag/aws-cdk/\\" target=\\"_blank\\">aws-cdk</a>, CDK, <a href=\\"https://aws.amazon.com/blogs/developer/tag/open-source/\\" target=\\"_blank\\">Open Source</a></p>\n"}