將現有的資源和 AWS CloudFormation 範本遷移至 AWS CDK

這是 AWS CDK v2 開發人員指南。較舊的 CDK v1 已於 2022 年 6 月 1 日進入維護，並於 2023 年 6 月 1 日結束支援。

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

這是 AWS CDK v2 開發人員指南。較舊的 CDK v1 已於 2022 年 6 月 1 日進入維護，並於 2023 年 6 月 1 日結束支援。

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

使用 AWS Cloud Development Kit (AWS CDK) 命令列界面 (AWS CDK CLI) 將已部署 AWS 的資源、已部署的 AWS CloudFormation 堆疊和本機 AWS CloudFormation 範本遷移至其中 AWS CDK。

遷移的運作方式

使用 AWS CDK CLIcdk migrate命令從下列來源遷移：

遷移後，您可以管理、修改和部署 CDK 應用程式至 ， AWS CloudFormation 以佈建或更新 資源。

CDK Migrate 的優點

將資源遷移到 AWS CDK 在過去是一個手動程序，需要時間和專業知識，甚至 AWS CloudFormation AWS CDK 可以開始。使用 CDK Migrate， AWS CDK CLI只需一小段時間， 就能為您促進大部分的遷移工作。CDK Migrate 將快速協助您開始使用 AWS CDK 來開發和管理新的和現有的應用程式 AWS。

考量事項

一般考量

從 AWS CloudFormation 範本遷移時的考量事項

從部署的資源遷移時的考量

先決條件

使用 cdk migrate命令之前，請先完成 中的所有設定步驟開始使用 AWS CDK。

CDK Migrate 入門

若要開始，請從您選擇的目錄執行 AWS CDK CLIcdk migrate命令。根據您執行的遷移類型，提供必要和選用的選項。

如需可與 搭配使用之選項的完整清單和說明cdk migrate，請參閱 cdk migrate。

以下是您可能想要提供的一些重要選項。

從 AWS CloudFormation 堆疊遷移

若要從部署的 AWS CloudFormation 堆疊遷移，請提供 --from-stack選項。使用 提供已部署 AWS CloudFormation 堆疊的名稱--stack-name。以下是範例：

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

AWS CDK CLI 將執行下列動作：

當您從已部署的 AWS CloudFormation 堆疊遷移時， 會 AWS CDK CLI嘗試將已部署的資源邏輯 IDs 和已部署的 AWS CloudFormation 堆疊名稱，比對至新 CDK 應用程式中已遷移的資源和堆疊。

遷移後，您可以正常管理和修改 CDK 應用程式。部署時， AWS CloudFormation 會因為符合的 AWS CloudFormation 堆疊名稱，將部署識別為 AWS CloudFormation 堆疊更新。具有相符邏輯 IDs 的資源將會更新。如需部署的詳細資訊，請參閱 管理和部署 CDK 應用程式。

從 AWS CloudFormation 範本遷移

CDK Migrate 支援從格式為 JSON或 的 AWS CloudFormation 範本遷移YAML。

若要從本機 AWS CloudFormation 範本遷移，請使用 --from-path選項並提供本機範本的路徑。您也必須提供必要的--stack-name選項。以下是範例：

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

AWS CDK CLI 將執行下列動作：

遷移後，您可以正常管理和修改 CDK 應用程式。在部署時，您有下列選項：

從 AWS SAM 範本遷移

若要從 AWS Serverless Application Model (AWS SAM) 範本遷移，您必須先將其轉換為 AWS CloudFormation 範本，或部署 以建立 AWS CloudFormation 堆疊。

若要將 AWS SAM 範本轉換為 AWS CloudFormation，您可以使用 AWS SAM CLIsam validate --debug命令。在執行此命令之前，您可能需要在 samconfig.toml false檔案中lint將 設定為 。

若要轉換為 AWS CloudFormation 堆疊，請使用 部署 AWS SAM 範本 AWS SAM CLI。然後從部署的堆疊遷移。

從部署的資源遷移

若要從部署 AWS 的資源遷移，請提供 --from-scan選項。您也必須提供必要的--stack-name選項。以下是範例：

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

AWS CDK CLI 將執行下列動作：

使用篩選條件

根據預設， AWS CDK CLI會掃描整個 AWS 環境，並將資源遷移至 IaC 產生器的最大配額限制。您可以使用 AWS CDK CLI提供篩選條件，以指定資源從您的帳戶遷移到新 CDK 應用程式的條件。如需進一步了解，請參閱 --filter。

使用 IaC 產生器掃描資源

根據您帳戶中的資源數量，掃描可能需要幾分鐘的時間。掃描程序期間會顯示進度列。

解決唯寫屬性

有些支援的資源包含唯寫屬性。這些屬性可以寫入 來設定 屬性，但 IaC 產生器無法讀取或 AWS CloudFormation 取得 值。例如，基於安全考量，用於指定資料庫密碼的 屬性可能為唯寫。

在遷移期間掃描資源時，IaC 產生器會偵測可能包含唯寫屬性的資源，並將其分類為下列任何類型：

如需唯寫屬性以及 IaC 產生器在掃描部署資源和建立 AWS CloudFormation 範本時如何管理它們的詳細資訊，請參閱AWS CloudFormation 《 使用者指南》中的 IaC 產生器和唯寫屬性。

遷移後，您必須在新的 CDK 應用程式中指定唯寫屬性值。會將警告區段附加至 CDK AWS CDK CLI專案的 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

解決所有唯寫屬性值後，您就可以準備部署。

migrate.json 檔案

會在遷移期間在您的 AWS CDK 專案中 AWS CDK CLI建立 migrate.json 檔案。此檔案包含已部署資源的參考資訊。當您第一次部署 CDK 應用程式時， AWS CDK CLI會使用此檔案來參考已部署的資源、將資源與新 AWS CloudFormation 堆疊建立關聯，以及刪除檔案。

管理和部署 CDK 應用程式

遷移至 時 AWS CDK，新的 CDK 應用程式可能無法立即部署。本主題說明管理和部署新 CDK 應用程式時要考慮的動作項目。

準備部署

部署之前，您必須準備 CDK 應用程式。

部署您的 CDK 應用程式

當您部署 CDK 應用程式時， AWS CDK CLI 會利用 AWS CloudFormation 服務來佈建您的 資源。資源會封裝在 CDK 應用程式中的單一堆疊中，並部署為單一 AWS CloudFormation 堆疊。

視您從何處遷移而定，您可以部署 來建立新的 AWS CloudFormation 堆疊或更新現有的 AWS CloudFormation 堆疊。