View a markdown version of this page

迁移现有资源和 AWS CloudFormation 模板到 AWS CDK - AWS 云开发套件 (AWS CDK) v2
迁移的工作原理CDK Migrate 优势注意事项先决条件开始使用 CDK Migrate从 AWS CloudFormation 堆栈从 AWS CloudFormation 模板从已部署的资源迁移管理和部署 CDK 应用程序

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

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

迁移现有资源和 AWS CloudFormation 模板到 AWS CDK

CDK Migrate 功能现为 AWS CDK 的预览版，可能会发生变化。

使用 AWS 云开发套件 (AWS CDK) 命令行界面 (AWS CDK CLI) 将已部署的 AWS 资源、已部署的 AWS CloudFormation 堆栈和本地 AWS CloudFormation 模板迁移到 CDK。 AWS

迁移的工作原理

使用 AWS CDK CLI cdk migrate 命令从以下来源迁移：

  • 已部署的 AWS 资源。

  • 已部署 AWS CloudFormation 的堆栈。

  • 本地 AWS CloudFormation 模板。

已部署的 AWS 资源

您可以从与 AWS CloudFormation 堆栈无关的特定环境（AWS 账户和 AWS 区域）迁移已部署的 AWS 资源。

AWS CDK CLI 利用 IaC 生成器服务扫描 AWS 环境中的资源以收集资源详细信息。要了解有关 IaC 生成器的更多信息，请参阅 AWS CloudFormation 用户指南中的为现有资源生成模板。

收集资源详细信息后， AWS CDK CLI 会创建一个新的 CDK 应用程序，其中包含一个包含您迁移的资源的单个堆栈。

已部署的 AWS CloudFormation 堆栈

您可以将单个 AWS CloudFormation 堆栈迁移到新的 AWS CDK 应用程序中。 AWS CDK CLI 将检索您的堆栈 AWS CloudFormation 模板并创建新的 CDK 应用程序。CDK 应用程序将由一个包含您迁移的堆栈的单个 AWS CloudFormation 堆栈组成。

本地 AWS CloudFormation 模板

您可以从本地 AWS CloudFormation 模板迁移。本地模板可能包含也可能不包含已部署的资源。 AWS CDK CLI 将创建一个新的 CDK 应用程序，其中包含一个包含您的资源的单一堆栈。

迁移后，您可以管理、修改和部署您的 CDK 应用程序， AWS CloudFormation 以预置或更新您的资源。

CDK Migrate 优势

从历史上看，将资源迁移到 AWS CDK 是一个手动过程，需要时间和专业知识才能 AWS 开始 CDK。 AWS CloudFormation 借助 CDK Migrate， AWS CDK CLI 可以在很短的时间内为您完成大部分迁移工作。CDK Migrate 将帮助您快速开始使用 AWS CDK 来开发和管理新的和现有的应用程序。 AWS

注意事项

一般注意事项

CDK 迁移与 CDK 导入

cdk import 命令可以将已部署的资源导入到新的或现有的 CDK 应用程序中。导入时，您必须在应用程序中手动将每个资源定义为 L1 构造。我们建议使用 cdk import 一次将一个或多个资源导入到新的或现有的 CDK 应用程序中。要了解更多信息，请参阅将现有资源导入到堆栈中。

该cdk migrate命令从已部署的资源、已部署的 AWS CloudFormation 堆栈或本地 AWS CloudFormation 模板迁移到新的 CDK 应用程序中。在迁移期间， AWS CDK CLI 使用将您的资源导入cdk import到新的 CDK 应用程序中。 AWS CDK CLI 还会为您生成每种资源的 L1 结构。我们建议在从支持的迁移源导入到新的 AWS CDK 应用程序cdk migrate时使用。

CDK Migrate 仅创建 L1 结构

新创建的 CDK 应用程序仅包含 L1 构造。迁移后，您可以为应用程序中添加更高级别的构造。

CDK Migrate 创建包含单个堆栈的 CDK 应用程序

新创建的 CDK 应用程序包含单个堆栈。

迁移已部署的资源时，所有已迁移的资源都将包含在新 CDK 应用程序的单个堆栈中。

