新的先决条件从 AWS CDK v2 开发者预览版升级从 AWS CDK v1 迁移到 v2 CDK 在部署之前测试已迁移的应用程序故障排除查找 v1 堆栈

从 AWS CDK v1 迁移到 v2 AWS CDK

的版本 2 AWS Cloud Development Kit (AWS CDK) 旨在让使用您首选的编程语言更轻松地将基础架构作为代码进行编写。本主题介绍的 v1 和 v2 之间的变化。 AWS CDK

提示

要识别使用 v1 部署的堆栈，请使用 aw scdk AWS CDK -v1-stack-finder 实用程序。

从 AWS CDK v1 到 CDK v2 的主要变化如下。

AWS CDK v2 将 Con AWS struct 库的稳定部分（包括核心库）整合到一个包中。aws-cdk-lib开发人员不再需要为他们使用的个别 AWS 服务安装额外的软件包。这种单包方法还意味着您不必同步各种CDK库包的版本。

L1 (CfnXXXX) 构造代表中可用资源的确切资源 AWS CloudFormation，始终被认为是稳定的，因此包含在中。aws-cdk-lib
实验模块不包括在内，我们仍在与社区合作开发新的 L2 或 L3 结构。aws-cdk-lib相反，它们是作为单独的软件包分发的。实验包以alpha后缀和语义版本号命名。语义版本号与它们兼容的 Construct L AWS ibrary 的第一个版本相匹配，还有一个alpha后缀。构造aws-cdk-lib在被指定为稳定版本后移入，从而允许主构造库遵守严格的语义版本控制。

稳定性是在服务级别指定的。例如，如果我们开始为 Amazon 创建一个或多个 L2 构造，而在撰写本文时 AppFlow，这些构造只有 L1 结构，则它们首先出现在名为的模块中。@aws-cdk/aws-appflow-alpha然后，aws-cdk-lib当我们认为新结构可以满足客户的基本需求时，它们就会移动。

一旦一个模块被指定为稳定模块并入其中aws-cdk-lib，就会使用下一个项目符号中描述APIs的 “BetAN” 惯例添加新的模块。

每个实验模块的每个版本都会随之发布一个新版本 AWS CDK。但是，在大多数情况下，它们不需要保持同步。你可以随时升级aws-cdk-lib或实验模块。唯一的例外是，当两个或多个相关的实验模块相互依赖时，它们必须是相同的版本。
对于正在添加新功能的稳定模块，新模块APIs（无论是全新的构造还是现有构造上的新方法或属性）在工作进行时会收到一个Beta1后缀。（当需要进行重大更改时 Beta2Beta3，其次是、等。）当指定为稳定版本时，会添加API不带后缀API的版本。然后，除最新方法（无论是测试版还是最终版）之外的所有方法都将被弃用。

例如，如果我们在构造中添加一个新方法grantPower()，它最初会显示为grantPowerBeta1()。如果需要进行重大更改（例如，新的必需参数或属性），则将命名该方法的下一个版本grantPowerBeta2()，依此类推。当工作完成并最终确定后，将添加该方法grantPower()（不带后缀），并弃用 BetAN 方法。API

在下一个主要版本 (3.0) 发布之前，所有测试版都将APIs保留在 Construct 库中，并且它们的签名不会改变。如果你使用它们，你会看到弃用警告，因此你应该尽早转到最终版本。API但是，任何未来的 AWS CDK 2.x 版本都不会破坏你的应用程序。
该Construct类已与相关类型一起从中提取 AWS CDK 到单独的库中。这样做是为了支持将构造编程模型应用于其他领域的努力。如果您正在编写自己的构造或使用 relatedAPIs，则必须将该constructs模块声明为依赖项，并对导入进行细微的更改。如果您使用的是高级功能，例如连接到CDK应用程序生命周期，则可能需要进行更多更改。有关全部详细信息，请参阅RFC。
AWS CDK v1.x 及其构造库中已弃用的属性、方法和类型已从 v2 中完全删除。CDK API在大多数支持的语言中，它们APIs会在 v1.x 下生成警告，因此您可能已经迁移到替代语言。APIsCDKv1.x APIs中已弃用的完整列表可在上找到。 GitHub
在 AWS CDK v1.x 中受功能标志限制的行为在 v2 中默认处于CDK启用状态。不再需要早期的功能标志，而且在大多数情况下也不支持这些标志。在非常特殊的情况下，还有一些可以让你恢复到 CDK v1 的行为。有关更多信息，请参阅更新功能标志。
在 CDK v2 中，部署到的环境必须使用现代引导堆栈进行引导。不再支持旧版引导堆栈（v1 下的默认堆栈）。CDK此外，v2 还需要新版本的现代堆栈。要升级现有环境，请重新启动它们。无需再设置任何功能标志或环境变量即可使用现代 bootstrap 堆栈。

