這是 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
從 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 建構模組,不包含在 中
aws-cdk-lib。反之,它們會以個別套件的形式分發。實驗套件是以alpha尾碼和語意版本編號命名。語意版本編號符合第一個與其相容的 AWS Construct Library 版本,以及alpha尾碼。在指定為穩定aws-cdk-lib之後,建構會移入 ,以允許主要建構程式庫遵循嚴格的語意版本控制。穩定性是在服務層級指定。例如,如果我們開始為 Amazon AppFlow 建立一或多個 L2 建構,在此撰寫中只有 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。 -
AWS CDK v1.x 及其建構程式庫中的已棄用屬性、方法和類型已從 CDK v2 API 中完全移除。在大多數支援的語言中,這些 APIs會在 v1.x 下產生警告,因此您可能已經遷移到替代 APIs。您可以在 GitHub 上取得 CDK v1.x 中已APIs 的完整清單
。 -
AWS CDK v1.x 中的特徵標記所鎖定的行為預設為在 CDK v2 中啟用。不再需要先前的功能旗標,而且在大多數情況下都不支援。在非常特定的情況下,您仍然可以還原到 CDK v1 行為。如需詳細資訊,請參閱更新功能旗標。
-
使用 CDK v2,您部署到的環境必須使用現代引導堆疊進行引導。不再支援舊版引導堆疊 (v1 下的預設值)。此外,CDK v2 需要新版本的現代堆疊。若要升級現有的環境,請重新啟動它們。不再需要設定任何特徵標記或環境變數,即可使用現代引導堆疊。
重要
現代引導範本會有效地將 隱含的許可授予--trust清單中--cloudformation-execution-policies的任何 AWS 帳戶。根據預設,這會擴展讀取和寫入引導帳戶中任何資源的許可。請務必使用您熟悉的政策和信任帳戶來設定引導堆疊。
新的先決條件
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,然後更新專案中安裝的模組。
更新您的相依性後,將 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 上的旗標清單
-
@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 行為或 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 版本。
更新相依性和匯入
更新應用程式的相依性,然後安裝新的套件。最後,更新程式碼中的匯入。
在部署之前測試您的遷移應用程式
部署堆疊之前,請使用 cdk diff檢查資源是否有非預期的變更。不預期邏輯 IDs的變更 (造成資源的取代)。
預期的變更包括但不限於:
-
資源的變更
CDKMetadata。 -
已更新資產雜湊。
-
與新樣式堆疊合成相關的變更。如果您的應用程式在 v1 中使用舊版堆疊合成器,則適用。
-
新增
CheckBootstrapVersion規則。
意外的變更通常不是因為本身升級至 AWS CDK v2 所致。通常,它們是先前由特徵標記變更的已棄用行為的結果。這是從大約 1.85.x 之前的 CDK 版本升級的徵狀。您會看到相同的變更升級至最新的 v1.x 版本。您通常可以執行下列動作來解決此問題:
-
將您的應用程式升級至最新的 v1.x 版本
-
移除功能旗標
-
視需要修訂您的程式碼
-
部署
-
升級至 v2
注意
如果您的升級應用程式在兩階段升級後無法部署,請回報問題
當您準備好在應用程式中部署堆疊時,請考慮先部署複本,以便進行測試。最簡單的方法是將其部署到不同的 區域。不過,您也可以變更堆疊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 引導。
尋找 v1 堆疊
將 CDK 應用程式從 v1 遷移至 v2 時,您可能想要識別使用 v1 建立的已部署 AWS CloudFormation 堆疊。若要執行此操作,請執行下列命令:
npx awscdk-v1-stack-finder
如需用量詳細資訊,請參閱 awscdk-v1-stack-finder README