迁移 AWS CloudFormation 堆栈时，您只能在新的 CDK 应用程序中将单个 AWS CloudFormation 堆栈迁移到单个堆栈中。

迁移资产

项目资产，例如 AWS Lambda 代码，不会直接迁移到新的 CDK 应用程序中。迁移后，您可以指定资产值，以将其包含在 CDK 应用程序中。

迁移有状态资源

在迁移有状态资源 [例如数据库和 Amazon Simple Storage Service（Amazon S3）存储桶] 时，您通常希望迁移现有资源而不是创建新资源。

要迁移和保留有状态资源，请执行以下操作：

  • 验证有状态资源是否支持导入。有关更多信息，请参阅《 AWS CloudFormation 用户指南》中的资源类型支持。

  • 迁移后，请验证新 CDK 应用程序中已迁移资源的逻辑 ID 是否与已部署资源的逻辑 ID 匹配。

  • 如果从 AWS CloudFormation 堆栈迁移，请验证新 CDK 应用程序中的堆栈名称是否与 AWS CloudFormation 堆栈相匹配。

  • 使用迁移资源的相同 AWS 账户和 AWS 区域部署 CDK 应用程序。

从迁移时的注意事项 AWS CloudFormation 模板

CDK Migrate 支持单模板迁移

迁移 AWS CloudFormation 模板时，您可以选择要迁移的单个模板。不支持嵌套模板。

迁移具有内部函数的模板

从使用内部函数的 AWS CloudFormation 模板迁移时， AWS CDK CLI 将尝试使用该类将您的逻辑迁移到 CDK 应用程序。Fn要了解更多信息，请参阅 AWS 云开发套件 (AWS CDK) API 参考中的 Fn 类。

从已部署的资源迁移时的注意事项

扫描限制

在扫描环境以查找资源时，IaC 生成器对其可以检索的数据有特定的限制，并且在扫描时有配额限制。要了解更多信息，请参阅《 AWS CloudFormation 用户指南》中的注意事项。

先决条件

在使用该cdk migrate命令之前，完成 AWS CDK 开始使用 AWS CDK 入门中的所有设置步骤。

开始使用 CDK Migrate

首先，从您选择的目录运行 AWS CDK CLI cdk migrate 命令。根据您要执行的迁移类型，提供必需选项和可选选项。

有关可与 cdk migrate 结合使用的选项的完整列表和说明，请参阅 cdk migrate。

以下是您可能需要提供的一些重要选项。

堆栈名称

唯一的必需选项是 --stack-name。使用此选项为迁移后将在 AWS CDK 应用程序中创建的堆栈指定名称。堆栈名称也将在部署时用作 AWS CloudFormation 堆栈的名称。

语言

使用 --language 指定新 CDK 应用程序的编程语言。

AWS 账户和 AWS 区域

AWS CDK CLI 从默认来源检索 AWS 账户和 AWS 区域信息。有关更多信息，请参阅 AWS CDK 的环境。您可以将 --account 和 --region 选项与 cdk migrate 结合使用来提供其他值。

新 CDK 项目的输出目录

默认情况下， AWS CDK CLI 将在您的工作目录中创建一个新的 CDK 项目，并使用您提供的值--stack-name来命名该项目文件夹。如果当前存在同名文件夹， AWS CDK CLI 将覆盖该文件夹。

您可以使用 --output-path 选项为新的 CDK 项目文件夹指定不同的输出路径。

迁移来源

提供一个选项来指定您要从中迁移的源。

  • --from-path— 从本地 AWS CloudFormation 模板迁移。

  • --from-scan— 从 AWS 账户和 AWS 区域中部署的资源迁移。

  • --from-stack— 从 AWS CloudFormation 堆栈迁移。

根据您的迁移源，您可以提供其他选项来自定义 cdk migrate 命令。

从 AWS CloudFormation 堆栈

要从已部署的 AWS CloudFormation 堆栈迁移，请提供--from-stack选项。使用提供已部署 AWS CloudFormation 堆栈的名称--stack-name。以下是示例：

