这是 AWS CDK v2 开发者指南。较旧的 CDK v1 于 2022 年 6 月 1 日进入维护阶段,并于 2023 年 6 月 1 日终止支持。
本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。
从 AWS CDK v1 迁移到 v2 AWS CDK
的版本 2 AWS Cloud Development Kit (AWS CDK) 旨在让使用您首选的编程语言更轻松地将基础架构作为代码进行编写。本主题介绍的 v1 和 v2 之间的变化。 AWS CDK
提示
要识别使用 v1 部署的堆栈,请使用 aw
从 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
后缀。(当需要进行重大更改时Beta2
Beta3
,其次是、等。) 当指定为稳定版本时,会添加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。
更新依赖关系和导入
更新应用程序的依赖关系,然后安装新的软件包。最后,更新代码中的导入。
在部署之前测试已迁移的应用程序
在部署堆栈之前,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 README