從 AWS CDK v1 遷移至 AWS CDK v2

RSS

焦點模式

從 AWS CDK v1 遷移至 AWS CDK v2 - AWS Cloud Development Kit (AWS CDK) v2

新的先決條件從 AWS CDK v2 開發人員預覽版升級從 AWS CDK v1 遷移至 CDK v2 在部署之前測試遷移的應用程式故障診斷尋找 v1 堆疊

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

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

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

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

第 2 版 AWS Cloud Development Kit (AWS CDK) 的設計目的是讓編寫基礎設施做為您偏好程式設計語言中的程式碼更容易。本主題說明 v1 和 v2 之間的變更 AWS CDK。

提示

若要識別使用 AWS CDK v1 部署的堆疊，請使用 awscdk-v1-stack-finder 公用程式。

從 AWS CDK v1 到 CDK v2 的主要變更如下。

AWS CDK v2 將 AWS Construct Library 的穩定部分，包括核心程式庫，合併為單一套件 aws-cdk-lib。開發人員不再需要為他們使用的個別 AWS 服務安裝額外的套件。這種單一套件方法也表示您不需要同步各種 CDK 程式庫套件的版本。

代表中可用確切資源的 L1 (CfnXXXX) 建構一律視為穩定 AWS CloudFormation，因此會包含在中aws-cdk-lib。
實驗模組，其中我們仍在與社群合作開發新的 L2 或 L3 建構模組，不包含在中aws-cdk-lib。相反地，它們會以個別套件的形式分佈。實驗套件是以alpha尾碼和語意版本編號命名。語意版本編號符合第一個與其相容的 AWS 建構程式庫版本，以及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 的最終版本。不過，沒有 future AWS CDK 2.x 版本會中斷您的應用程式。
Construct 類別已從解壓縮 AWS CDK 到單獨的程式庫，以及相關的類型。這樣做是為了支援將建構程式設計模型套用至其他網域的工作。如果您要撰寫自己的建構或使用相關的 APIs，您必須宣告constructs模組為相依性，並對匯入進行次要變更。如果您使用的是進階功能，例如掛鉤至 CDK 應用程式生命週期，則可能需要更多變更。如需完整詳細資訊，請參閱 RFC。
已完全從 CDK AWS CDK v2 API 中移除 v1.x 及其建構程式庫中已取代的屬性、方法和類型。在大多數支援的語言中，這些 APIs會在 v1.x 下產生警告，因此您可能已遷移至替代 APIs。您可以在 GitHub 上取得 CDK v1.x 中已APIs 的完整清單。
依預設，CDK AWS CDK v2 中會啟用由 v1.x 中的特徵標記所鎖定的行為。不再需要先前的功能旗標，而且在大多數情況下都不支援。在非常特定的情況下，您仍然可以還原至 CDK v1 行為。如需詳細資訊，請參閱更新功能旗標。
使用 CDK v2，您部署到的環境必須使用現代引導堆疊進行引導。不再支援舊版引導堆疊 (v1 下的預設值）。此外，CDK v2 需要新版本的現代堆疊。若要升級現有環境，請重新引導它們。不再需要設定任何特徵標記或環境變數，即可使用現代引導堆疊。

重要

現代引導範本會有效地將隱含的許可授予--trust清單中--cloudformation-execution-policies的任何 AWS 帳戶。根據預設，這會擴展讀取和寫入引導帳戶中任何資源的許可。請務必使用您熟悉的政策和信任帳戶來設定引導堆疊。

新的先決條件

AWS CDK v2 的大多數需求與 v1 AWS CDK .x 相同。此處列出其他需求。

對於 TypeScript 開發人員，需要 TypeScript 3.8 或更新版本。
需要新版的 CDK Toolkit 才能與 CDK v2 搭配使用。現在 CDK v2 已全面推出，安裝 CDK Toolkit 時，v2 是預設版本。它與 CDK v1 專案回溯相容，因此除非您想要建立 CDK v1 專案，否則不需要保留舊版。若要升級，請發出 npm install -g aws-cdk。

從 AWS CDK v2 開發人員預覽版升級

如果您使用的是 CDK v2 開發人員預覽版，則專案中對的發行候選版本具有相依性 AWS CDK，例如 2.0.0-rc1。將這些更新為 2.0.0，然後更新專案中安裝的模組。

anchor anchor anchor anchor anchor anchor

npm install 或 yarn install

更新您的相依性後，npm update -g aws-cdk將 CDK Toolkit 更新至發行版本的問題。

從 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 使用 v1 或 v2，您都可以搭配所有 AWS CDK 專案使用單一全域安裝的 CDK Toolkit 版本。例外是 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。

anchor anchor


alias cdk1="npx aws-cdk@1.x"
alias cdk="npx aws-cdk@2.x"

更新相依性和匯入

更新應用程式的相依性，然後安裝新的套件。最後，更新程式碼中的匯入。

TypeScript

應用程式

對於 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 本身的生命週期取得提示，該生命週期已於 2022 年 6 月 1 日進入維護，並將在 2023 年 6 月 1 日end-of-life 如需完整詳細資訊，請參閱AWS CDK 維護政策。

程式庫和應用程式

透過執行 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

JavaScript

更新package.json如下。移除 v1 樣式個別穩定模組的相依性，並建立應用程式aws-cdk-lib所需的最低版本（此處為 2.0.0)。