$ cdk migrate --from-stack --stack-name "myCloudFormationStack"

AWS CDK CLI 将执行以下操作：

  1. 检索已部署堆栈的 AWS CloudFormation 模板。

  2. 运行 cdk init 来初始化新的 CDK 应用程序。

  3. 在 CDK 应用程序中创建包含迁移 AWS CloudFormation 堆栈的堆栈。

当您从已部署的 AWS CloudFormation 堆栈迁移时， AWS CDK CLI 会尝试将已部署的资源逻辑 ID 和已部署的 AWS CloudFormation 堆栈名称与新 CDK 应用程序中迁移的资源和堆栈进行匹配。

迁移后，您可以正常管理和修改 CDK 应用程序。部署时，由于 AWS CloudFormation 堆栈名称匹配， AWS CloudFormation 会将部署标识为 AWS CloudFormation 堆栈更新。具有匹配逻辑 ID 的资源将更新。有关部署的更多信息，请参阅管理和部署 CDK 应用程序。

从 AWS CloudFormation 模板

CDK Migrate 支持从格式为JSON或YAML的 AWS CloudFormation 模板迁移。

要从本地 AWS CloudFormation 模板迁移，请使用--from-path选项并提供本地模板的路径。您还必须提供所需的 --stack-name 选项。以下是示例：

$ cdk migrate --from-path "./template.json" --stack-name "myCloudFormationStack"

AWS CDK CLI 将执行以下操作：

  1. 检索您的本地 AWS CloudFormation 模板。

  2. 运行 cdk init 来初始化新的 CDK 应用程序。

  3. 在 CDK 应用程序中创建包含迁移 AWS CloudFormation 模板的堆栈。

迁移后，您可以正常管理和修改 CDK 应用程序。部署时，您可以使用以下选项：

  • 更新 AWS CloudFormation 堆栈 -如果之前部署了本地 AWS CloudFormation 模板，则可以更新已部署的 AWS CloudFormation 堆栈。

  • 部署新 AWS CloudFormation 堆栈 -如果从未部署过本地 AWS CloudFormation 模板，或者您想从先前部署的模板创建新堆栈，则可以部署新 AWS CloudFormation 堆栈。

从 AWS SAM 模板

要从 AWS 无服务器应用程序模型 (AWS SAM) 模板迁移，必须先将其转换为 AWS CloudFormation 模板或进行部署以创建 AWS CloudFormation 堆栈。

要将 AWS SAM 模板转换为 AWS CloudFormation，可以使用 AWS SAM CLI sam validate --debug 命令。在运行此命令之前，您可能需要在 samconfig.toml 文件中将 lint 设置为 false。

要转换为 AWS CloudFormation 堆栈，请使用 AWS SAM CLI 部署 AWS SAM 模板。然后从已部署的堆栈迁移。

从已部署的资源迁移

要从已部署的 AWS 资源中迁移，请提供--from-scan选项。您还必须提供所需的 --stack-name 选项。以下是示例：

$ cdk migrate --from-scan --stack-name "myCloudFormationStack"

AWS CDK CLI 将执行以下操作：

  1. 扫描您的帐户以获取资源和财产详细信息 — AWS CDK CLI 使用 IaC 生成器扫描您的帐户并收集详细信息。

  2. 生成 AWS CloudFormation 模板 -扫描后， AWS CDK CLI 使用 IaC 生成器来创建模板。 AWS CloudFormation

  3. 初始化新的 CDK 应用程序并迁移您的模板 — AWS CDK CLI 运行cdk init以初始化新的 AWS CDK 应用程序，并将您的 AWS CloudFormation 模板作为单个堆栈迁移到 CDK 应用程序中。

使用筛选器

默认情况下， AWS CDK CLI 将扫描整个 AWS 环境并将资源迁移至 IaC 生成器的最大配额限制。您可以通过 AWS CDK CLI 提供过滤器，以指定将资源从您的账户迁移到新 CDK 应用程序的标准。要了解更多信息，请参阅 --filter 。

使用 IaC 生成器扫描资源

根据您的账户中的资源数量，扫描可能需要几分钟。扫描过程中会显示一个进度条。