重要

现代引导模板可以有效地向--trust列表中的任何 AWS 账户授--cloudformation-execution-policies予隐含的权限。默认情况下，这会扩展对引导账户中任何资源的读写权限。请务必使用您熟悉的策略和可信帐户来配置引导堆栈。

新的先决条件

AWS CDK v2 的大多数要求与 v1.x 的要求相同。 AWS CDK 此处列出了其他要求。

对于 TypeScript 开发人员，需要 TypeScript 3.8 或更高版本。
需要使用新版本的CDK工具包才能与 CDK v2 配合使用。现在 CDK v2 已正式上线，因此安装工具包时，v2 是默认版本。CDK它与 CDK v1 项目向后兼容，因此除非要创建 v1 项目，否则无需继续安装早期版本。CDK要升级，请发出npm install -g aws-cdk。

从 AWS CDK v2 开发者预览版升级

如果您使用的是 CDK v2 开发者预览版，则您的项目依赖于的发布候选版本 AWS CDK，例如2.0.0-rc1。将它们更新为2.0.0，然后更新项目中安装的模块。

更新依赖项后，发出 CDK Toolkit 更新npm update -g aws-cdk到发布版本的命令。

从 AWS CDK v1 迁移到 v2 CDK

要将您的应用程序迁移到 AWS CDK v2，请先更新中的功能标志。cdk.json然后，根据需要更新应用程序的依赖关系和导入，以适应其编写的编程语言。

更新到最近的 v1

我们看到许多客户一步从旧版本的 AWS CDK v1 升级到最新版本的 v2。虽然做到这一点当然是可能的，但你既要在多年的变化中进行升级（不幸的是，这些变更可能不是所有人都进行了与今天相同数量的演化测试），也要跨具有新默认值和不同代码组织的版本进行升级。

为了获得最安全的升级体验并更轻松地诊断任何意外更改的来源，我们建议您将这两个步骤分开：首先升级到最新的 v1 版本，然后再切换到 v2。

更新功能标志

cdk.json如果存在以下 v1 功能标志，请将其删除，因为默认情况下，这些标志在 AWS CDK v2 中均处于活动状态。如果它们的旧效果对您的基础架构很重要，则需要对源代码进行更改。有关更多信息， GitHub请参阅上的旗帜列表。

@aws-cdk/core:enableStackNameDuplicates
aws-cdk:enableDiffNoFail
@aws-cdk/aws-ecr-assets:dockerIgnoreSupport
@aws-cdk/aws-secretsmanager:parseOwnedSecretName
@aws-cdk/aws-kms:defaultKeyPolicies
@aws-cdk/aws-s3:grantWriteWithoutAcl
@aws-cdk/aws-efs:defaultEncryptionAtRest

可以将少量 v1 功能标志设置为false以恢复到特定的 AWS CDK v1 行为；有关完整参考，请参阅恢复到 v1 行为或上的 GitHub 列表。

对于这两种类型的标志，请使用cdk diff命令检查对合成模板的更改，以查看对其中任何一个标志的更改是否会影响您的基础架构。

CDK工具包兼容性

CDKv2 需要工具包的 v2 或更高版本。CDK此版本与 v1 应用程序向后兼容。CDK因此，无论项目使用 v1 还是 v2，您都可以在所有 AWS CDK 项目中使用一个全球安装的 CDK Toolkit 版本。一个例外是 CDK Toolkit v2 仅创建 CDK v2 项目。

如果您需要同时创建 v1 和 v2 CDK 项目，请不要全局安装 CDK Toolkit v 2。（如果您已经安装了它，请将其删除:npm remove -g aws-cdk.）要调用CDK工具包，请npx根据需要使用运行CDK工具包的 v1 或 v2。


npx aws-cdk@1.x init app --language typescript
npx aws-cdk@2.x init app --language typescript

提示

设置命令行别名，以便您可以使用cdk和cdk1命令调用所需版本的 CDK Toolkit。

更新依赖关系和导入

更新应用程序的依赖关系，然后安装新的软件包。最后，更新代码中的导入。

TypeScript

应用程序

对于CDK应用程序，请按package.json如下方式进行更新。移除对 v1 风格的单个稳定模块的依赖，并建立应用程序aws-cdk-lib所需的最低版本（此处为 2.0.0）。

实验构造在单独的、独立版本化的包中提供，其名称以结尾alpha并带有 alpha 版本号。alpha 版本号对应于aws-cdk-lib与之兼容的第一个版本。在这里，我们已固定aws-codestar到 v2.0.0-alpha.1。


