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

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

CDK Migrate 功能目前為 AWS CDK 的預覽版本，可能會有所變更。

使用 AWS 雲端開發套件 (AWS CDK) 命令列界面 (AWS CDK CLI) 將部署 AWS 的資源、deployed AWS CloudFormation 堆疊和 local AWS CloudFormation 範本遷移至 AWS CDK。

遷移的運作方式

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

部署 AWS 的資源。
部署的 AWS CloudFormation 堆疊。
Local AWS CloudFormation 範本。

部署 AWS 的資源

您可以從與 an 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 應用程式將由包含您 migrated AWS CloudFormation 堆疊的單一堆疊組成。

Local AWS CloudFormation 範本

您可以從 local 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 堆疊或 local 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 堆疊時，您只能將單一 AWS CloudFormation 堆疊遷移至新 CDK 應用程式中的單一堆疊。

遷移資產

Lambda AWS 程式碼等專案資產不會直接遷移到新的 CDK 應用程式。遷移後，您可以指定要包含在 CDK 應用程式中的資產值。

遷移具狀態資源

遷移資料庫和 Amazon Simple Storage Service (Amazon S3) 儲存貯體等具狀態資源時，您最常想要遷移現有的資源，而不是建立新的資源。

若要遷移和保留具狀態資源，請執行下列動作：

確認您的具狀態資源支援匯入。如需詳細資訊，請參閱《 AWS CloudFormation 使用者指南》中的資源類型支援。
遷移後，請確認遷移的資源在新 CDK 應用程式中的邏輯 ID 符合已部署資源的邏輯 ID。
如果從 AWS CloudFormation 堆疊遷移，請確認新 CDK 應用程式中的堆疊名稱符合 AWS CloudFormation 堆疊。
使用已遷移資源的相同 AWS 帳戶和 AWS 區域部署 CDK 應用程式。

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

CDK Migrate 支援單一範本遷移: 遷移 AWS CloudFormation 範本時，您可以選取要遷移的單一範本。不支援巢狀範本。
使用內部函數遷移範本: 從使用內部函數的 AWS CloudFormation 範本遷移時， AWS CDK CLI 會嘗試使用 Fn類別將邏輯遷移至 CDK 應用程式。若要進一步了解，請參閱《 AWS 雲端開發套件 (AWS CDK) API 參考》中的類別 Fn。

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

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

先決條件

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

CDK Migrate 入門

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

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

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

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 – 從 local AWS CloudFormation 範本遷移。
--from-scan – 從 AWS 帳戶和 AWS 區域中部署的資源遷移。
--from-stack – 從 an AWS CloudFormation 堆疊遷移。

根據您的遷移來源，您可以提供額外的選項來自訂cdk migrate命令。

從 an 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 應用程式。
在包含您 migrated AWS CloudFormation 堆疊的 CDK 應用程式中建立堆疊。

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

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

從 an AWS CloudFormation 範本遷移

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

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


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

AWS CDK CLI 將執行下列動作：

擷取 local AWS CloudFormation 範本。
執行 cdk init 以初始化新的 CDK 應用程式。
在包含您 migrated AWS CloudFormation 範本的 CDK 應用程式中建立堆疊。

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

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

從 AWS SAM 範本遷移

若要從無 AWS 伺服器應用程式模型 (AWS SAM) 範本遷移，您必須先將其轉換為 an AWS CloudFormation 範本或部署以建立 an AWS CloudFormation 堆疊。

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

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

從部署的資源遷移

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


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

AWS CDK CLI 將執行下列動作：

掃描您的帳戶以取得資源和屬性詳細資訊 – AWS CDK CLI 利用 IaC 產生器來掃描您的帳戶並收集詳細資訊。
產生 an AWS CloudFormation 範本 – 掃描後， AWS CDK CLI 會使用 IaC 產生器來建立 an 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 資源的 ImageUri、 S3Bucket和 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 會使用此檔案來參考已部署的資源、將資源與 new AWS CloudFormation 堆疊建立關聯，以及刪除檔案。

管理和部署您的 CDK 應用程式

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

準備部署

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

合成您的應用程式

使用 cdk synth命令將 CDK 應用程式中的堆疊合成至 an 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 堆疊。您部署的資源將包含在 new AWS CloudFormation 堆疊中。

如果您從從未部署的 local AWS CloudFormation 範本遷移， AWS CDK CLI 將在部署時自動建立新的 AWS CloudFormation 堆疊。

如果您從先前部署的已部署 AWS CloudFormation 堆疊或 local AWS CloudFormation 範本遷移，您可以部署來建立新的 AWS CloudFormation 堆疊。若要建立新的堆疊，請執行下列動作：

部署到新的 AWS 環境。這包括使用不同的 AWS 帳戶或部署到不同的 AWS 區域。
如果您想要將新堆疊部署到已遷移堆疊或範本的相同 AWS 環境，則必須將 CDK 應用程式中的堆疊名稱修改為新的值。您還必須修改 CDK 應用程式中資源的所有邏輯 IDs。然後，您可以部署到相同的環境，以建立新的堆疊和新的資源。

部署以更新現有的 AWS CloudFormation 堆疊

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

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

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

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

文件慣用形式

從 AWS CDK v1 遷移至 AWS CDK v2

設定安全登入資料