支持的资源类型

AWS CDK CLI 将迁移 IaC 生成器支持的资源。有关完整列表，请参阅《 AWS CloudFormation 用户指南》中的资源类型支持。

解决只写属性问题

一些支持的资源包含只写属性。可以写入这些属性来配置属性，但是 IaC 生成器无法读 AWS CloudFormation 取或获取值。例如，出于安全考虑，用于指定数据库密码的属性可能是只写属性。

在迁移期间扫描资源时，IaC 生成器会检测可能包含只写属性的资源，并将其归类为以下任何类型：

  • MUTUALLY_EXCLUSIVE_PROPERTIES：这些是特定资源的只写属性，可以互换，用途相似。配置资源需要其中一个互斥属性。例如， AWS::Lambda::Function 资源的 S3Bucket、ImageUri、和 ZipFile 属性是互斥的只写属性。其中任何一个属性都可用于指定函数资产，但您必须使用一个。

  • MUTUALLY_EXCLUSIVE_TYPES：这些是必需的只写属性，接受多种配置类型。例如， AWS::ApiGateway::RestApi 资源的 Body 属性接受对象或字符串类型。

  • UNSUPPORTED_PROPERTIES：这些是只写属性，不属于其他两个类别。它们是可选属性或必需属性，接受对象数组。

有关只写属性以及 IaC 生成器在扫描已部署资源和创建 AWS CloudFormation 模板时如何管理这些属性的更多信息，请参阅用户指南中的 iaC 生成器和只写属性。 AWS CloudFormation

迁移后，您必须在新的 CDK 应用程序中指定只写属性值。 AWS CDK CLI 将在 CDK 项目的ReadMe文件中附加警告部分，以记录 IaC 生成器标识的所有只写属性。以下是示例：

# Welcome to your CDK TypeScript project
...
## Warnings
### Write-only properties
Write-only properties are resource property values that can be written to but can't be read by AWS CloudFormation or CDK Migrate. For more information, see [IaC generator and write-only properties](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/generate-IaC-write-only-properties.html).

