遷移的運作方式 CDK Migrate 的優點考量事項必要條件 CDK 遷移入門從 AWS CloudFormation 堆疊遷移從 AWS CloudFormation 範本遷移從部署的資源遷移管理和部署您的CDK應用程式

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

CDK Migrate 功能位於的預覽版本中， AWS CDK 且可能有所變更。

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

遷移的運作方式

使用 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 CloudFormation AWS CDK ，才能開始。使用 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 遷移僅建立 L1 建構

新建立CDK的應用程式將僅包含 L1 建構。您可以在遷移後將更高層級的建構新增至應用程式。

CDK Migrate 會建立包含單一堆疊CDK的應用程式

新建立CDK的應用程式將包含單一堆疊。

遷移部署的資源時，所有遷移的資源都會包含在新CDK應用程式的單一堆疊中。

遷移 AWS CloudFormation 堆疊時，您只能將單一 AWS CloudFormation 堆疊遷移至新CDK應用程式中的單一堆疊。

遷移資產

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 會嘗試使用 Fn類別將邏輯遷移至CDK應用程式。若要進一步了解，請參閱AWS Cloud Development Kit (AWS CDK) API參考 中的類別 Fn。

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

掃描限制: 掃描環境以取得資源時，IaC 產生器對可以擷取的資料有特定限制，並在掃描時配額限制。若要進一步了解，請參閱 AWS CloudFormation 使用者指南 中的考量事項。

必要條件

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

CDK 遷移入門

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

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

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

Stack name (堆疊名稱)

唯一需要的選項是 --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 將執行下列動作：

擷取已部署堆疊的 AWS CloudFormation 範本。
執行 cdk init 以初始化新的CDK應用程式。
在包含遷移堆疊CDK的應用程式內建立 AWS CloudFormation 堆疊。

當您從部署的 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 將執行下列動作：

擷取本機 AWS CloudFormation 範本。
執行 cdk init 以初始化新的CDK應用程式。
在包含遷移 AWS CloudFormation 範本CDK的應用程式內建立堆疊。

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

更新 AWS CloudFormation 堆疊 – 如果先前已部署本機 AWS CloudFormation 範本，您可以更新已部署的 AWS CloudFormation 堆疊。
部署新的 AWS CloudFormation 堆疊 – 如果從未部署本機 AWS CloudFormation 範本，或者如果您想要從先前部署的範本建立新堆疊，您可以部署新的 AWS CloudFormation 堆疊。

從 AWS SAM 範本遷移

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

若要將 AWS SAM 範本轉換為 AWS CloudFormation，您可以使用 AWS SAM CLI sam validate --debug 命令。在執行此命令之前，您可能必須在falsesamconfig.toml檔案中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 使用 IaC 產生器掃描您的帳戶並收集詳細資訊。
產生 AWS CloudFormation 範本 – 掃描後， AWS CDK CLI 會使用 IaC 產生器來建立 AWS CloudFormation 範本。
初始化新的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 範本時如何管理這些屬性的詳細資訊，請參閱 AWS CloudFormation 使用者指南 中的 IaC 產生器和僅限寫入屬性。

遷移後，您必須在新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 產生器。

若要解析唯讀屬性

從CDK專案ReadMe檔案的警告區段中識別要解決的唯讀屬性。在這裡，您可以記下CDK應用程式中可能包含僅寫入屬性的資源，並識別發現的僅寫入屬性類型。
1. 對於 MUTUALLY_EXCLUSIVE_PROPERTIES，決定要在 AWS CDK 應用程式中設定的互斥屬性。
2. 對於 MUTUALLY_EXCLUSIVE_TYPES，請決定您要用來設定屬性的已接受類型。
3. 對於 UNSUPPORTED_PROPERTIES，判斷屬性是選用或必要。然後視需要設定。
使用 IaC 產生器和僅寫入屬性的指引，參考警告類型的意義。

在您的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，請參閱合成堆疊。

執行 diff

如果您從部署的 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應用程式中的堆疊名稱修改為新的值。您還必須修改IDsCDK應用程式中資源的所有邏輯。然後，您可以部署到相同的環境，以建立新的堆疊和新的資源。

部署以更新現有 AWS CloudFormation 堆疊

如果您從先前部署的已部署 AWS CloudFormation 堆疊或本機 AWS CloudFormation 範本遷移，則可以部署來更新現有的 AWS CloudFormation 堆疊。

確認您的CDK應用程式中的堆疊名稱符合已部署堆疊的 AWS CloudFormation 堆疊名稱，並部署至相同的 AWS 環境。

您的瀏覽器已停用或無法使用 Javascript。

您必須啟用 Javascript，才能使用 AWS 文件。請參閱您的瀏覽器說明頁以取得說明。

文件慣用形式

從 AWS CDK 第 1 版遷移到第 AWS CDK 2 版

設定安全認證