{
  "dependencies": {
    "aws-cdk-lib": "^2.0.0",
    "@aws-cdk/aws-codestar-alpha": "2.0.0-alpha.1",
    "constructs": "^10.0.0"
  }
}

构造图书馆

对于构造库，请为应用程序建立aws-cdk-lib所需的最低版本（此处为 2.0.0），然后按如下方式进行更新package.json。

请注意，这既aws-cdk-lib显示为对等依赖关系，也显示为开发依赖关系。


{
  "peerDependencies": {
    "aws-cdk-lib": "^2.0.0",
    "constructs": "^10.0.0"
  },
  "devDependencies": {
    "aws-cdk-lib": "^2.0.0",
    "constructs": "^10.0.0",
    "typescript": "~3.9.0"
  }
}

注意

在发布兼容 v2 的库时，你应该对库的版本号进行主要版本提升，因为这对库使用者来说是一个重大变化。不可能使用单个库同时支持 CDK v1 和 v2。要继续为仍在使用 v1 的客户提供支持，您可以并行维护早期版本，或者为 v2 创建新软件包。

您想继续支持 AWS CDK v1 客户多长时间由您决定。你可以从 CDK v1 本身的生命周期中汲取灵感，该生命周期于 2022 年 6 月 1 日进入维护阶段，并将于 2023 年 6 月 1 end-of-life 日到期。有关完整详细信息，请参阅AWS CDK 维护政策。

既有库又有应用程序

通过运行npm install或来安装新的依赖项yarn install。

将导入更改为Construct从新constructs模块、核心类型（例如App和Stack从的顶层）导入aws-cdk-lib，以及从下的命名空间中使用的服务的稳定构造库模块导入。aws-cdk-lib


import { Construct } from 'constructs';
import { App, Stack } from 'aws-cdk-lib';                 // core constructs
import { aws_s3 as s3 } from 'aws-cdk-lib';               // stable module
import * as codestar from '@aws-cdk/aws-codestar-alpha';  // experimental module

JavaScript

更新package.json如下。移除对 v1 风格的单个稳定模块的依赖，并建立应用程序aws-cdk-lib所需的最低版本（此处为 2.0.0）。


{
  "dependencies": {
    "aws-cdk-lib": "^2.0.0",
    "@aws-cdk/aws-codestar-alpha": "2.0.0-alpha.1",
    "constructs": "^10.0.0"
  }
}

通过运行npm install或来安装新的依赖项yarn install。

更改应用程序的导入以执行以下操作：

Construct从新constructs模块导入
从顶层导入核心类型Stack，例如App和 aws-cdk-lib
从下的命名空间导入 AWS 构造库模块 aws-cdk-lib


const { Construct } = require('constructs');
const { App, Stack } = require('aws-cdk-lib');              // core constructs
const s3 = require('aws-cdk-lib').aws_s3;                   // stable module
const codestar = require('@aws-cdk/aws-codestar-alpha');    // experimental module

Python

更新requirements.txt或中的install_requires定义，setup.py如下所示。移除对 v1 风格的单个稳定模块的依赖。

实验构造在单独的、独立版本化的包中提供，其名称以结尾alpha并带有 alpha 版本号。alpha 版本号对应于aws-cdk-lib与之兼容的第一个版本。在这里，我们已固定aws-codestar到 v2.0.0alpha1。


install_requires=[
     "aws-cdk-lib>=2.0.0",
     "constructs>=10.0.0",
     "aws-cdk.aws-codestar-alpha>=2.0.0alpha1",
     # ...
],

提示

使用卸载已安装在应用程序虚拟环境中的任何其他版本的 AWS CDK 模块pip uninstall。然后使用安装新的依赖项python -m pip install -r requirements.txt。

更改应用程序的导入以执行以下操作：

Construct从新constructs模块导入
从顶层导入核心类型Stack，例如App和 aws_cdk
从下的命名空间导入 AWS 构造库模块 aws_cdk


from constructs import Construct
from aws_cdk import App, Stack                    # core constructs
from aws_cdk import aws_s3 as s3                  # stable module
import aws_cdk.aws_codestar_alpha as codestar     # experimental module

# ...

class MyConstruct(Construct):
    # ...

class MyStack(Stack):
    # ...

s3.Bucket(...)

Java

在中pom.xml，删除稳定模块的所有software.amazon.awscdk依赖关系，并将其替换为对 software.constructs (forConstruct) 和的依赖关系software.amazon.awscdk。


<dependency>
    <groupId>software.amazon.awscdk</groupId>
    <artifactId>aws-cdk-lib</artifactId>
    <version>2.0.0</version>