Write-only properties discovered during migration are organized here by resource ID and categorized by write-only property type. Resolve write-only properties by providing property values in your CDK app. For guidance, see [Resolve write-only properties](https://docs.aws.amazon.com/cdk/v2/guide/migrate.html#migrate-resources-writeonly).
### MyLambdaFunction
- **UNSUPPORTED_PROPERTIES**:
  - SnapStart/ApplyOn: Applying SnapStart setting on function resource type.Possible values: [PublishedVersions, None]
This property can be replaced with other types
  - Code/S3ObjectVersion: For versioned objects, the version of the deployment package object to use.
This property can be replaced with other exclusive properties
- **MUTUALLY_EXCLUSIVE_PROPERTIES**:
  - Code/S3Bucket: An Amazon S3 bucket in the same AWS Region as your function. The bucket can be in a different AWS account.
This property can be replaced with other exclusive properties
  - Code/S3Key: The Amazon S3 key of the deployment package.
This property can be replaced with other exclusive properties

  • 警告按标题进行组织，标题用于识别与之关联的资源的逻辑 ID。

  • 警告按类型分类。这些类型直接来自 IaC 生成器。

解析只写属性

  1. 从 CDK 项目 ReadMe 文件的警告部分识别要解析的只写属性。在这里，您可以记下 CDK 应用程序中可能包含只写属性的资源并识别已发现的只写属性类型。

    1. 对于MUTUALLY_EXCLUSIVE_PROPERTIES，确定要在 AWS CDK 应用程序中配置哪个互斥属性。

    2. 对于 MUTUALLY_EXCLUSIVE_TYPES，确定您将使用哪个接受的类型来配置该属性。

    3. 对于 UNSUPPORTED_PROPERTIES，确定该属性是可选属性还是必需属性。然后，根据需要进行配置。

  2. 使用 IaC 生成器和只写属性中的指导来参考警告类型的含义。

  3. 在 CDK 应用程序中，还会在应用程序的 Props 部分指定要解析的只写属性值。在此处提供正确的值。有关属性说明和指导，您可以参考 AWS CDK API 参考。

    以下是已迁移的 CDK 应用程序中 Props 部分的示例，其中包含两个要解析的只写属性：

    export interface MyTestAppStackProps extends cdk.StackProps {
  /**
   * The Amazon S3 key of the deployment package.
   */
  readonly lambdaFunction00asdfasdfsadf008grk1CodeS3Keym8P82: string;
  /**
   * An Amazon S3 bucket in the same AWS Region as your function. The bucket can be in a different AWS account.
   */
  readonly lambdaFunction00asdfasdfsadf008grk1CodeS3Bucketzidw8: string;
}

    解析完所有只写属性值后，就可以为部署做准备。

migrate.json 文件

在迁 AWS 移期间，CDK CLI 会在您的 AWS CDK 项目中创建一个migrate.json文件。此文件包含有关已部署的资源的参考信息。当您首次部署 CDK 应用程序时， AWS CDK CLI 使用此文件来引用您部署的资源，将您的资源与新 AWS CloudFormation 堆栈关联并删除该文件。

管理和部署 CDK 应用程序

迁移到 AWS CDK 时，新的 CDK 应用程序可能无法立即做好部署准备。本主题介绍在管理和部署新的 CDK 应用程序时需要考虑的操作项。

准备部署

在部署之前，您必须准备好 CDK 应用程序。

合成您的应用程序

使用该cdk synth命令将 CDK 应用程序中的堆栈合成模板。 AWS CloudFormation

如果您是从已部署的 AWS CloudFormation 堆栈或模板迁移的，则可以将合成的模板与迁移的模板进行比较，以验证资源和属性值。

要了解有关 cdk synth 的更多信息，请参阅合成堆栈。

进行差异

如果您是从已部署的 AWS CloudFormation 堆栈迁移的，则可以使用 cdk diff 命令与新 CDK 应用程序中的堆栈进行比较。

要了解有关 cdk diff 的更多信息，请参阅比较堆栈。

引导您的环境

如果您是首次从 AWS 环境进行部署，请使用cdk bootstrap来准备环境。要了解更多信息，请参阅 AWS CDK 引导。

部署 CDK 应用程序

当您部署 CDK 应用程序时， AWS CDK CLI 会利用该 AWS CloudFormation 服务来配置您的资源。资源在 CDK 应用程序中捆绑到单个堆栈中，并作为单 AWS CloudFormation 个堆栈进行部署。

根据您的迁移来源，您可以部署来创建新 AWS CloudFormation 堆栈或更新现有 AWS CloudFormation 堆栈。

部署以创建新 AWS CloudFormation 堆栈

如果您从已部署的资源迁移， AWS CDK CLI 将在部署时自动创建新的 AWS CloudFormation 堆栈。您部署的资源将包含在新 AWS CloudFormation 堆栈中。

如果您从从未部署过的本地 AWS CloudFormation 模板迁移， AWS CDK CLI 将在部署时自动创建新的 AWS CloudFormation 堆栈。

如果您是从已部署的 AWS CloudFormation 堆栈或先前部署的本地 AWS CloudFormation 模板迁移而来的，则可以部署以创建新的 AWS CloudFormation 堆栈。要创建新堆栈，请执行以下操作：

  • 部署到新 AWS 环境。这包括使用不同的 AWS 账户或部署到不同的 AWS 区域。

  • 如果您想将新堆栈部署到迁移堆栈或模板的相同 AWS 环境中，则必须将 CDK 应用程序中的堆栈名称修改为新值。您还必须修改 CDK 应用程序中资源的所有逻辑 ID。然后，您可以部署到同一环境以创建新堆栈和新资源。

部署以更新现有 AWS CloudFormation 堆栈

如果您是从先前部署的已部署 AWS CloudFormation 堆栈或本地 AWS CloudFormation 模板迁移的，则可以部署以更新现有 AWS CloudFormation 堆栈。

验证您的 CDK 应用程序中的堆栈名称是否与已部署堆栈的堆 AWS CloudFormation 栈名称相匹配并部署到同一 AWS 环境。