{
  "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

Python

更新中的 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(...)

Java

在中pom.xml，移除穩定模組的所有software.amazon.awscdk相依性，並將其取代為 software.constructs（適用於 Construct) 和上的相依性software.amazon.awscdk。


<dependency>
    <groupId>software.amazon.awscdk</groupId>
    <artifactId>aws-cdk-lib</artifactId>
    <version>2.0.0</version>
</dependency><dependency>
    <groupId>software.amazon.awscdk</groupId>
    <artifactId>code-star-alpha</artifactId>
    <version>2.0.0-alpha.1</version>
</dependency>
<dependency>
    <groupId>software.constructs</groupId>
    <artifactId>constructs</artifactId>
    <version>10.0.0</version>
</dependency>

執行安裝新的相依性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#

升級 C# CDK 應用程式相依性最直接的方式，就是手動編輯.csproj檔案。移除所有穩定的Amazon.CDK.*套件參考，並將它們取代為 Amazon.CDK.Lib和 Constructs套件的參考。


<PackageReference Include="Amazon.CDK.Lib" Version="2.0.0" />
<PackageReference Include="Amazon.CDK.AWS.Codestar.Alpha" Version="2.0.0-alpha.1" />
<PackageReference Include="Constructs" Version="10.0.0" />

執行安裝新的相依性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

將相依性go get更新至最新版本並更新專案.mod檔案的問題。

anchor anchor anchor anchor anchor anchor

應用程式

對於 CDK 應用程式，更新package.json如下所示。移除 v1 樣式個別穩定模組的相依性，並建立應用程式aws-cdk-lib所需的最低版本（此處為 2.0.0)。


{
  "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"
  }
}

注意

程式庫和應用程式

透過執行 npm install或安裝新的相依性yarn install。


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

在部署之前測試遷移的應用程式

部署堆疊之前，請使用 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。

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

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

文件慣用形式

安全

遷移至 AWS CDK

下一個主題：

遷移至 AWS CDK

上一個主題：

安全

需要協助？

在本頁面

此頁面是否有幫助？

提供意見回饋

隱私權網站條款 Cookie 偏好設定

選取您的 Cookie 偏好設定

自訂 Cookie 偏好設定

必要

效能

功能

廣告

無法儲存 Cookie 偏好設定

從 AWS CDK v1 遷移至 AWS CDK v2

提示

重要

新的先決條件

從 AWS CDK v2 開發人員預覽版升級

從 AWS CDK v1 遷移至 CDK v2

更新至最近的 v1

更新功能旗標

CDK Toolkit 相容性

提示

更新相依性和匯入

應用程式

建構程式庫

注意

程式庫和應用程式

提示

應用程式

建構程式庫

注意

程式庫和應用程式

在部署之前測試遷移的應用程式

注意

故障診斷

TypeScript `'from' expected`或匯入`';' expected`錯誤

執行「cdk 引導」

尋找 v1 堆疊

下一個主題：

上一個主題：

需要協助？

在本頁面

此頁面是否有幫助？

選取您的 Cookie 偏好設定

從 AWS CDK v1 遷移至 AWS CDK v2

提示

重要

新的先決條件

從 AWS CDK v2 開發人員預覽版升級

從 AWS CDK v1 遷移至 CDK v2

更新至最近的 v1

更新功能旗標

CDK Toolkit 相容性

提示

更新相依性和匯入

應用程式

建構程式庫

注意

程式庫和應用程式

提示

應用程式

建構程式庫

注意

程式庫和應用程式

在部署之前測試遷移的應用程式

注意

故障診斷

TypeScript 'from' expected或匯入';' expected錯誤

執行「cdk 引導」

尋找 v1 堆疊

下一個主題：

上一個主題：

需要協助？

在本頁面

此頁面是否有幫助？

TypeScript `'from' expected`或匯入`';' expected`錯誤