</dependency><dependency>
    <groupId>software.amazon.awscdk</groupId>
    <artifactId>code-star-alpha</artifactId>
    <version>2.0.0-alpha.1</version>
</dependency>
<dependency>
    <groupId>software.constructs</groupId>
    <artifactId>constructs</artifactId>
    <version>10.0.0</version>
</dependency>

通过运行安装新的依赖项mvn package。

更改您的代码以执行以下操作：

Construct从新software.constructs库导入
从中导入核心类App，比如Stack和 software.amazon.awscdk
从中导入服务构造 software.amazon.awscdk.services


import software.constructs.Construct;
import software.amazon.awscdk.Stack;
import software.amazon.awscdk.StackProps;
import software.amazon.awscdk.App;
import software.amazon.awscdk.services.s3.Bucket;
import software.amazon.awscdk.services.codestar.alpha.GitHubRepository;

C#

升级 C# CDK 应用程序依赖关系的最直接方法是手动编辑.csproj文件。删除所有稳定的Amazon.CDK.*软件包引用，并将其替换为对Amazon.CDK.Lib和Constructs软件包的引用。


<PackageReference Include="Amazon.CDK.Lib" Version="2.0.0" />
<PackageReference Include="Amazon.CDK.AWS.Codestar.Alpha" Version="2.0.0-alpha.1" />
<PackageReference Include="Constructs" Version="10.0.0" />

通过运行安装新的依赖项dotnet restore。

按如下所示更改源文件中的导入。


using Constructs;                   // for Construct class
using Amazon.CDK;                   // for core classes like App and Stack
using Amazon.CDK.AWS.S3;            // for stable constructs like Bucket
using Amazon.CDK.Codestar.Alpha;    // for experimental constructs

Go

将您的依赖项更新go get到最新版本并更新项目.mod文件的问题。

在部署之前测试已迁移的应用程序

在部署堆栈之前，cdk diff请使用检查资源是否有意外更改。预计不会对逻辑进行更改IDs（导致资源替换）。

预期的变化包括但不限于：

对CDKMetadata资源的更改。
更新了资产哈希值。
与新式堆栈合成相关的更改。如果您的应用在 v1 中使用了旧版堆栈合成器，则适用。（CDKv2 不支持旧版堆栈合成器。）
添加CheckBootstrapVersion规则。

升级到 AWS CDK v2 本身通常不会导致意外更改。通常，它们是由先前被功能标志更改的过时行为的结果。这是从大约 1.85.x CDK 之前的版本升级的症状。升级到最新的 v1.x 版本时，你会看到同样的变化。通常，您可以通过执行以下操作来解决此问题：

将您的应用程序升级到最新的 v1.x 版本
移除功能标志
根据需要修改您的代码
部署
升级到 v2

注意

如果升级后的应用程序在两阶段升级后无法部署，请报告问题。

当您准备好在应用程序中部署堆栈时，可以考虑先部署一个副本，以便对其进行测试。最简单的方法是将其部署到不同的区域。但是，您也可以更改堆栈IDs的数量。测试完成后，请务必使用销毁测试副本cdk destroy。

故障排除

TypeScript `'from' expected`或者导入`';' expected`时出错

升级到 TypeScript 3.8 或更高版本。

运行 “cdk bootstrap”

如果你看到类似以下的错误：

❌  MyStack failed: Error: MyStack: SSM parameter /cdk-bootstrap/hnb659fds/version not found. Has the environment been bootstrapped? Please run 'cdk bootstrap' (see https://docs.aws.amazon.com/cdk/latest/guide/bootstrapping.html)
    at CloudFormationDeployments.validateBootstrapStackVersion (.../aws-cdk/lib/api/cloudformation-deployments.ts:323:13)
    at processTicksAndRejections (internal/process/task_queues.js:97:5)
MyStack: SSM parameter /cdk-bootstrap/hnb659fds/version not found. Has the environment been bootstrapped? Please run 'cdk bootstrap' (see https://docs.aws.amazon.com/cdk/latest/guide/bootstrapping.html)

AWS CDK v2 需要更新的引导堆栈，而且，所有 v2 部署都需要引导资源。（使用 v1，您无需引导即可部署简单的堆栈。）有关完整的详细信息，请参阅 AWS CDK 自力更生。

查找 v1 堆栈

将CDK应用程序从 v1 迁移到 v2 时，您可能需要识别使用 v1 创建的已部署 AWS CloudFormation 堆栈。为此，请运行以下命令：


npx awscdk-v1-stack-finder

有关用法的详细信息，请参阅 awsc READMEdk-v1-stack-finder。

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

文档惯例

最佳实践

迁移到 AWS CDK