从 AWS CDK v1 迁移到 v2 AWS CDK

RSS

聚焦模式

从 AWS CDK v1 迁移到 v2 AWS CDK - AWS Cloud Development Kit (AWS CDK) v2

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

这是 AWS CDK v2 开发者指南。旧版 CDK v1 于 2022 年 6 月 1 日进入维护阶段，并于 2023 年 6 月 1 日终止支持。

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

这是 AWS CDK v2 开发者指南。旧版 CDK v1 于 2022 年 6 月 1 日进入维护阶段，并于 2023 年 6 月 1 日终止支持。

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

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

提示

要识别使用 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
实验性模块不包含在 aws-cdk-lib 中，我们仍在与社区合作在其中开发新的 L2 或 L3 构造。相反，它们是作为单独的软件包进行分发的。实验软件包以 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后缀。（当需要进行重大更改时，接下来后缀为 Beta2、Beta3，依此类推。）当认定 API 稳定时，会添加不带后缀的 API 版本。将弃用除最新方法（无论是测试版还是最终版）之外的所有方法。

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

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

重要

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

新的先决条件

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

对于 TypeScript 开发人员，需要 TypeScript 3.8 或更高版本。
需要新版本的 CDK Toolkit 才能与 CDK v2 一起使用。CDK v2 现已正式发布，因此安装 CDK Toolkit时，v2 是默认版本。该版本向后兼容 CDK v1 项目，因此除非要创建 CDK v1 项目，否则无需安装早期版本。要进行升级，请发出 npm install -g aws-cdk 命令。

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

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

anchor anchor anchor anchor anchor anchor

npm install 或 yarn install

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

从 AWS CDK v1 迁移到 CDK v2

要将您的应用程序迁移到 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 Toolkit 兼容性

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

如果您需要同时创建 v1 和 v2 CDK 项目，请勿全局安装 CDK Toolkit v2。（如果您已经安装了该版本，请将其删除：npm remove -g aws-cdk。）要调用 CDK Toolkit，请根据需要使用 npx 来运行 CDK Toolkit 的 v1 或 v2。


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

提示

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

anchor anchor


alias cdk1="npx aws-cdk@1.x"
alias cdk="npx aws-cdk@2.x"

更新依赖项和导入项

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

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 Maintenance Policy。

库和应用程序

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

将您的导入更改为从新的 constructs 模块导入 Construct、从 aws-cdk-lib 的顶层导入核心类型（例如 App 和 Stack），以及从 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 命令来安装新的依赖项。

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

从新的 constructs 模块导入 Construct
从 aws-cdk-lib 的顶层导入核心类型，例如 App 和 Stack
从下的命名空间导入 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 或 setup.py 中的 install_requires 定义。删除 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 安装新的依赖项。

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

从新的 constructs 模块导入 Construct
从 aws_cdk 的顶层导入核心类型，例如 App 和 Stack
从下的命名空间导入 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（用于 Construct）和 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命令来安装新的依赖项。

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

从新的 software.constructs 库中导入 Construct
从 software.amazon.awscdk 中导入核心类，例如 Stack 和 App
从 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 文件。

anchor anchor anchor anchor anchor anchor

应用程序


{
  "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"
  }
}

注意

库和应用程序

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


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

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

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

预期更改包括但不限于：

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

升级到 AWS CDK v2 本身通常不会导致意外更改。通常，先前由功能标志更改的弃用行为才会导致这种结果。这是从 CDK 1.85.x 之前的版本升级会出现的情况。升级到最新的 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

有关使用详细信息，请参阅 awscdk-v1-stack-finder README。

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

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

文档惯例

安全性

迁移到 AWS CDK

本页内容

选择您的 Cookie 首选项

自定义 Cookie 首选项

关键

性能

功能

广告

无法保存 Cookie 首选项

从 AWS CDK v1 迁移到 v2 AWS CDK

提示

重要

新的先决条件

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

从 AWS CDK v1 迁移到 CDK v2

更新至最新的 v1

更新功能标志

CDK Toolkit 兼容性

提示

更新依赖项和导入项

应用程序

构造库

注意

库和应用程序

提示

应用程序

构造库

注意

库和应用程序

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

注意

故障排除

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

运行“cdk bootstrap”

查找 v1 堆栈

本页内容

此页内容对您是否有帮助？

下一主题：

上一主题：

需要帮助吗？

选择您的 Cookie 首选项

从 AWS CDK v1 迁移到 v2 AWS CDK

提示

重要

新的先决条件

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

从 AWS CDK v1 迁移到 CDK v2

更新至最新的 v1

更新功能标志

CDK Toolkit 兼容性

提示

更新依赖项和导入项

应用程序

构造库

注意

库和应用程序

提示

应用程序

构造库

注意

库和应用程序

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

注意

故障排除

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

运行“cdk bootstrap”

查找 v1 堆栈

本页内容

此页内容对您是否有帮助？

下一主题：

上一主题：

需要帮助吗？

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