這是 AWS CDK v2 開發人員指南。較舊的 CDK v1 已於 2022 年 6 月 1 日進入維護，並於 2023 年 6 月 1 日結束支援。 本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 從 AWS CDK v1 遷移至 AWS CDK v2 第 2 版的 AWS 雲端開發套件 (AWS CDK) 旨在讓您以偏好的程式設計語言將基礎設施編寫為程式碼。本主題說明 AWS CDK v1 和 v2 之間的變更。 **提示** 若要識別使用 AWS CDK v1 部署的堆疊，請使用 [awscdk-v1-stack-finder](https://www.npmjs.com/package/awscdk-v1-stack-finder) 公用程式。 從 AWS CDK v1 到 CDK v2 的主要變更如下。 + AWS CDK v2 將 AWS Construct Library 的穩定部分，包括核心程式庫，合併為單一套件 `aws-cdk-lib`。開發人員不再需要為他們使用的個別 AWS 服務安裝額外的套件。這種單一套件方法也表示您不需要同步各種 CDK 程式庫套件的版本。 代表 AWS CloudFormation 中可用確切資源的 L1 (CfnXXXX) 建構一律視為穩定，因此會包含在 中`aws-cdk-lib`。 + 實驗模組，其中我們仍在與社群合作開發新的 [L2 或 L3 建構](constructs.md#constructs-lib-levels)模組，不包含在 中`aws-cdk-lib`。反之，它們會以個別套件的形式分發。實驗套件是以`alpha`尾碼和語意版本編號命名。語意版本編號符合第一個與其相容的 AWS Construct Library 版本，以及`alpha`尾碼。在指定為穩定`aws-cdk-lib`之後，建構會移入 ，以允許主要建構程式庫遵循嚴格的語意版本控制。 穩定性是在服務層級指定。例如，如果我們開始為 Amazon AppFlow 建立一或多個 [L2 建構，](constructs.md#constructs-lib-levels)在此撰寫中只有 L1 建構，它們首先會出現在名為 的模組中`@aws-cdk/aws-appflow-alpha`。然後，當我們覺得新的建構符合客戶的基本需求`aws-cdk-lib`時，它們會移至 。 一旦模組被指定為穩定且併入 `aws-cdk-lib`，就會使用下一個項目符號所述的「BetaN」慣例來新增新的 APIs。 每個實驗模組的新版本都會隨著 AWS CDK 的每個版本發佈。不過，在大多數情況下，它們不需要保持同步。您可以視需要隨時升級 `aws-cdk-lib`或 實驗模組。例外是，當兩個或多個相關的實驗模組彼此相依時，它們必須是相同的版本。 + 對於要新增新功能的穩定模組，新的 APIs （無論是全新的建構，還是現有建構上的新方法或屬性） 都會在工作進行時收到`Beta1`尾碼。（在需要重大變更時`Beta2`，遵循 `Beta3`、 等。) 指定穩定 API 時，會新增不含尾碼的 API 版本。然後，除最新 （無論 Beta 版或最終版） 以外的所有方法都會被取代。 例如，如果我們將新方法新增至`grantPower()`建構，它一開始會顯示為 `grantPowerBeta1()`。如果需要重大變更 （例如，新的必要參數或屬性），則方法的下一個版本會命名為 `grantPowerBeta2()`，以此類推。當工作完成且 API 完成時，會新增方法 `grantPower()`（不含尾碼），並取代 BetaN 方法。 所有 Beta APIs都會保留在 Construct Library 中，直到下一個主要版本 (3.0) 版本為止，而且其簽章不會變更。如果您使用，將會看到棄用警告，因此您應該盡快移至 API 的最終版本。不過，未來的 AWS CDK 2.x 版本不會中斷您的應用程式。 + `Construct` 類別已從 AWS CDK 解壓縮到單獨的程式庫，以及相關的類型。這樣做是為了支援將建構程式設計模型套用至其他網域的工作。如果您要撰寫自己的建構或使用相關的 APIs，您必須將`constructs`模組宣告為相依性，並對匯入進行次要變更。如果您使用的是進階功能，例如連接至 CDK 應用程式生命週期，則可能需要更多變更。如需完整詳細資訊，[請參閱 RFC](https://github.com/aws/aws-cdk-rfcs/blob/master/text/0192-remove-constructs-compat.md#release-notes)。 + AWS CDK v1.x 及其建構程式庫中的已棄用屬性、方法和類型已從 CDK v2 API 中完全移除。在大多數支援的語言中，這些 APIs會在 v1.x 下產生警告，因此您可能已經遷移到替代 APIs。您可以在 GitHub 上取得 CDK v1.x [中已APIs 的完整清單](https://github.com/aws/aws-cdk/blob/master/DEPRECATED_APIs.md)。 + AWS CDK v1.x 中的特徵標記所鎖定的行為預設為在 CDK v2 中啟用。不再需要先前的功能旗標，而且在大多數情況下都不支援。在非常特定的情況下，您仍然可以還原到 CDK v1 行為。如需詳細資訊，請參閱[更新功能旗標](#migrating-v2-v1-upgrade-cdk-json)。 + 使用 CDK v2，您部署到的環境必須使用現代引導堆疊進行引導。不再支援舊版引導堆疊 (v1 下的預設值）。此外，CDK v2 需要新版本的現代堆疊。若要升級現有的環境，請重新啟動它們。不再需要設定任何特徵標記或環境變數，即可使用現代引導堆疊。 **重要** 現代引導範本會有效地將 隱含的許可授予`--trust`清單中`--cloudformation-execution-policies`的任何 AWS 帳戶。根據預設，這會擴展讀取和寫入引導帳戶中任何資源的許可。請務必使用您熟悉的政策和信任帳戶來[設定引導堆疊](bootstrapping-customizing.md)。 ## 新的先決條件 AWS CDK v2 的大多數需求與 AWS CDK v1.x 相同。此處列出其他要求。 + 對於 TypeScript 開發人員，需要 TypeScript 3.8 或更新版本。 + 需要新版本的 CDK Toolkit 才能與 CDK v2 搭配使用。現在 CDK v2 已全面推出，v2 是安裝 CDK Toolkit 時的預設版本。它與 CDK v1 專案回溯相容，因此除非您想要建立 CDK v1 專案，否則不需要保留舊版的安裝。若要升級，請發出 `npm install -g aws-cdk`。 ## 從 AWS CDK v2 開發人員預覽版升級 如果您使用的是 CDK v2 開發人員預覽版，則專案中對 AWS CDK 的發行候選版本具有相依性，例如 `2.0.0-rc1`。將這些更新為 `2.0.0`，然後更新專案中安裝的模組。 **Example** `npm install` 或 `yarn install` `npm install` 或 `yarn install` ``` python -m pip install -r requirements.txt ``` ``` mvn package ``` ``` dotnet restore ``` ``` go get ``` 更新您的相依性後，將 CDK Toolkit `npm update -g aws-cdk`更新至發行版本的問題。 ## 從 AWS CDK v1 遷移至 CDK v2 若要將應用程式遷移至 AWS CDK v2，請先更新 中的功能旗標`cdk.json`。然後，更新應用程式的相依性，並視需要匯入其寫入的程式設計語言。 ### 更新至最近的 v1 我們看到許多客戶在一個步驟中從舊版本的 AWS CDK v1 升級到最新版本的 v2。雖然可以這樣做，但您會跨多年的變更進行升級 （不幸的是，並非所有 都有相同的進化測試量），以及使用新的預設值和不同的程式碼組織跨版本升級。 為了獲得最安全的升級體驗，並更輕鬆地診斷任何意外變更的來源，我們建議您分開這兩個步驟：首先升級至最新的 v1 版本，然後切換到 v2。 ### 更新功能旗標 `cdk.json` 如果下列 v1 功能旗標存在，請將其從 中移除，因為這些都是 AWS CDK v2 預設作用中的。如果舊效果對您的基礎設施很重要，您將需要變更原始程式碼。如需詳細資訊[，請參閱 GitHub 上的旗標清單](https://github.com/aws/aws-cdk/blob/main/packages/%40aws-cdk/cx-api/FEATURE_FLAGS.md)。 + `@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 行為](featureflags.md#featureflags-disabling)或 GitHub 上的清單。 對於這兩種類型的旗標，請使用 `cdk diff`命令來檢查合成範本的變更，以查看這些旗標的變更是否會影響您的基礎設施。 ### CDK Toolkit 相容性 CDK v2 需要 CDK Toolkit 的 v2 或更新版本。此版本與 CDK v1 應用程式回溯相容。因此，您可以將單一全域安裝的 CDK Toolkit 版本與所有 AWS CDK 專案搭配使用，無論它們是使用 v1 還是 v2。例外是 CDK Toolkit v2 只會建立 CDK v2 專案。 如果您需要同時建立 v1 和 v2 CDK 專案，**請勿全域安裝 CDK Toolkit v2。**（如果您已安裝它，請將其移除：)`npm remove -g aws-cdk`。若要叫用 CDK Toolkit，請視需要使用 `npx`來執行 CDK Toolkit 的 v1 或 v2。 ``` npx aws-cdk@1.x init app --language typescript npx aws-cdk@2.x init app --language typescript ``` **提示** 設定命令列別名，以便您可以使用 `cdk`和 `cdk1`命令叫用所需的 CDK Toolkit 版本。 ``` alias cdk1="npx aws-cdk@1.x" alias cdk="npx aws-cdk@2.x" ``` ``` doskey cdk1=npx aws-cdk@1.x $* doskey cdk=npx aws-cdk@2.x $* ``` ### 更新相依性和匯入 更新應用程式的相依性，然後安裝新的套件。最後，更新程式碼中的匯入。 **Example** **應用程式** 對於 CDK 應用程式，更新`package.json`如下所示。移除 v1 樣式個別穩定模組的相依性，並建立應用程式`aws-cdk-lib`所需的最低版本 （此處為 2.0.0)。 實驗建構是以個別、獨立版本控制的套件提供，名稱結尾為 `alpha`和 alpha 版本編號。Alpha 版本編號對應至`aws-cdk-lib`與其相容的 的第一個版本。在這裡，我們鎖定`aws-codestar`了 v2.0.0-alpha.1。 ``` { "dependencies": { "aws-cdk-lib": "^2.0.0", "@aws-cdk/aws-codestar-alpha": "2.0.0-alpha.1", "constructs": "^10.0.0" } } ``` **建構程式庫** 對於建構程式庫，請建立應用程式`aws-cdk-lib`所需的最低版本 （此處為 2.0.0)，並`package.json`更新，如下所示。 請注意， 同時`aws-cdk-lib`顯示為對等相依性和開發相依性。 ``` { "peerDependencies": { "aws-cdk-lib": "^2.0.0", "constructs": "^10.0.0" }, "devDependencies": { "aws-cdk-lib": "^2.0.0", "constructs": "^10.0.0", "typescript": "~3.9.0" } } ``` 您應該在發行 v2 相容程式庫時，在程式庫的版本編號上執行主要版本凸點，因為這是程式庫取用者的重大變更。無法使用單一程式庫同時支援 CDK v1 和 v2。若要繼續支援仍在使用 v1 的客戶，您可以平行維護較早的版本，或為 v2 建立新的套件。 這取決於您希望繼續支援 AWS CDK v1 客戶的時間長度。您可能會從 CDK v1 本身的生命週期中獲得提示，CDK v1 本身已於 2022 年 6 月 1 日進入維護，並在 2023 年 6 月 1 日達到end-of-life。如需完整詳細資訊，請參閱 [AWS CDK 維護政策](https://github.com/aws/aws-cdk-rfcs/blob/master/text/0079-cdk-2.0.md#aws-cdk-maintenance-policy)。 **程式庫和應用程式** 透過執行 `npm install`或 安裝新的相依性`yarn install`。 變更匯入以`Construct`從新`constructs`模組匯入、`Stack`從頂層 匯入 `App` 和 等核心類型`aws-cdk-lib`，以及從 下命名空間使用之服務的穩定建構程式庫模組`aws-cdk-lib`。 ``` import { Construct } from 'constructs'; import { App, Stack } from 'aws-cdk-lib'; // core constructs import { aws_s3 as s3 } from 'aws-cdk-lib'; // stable module import * as codestar from '@aws-cdk/aws-codestar-alpha'; // experimental module ``` `package.json` 更新如下所示。移除 v1 樣式個別穩定模組的相依性，並建立應用程式`aws-cdk-lib`所需的最低版本 （此處為 2.0.0)。 實驗建構是以個別、獨立版本控制的套件提供，名稱結尾為 `alpha`和 alpha 版本編號。alpha 版本編號對應至`aws-cdk-lib`與其相容的 的第一個版本。在這裡，我們鎖定`aws-codestar`了 v2.0.0-alpha.1。 ``` { "dependencies": { "aws-cdk-lib": "^2.0.0", "@aws-cdk/aws-codestar-alpha": "2.0.0-alpha.1", "constructs": "^10.0.0" } } ``` 透過執行 `npm install`或 安裝新的相依性`yarn install`。 變更應用程式的匯入以執行下列動作： + `Construct` 從新`constructs`模組匯入 + 從 的最上層匯入核心類型`Stack`，例如 `App`和 。 `aws-cdk-lib` + 從 下的命名空間匯入 AWS 建構程式庫模組 `aws-cdk-lib` ``` const { Construct } = require('constructs'); const { App, Stack } = require('aws-cdk-lib'); // core constructs const s3 = require('aws-cdk-lib').aws_s3; // stable module const codestar = require('@aws-cdk/aws-codestar-alpha'); // experimental module ``` 更新 中的 `requirements.txt`或 `install_requires`定義`setup.py`，如下所示。移除 v1 樣式個別穩定模組的相依性。 實驗建構是以個別、獨立版本控制的套件提供，名稱結尾為 `alpha`和 alpha 版本編號。alpha 版本編號對應至`aws-cdk-lib`與其相容的 的第一個版本。在這裡，我們鎖定`aws-codestar`了 v2.0.0alpha1。 ``` install_requires=[ "aws-cdk-lib>=2.0.0", "constructs>=10.0.0", "aws-cdk.aws-codestar-alpha>=2.0.0alpha1", # ... ], ``` 使用 解除安裝已在應用程式的虛擬環境中安裝的任何其他 AWS CDK 模組版本`pip uninstall`。然後使用 安裝新的相依性`python -m pip install -r requirements.txt`。 變更應用程式的匯入以執行下列動作： + `Construct` 從新`constructs`模組匯入 + 從 的最上層匯入核心類型`Stack`，例如 `App`和 。 `aws_cdk` + 從 下的命名空間匯入 AWS 建構程式庫模組 `aws_cdk` ``` from constructs import Construct from aws_cdk import App, Stack # core constructs from aws_cdk import aws_s3 as s3 # stable module import aws_cdk.aws_codestar_alpha as codestar # experimental module # ... class MyConstruct(Construct): # ... class MyStack(Stack): # ... s3.Bucket(...) ``` 在 中`pom.xml`，移除穩定模組的所有`software.amazon.awscdk`相依性，並將其取代為 `software.constructs`（適用於 `Construct`) 和 上的相依性`software.amazon.awscdk`。 實驗建構是以個別、獨立版本控制的套件提供，名稱結尾為 `alpha`和 alpha 版本編號。alpha 版本編號對應至`aws-cdk-lib`與其相容的 的第一個版本。在這裡，我們鎖定`aws-codestar`了 v2.0.0-alpha.1。 ``` software.amazon.awscdk aws-cdk-lib 2.0.0 software.amazon.awscdk code-star-alpha 2.0.0-alpha.1 software.constructs constructs 10.0.0 ``` 執行 安裝新的相依性`mvn package`。 變更您的程式碼以執行下列動作： + `Construct` 從新`software.constructs`程式庫匯入 + 從 匯入核心類別，例如 `Stack`和 `App`。 `software.amazon.awscdk` + 從 匯入服務建構 `software.amazon.awscdk.services` ``` import software.constructs.Construct; import software.amazon.awscdk.Stack; import software.amazon.awscdk.StackProps; import software.amazon.awscdk.App; import software.amazon.awscdk.services.s3.Bucket; import software.amazon.awscdk.services.codestar.alpha.GitHubRepository; ``` 升級 C\$1 CDK 應用程式相依性最直接的方式，就是手動編輯`.csproj`檔案。移除所有穩定的`Amazon.CDK.*`套件參考，並將其取代為 `Amazon.CDK.Lib`和 `Constructs`套件的參考。 實驗建構是以個別、獨立版本控制的套件提供，名稱結尾為 `alpha`和 alpha 版本編號。alpha 版本編號對應至`aws-cdk-lib`與其相容的 的第一個版本。在這裡，我們鎖定`aws-codestar`了 v2.0.0-alpha.1。 ``` ``` 透過執行 安裝新的相依性`dotnet restore`。 變更來源檔案中的匯入，如下所示。 ``` using Constructs; // for Construct class using Amazon.CDK; // for core classes like App and Stack using Amazon.CDK.AWS.S3; // for stable constructs like Bucket using Amazon.CDK.Codestar.Alpha; // for experimental constructs ``` 將相依性`go get`更新至最新版本並更新專案`.mod`檔案的問題。 ## 在部署之前測試您的遷移應用程式 部署堆疊之前，請使用 `cdk diff`檢查資源是否有非預期的變更。**不**預期邏輯 IDs的變更 （造成資源的取代）。 預期的變更包括但不限於： + 資源的變更`CDKMetadata`。 + 已更新資產雜湊。 + 與新樣式堆疊合成相關的變更。如果您的應用程式在 v1 中使用舊版堆疊合成器，則適用。 + 新增`CheckBootstrapVersion`規則。 意外的變更通常不是因為本身升級至 AWS CDK v2 所致。通常，它們是先前由特徵標記變更的已棄用行為的結果。這是從大約 1.85.x 之前的 CDK 版本升級的徵狀。您會看到相同的變更升級至最新的 v1.x 版本。您通常可以執行下列動作來解決此問題： 1. 將您的應用程式升級至最新的 v1.x 版本 1. 移除功能旗標 1. 視需要修訂您的程式碼 1. 部署 1. 升級至 v2 **注意** 如果您的升級應用程式在兩階段升級後無法部署，[請回報問題](https://github.com/aws/aws-cdk/issues/new/choose)。 當您準備好在應用程式中部署堆疊時，請考慮先部署複本，以便進行測試。最簡單的方法是將其部署到不同的 區域。不過，您也可以變更堆疊IDs。測試之後，請務必使用 銷毀測試複本`cdk destroy`。 ## 故障診斷 **TypeScript `'from' expected`或匯入中的`';' expected`錯誤** 升級至 TypeScript 3.8 或更新版本。 **執行 'cdk 引導程式'** 如果您看到類似以下的錯誤： ``` ❌ 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 引導](bootstrapping.md)。 ## 尋找 v1 堆疊 將 CDK 應用程式從 v1 遷移至 v2 時，您可能想要識別使用 v1 建立的已部署 AWS CloudFormation 堆疊。若要執行此操作，請執行下列命令： ``` npx awscdk-v1-stack-finder ``` 如需用量詳細資訊，請參閱 awscdk-v1-stack-finder [README](https://github.com/cdklabs/awscdk-v1-stack-finder/blob/main/README.md)。