AWS CDKv2 への移行 - AWS Cloud Development Kit (AWS CDK) v2

これはAWS CDK v2 開発者ガイドです。古いCDK v1は2022年6月1日にメンテナンスを開始し、今後は重大なバグ修正とセキュリティパッチのみが提供されます。新機能はCDK v2専用に開発されます。CDK v1 Support は、2023 年 6 月 1 日に完全に終了します。

翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

AWS CDKv2 への移行

バージョン 2AWS Cloud Development Kit (AWS CDK) は、希望するプログラミング言語のコードとしてインフラストラクチャを簡単に記述できるように設計されています。このトピックでは、の v1 と v2 の変更点について説明しますAWS CDK。

ヒント

AWS CDKv1 でデプロイされたスタックを識別するには、awscdk-v1-stack-finder ユーティリティを使用してください。

AWS CDKv1 から CDK v2 への主な変更点は以下の通りです。

  • AWS CDKv2 は、AWSコアライブラリを含むコンストラクトライブラリの安定した部分を 1aws-cdk-lib つのパッケージに統合します。開発者は、AWS使用する個々のサービスに追加のパッケージをインストールする必要がなくなりました。この単一パッケージアプローチは、さまざまな CDK ライブラリパッケージのバージョンを同期する必要がないことも意味します。

    で使用可能なリソースをそのまま表す L1 (CFNxxXX) 構成はAWS CloudFormation、常に安定していると見なされるため、に含まれていますaws-cdk-lib

  • まだコミュニティと協力して新しい L2 または L3 コンストラクトを開発している実験モジュールは、に含まれていませんaws-cdk-lib。代わりに、それらは個別のパッケージとして配布されます。実験用パッケージには、alphaサフィックスとセマンティックバージョン番号が付けられています。セマンティックバージョン番号は、AWS互換性のあるコンストラクトライブラリの最初のバージョンと一致し、alphaサフィックスも付いています。aws-cdk-libコンストラクトは安定版に指定された後に移行されるため、メインのコンストラクトライブラリは厳密なセマンティックバージョン管理に従うことができます。

    安定性はサービスレベルで決まります。たとえば、Amazon 用に 1 つ以上の L2 コンストラクトを作成し始めると AppFlow、現時点ではL1コンストラクトしかありませんが、それらは最初にという名前のモジュールに表示されます@aws-cdk/aws-appflow-alpha。そして、aws-cdk-lib新しい構造が顧客の基本的なニーズを満たしていると私たちが感じたときに移ります。

    モジュールが安定版として指定され、組み込まれるとaws-cdk-lib、次のbullet 条書きで説明する「beTAN」規約を使用して新しい API が追加されます。

    各実験モジュールの新しいバージョンは、のリリースごとにリリースされますAWS CDK。ただし、ほとんどの場合、それらを同期させる必要はありません。aws-cdk-lib実験モジュールはいつでもアップグレードできます。ただし、2 つ以上の関連する実験モジュールが相互に依存している場合、それらは同じバージョンでなければならないという点です。

  • 新しい機能が追加される安定したモジュールでは、作業が進行している間、新しい API (まったく新しい構成でも、既存の構成の新しいメソッドやプロパティでも)Beta1 に接尾辞が付きます。(重大な変更が必要な場合はBeta2Beta3、、という順に続きます。) API が安定版に指定されると、サフィックスのないバージョンの API が追加されます。最新のもの (ベータ版か最終版かを問わず) を除くすべてのメソッドは廃止されます。

    たとえば、grantPower()コンストラクトに新しいメソッドを追加すると、最初は次のように表示されますgrantPowerBeta1()。重大な変更 (新しい必須パラメータやプロパティなど) が必要な場合は、grantPowerBeta2()メソッドの次のバージョンに名前が付けられます。作業が完了して API が完成すると、メソッドgrantPower() (サフィックスなし) が追加され、BetaN メソッドは廃止されます。

    すべてのベータ API は、次のメジャーバージョン (3.0) リリースまでConstruct Library に残り、そのシグネチャは変更されません。使用すると非推奨の警告が表示されるため、できるだけ早く API の最終バージョンに移行してください。ただし、future のAWS CDK 2.x リリースによってアプリケーションが動作しなくなることはありません。

  • Constructクラスは、AWS CDK関連するタイプとともに別のライブラリに抽出されました。これは、Construct Programming Modelを他のドメインに適用する取り組みを支援するために行われます。独自の構成を作成する場合や関連する API を使用する場合は、constructsモジュールを依存関係として宣言し、インポート内容に若干の変更を加える必要があります。CDK アプリライフサイクルへの接続などの高度な機能を使用している場合は、さらに変更が必要になる場合があります。詳細については、RFC を参照してください

  • AWS CDKv1.x およびその構成ライブラリで廃止されたプロパティ、メソッド、タイプは CDK v2 API から完全に削除されました。サポートされているほとんどの言語では、これらの API は v1.x で警告を生成するため、すでに代替の API に移行されている可能性があります。CDK v1.x で廃止された API の完全なリストについては、を参照してください GitHub。

  • AWS CDKv1.xの機能フラグによって制限されていた動作は、CDK v2ではデフォルトで有効になっています。以前の機能フラグは不要になり、ほとんどの場合サポートされていません。特定の状況下で CDK v1 の動作に戻せるように、まだいくつか用意されています。詳細については、「機能フラグを更新する」を参照してください。

  • CDK v2 では、デプロイ先の環境は最新のブートストラップスタックを使用してブートストラップする必要があります。従来のブートストラップスタック (v1 ではデフォルト) はサポートされなくなりました。CDK v2 にはさらに、最新スタックの新しいバージョンが必要です。既存の環境をアップグレードするには、それらを再ブートストラップします。最新のブートストラップスタックを使用するために、機能フラグや環境変数を設定する必要はなくなりました。

重要

最新のブートストラップテンプレートでは、AWS--trustによって暗示される権限がリスト内のどのアカウントにも効果的に付与されます。--cloudformation-execution-policiesデフォルトでは、これにより、ブートストラップアカウント内の任意のリソースに対する読み取りと書き込みの権限が拡張されます。ブートストラップスタックには、使い慣れたポリシーと信頼できるアカウントを設定してください

新しい前提条件

AWS CDKv2 のほとんどの要件はAWS CDK v1.x と同じです。その他の要件については、ここに一覧表示されます。

  • TypeScript 開発者には、 TypeScript 3.8 以降が必要です。

  • CDK v2 で使用するには、CDK ツールキットの新しいバージョンが必要です。CDK v2 が一般公開されたため、CDK Toolkit をインストールする際のデフォルトバージョンは v2 です。CDK v1 プロジェクトとの下位互換性があるため、CDK v1 プロジェクトを作成する場合を除いて、以前のバージョンをインストールしたままにしておく必要はありません。アップグレードするには、を発行してくださいnpm install -g aws-cdk

AWS CDKv2 開発者プレビューからのアップグレード

CDK v2 Developer Preview を使用している場合は、AWS CDK2.0.0-rc1などのリリース候補バージョンに依存するプロジェクトがあります。これらをに更新してから2.0.0、プロジェクトにインストールされているモジュールを更新します。

TypeScript

npm install 、または yarn install

JavaScript

npm install 、、または yarn install

Python
python -m pip install -r requirements.txt
Java
mvn package
C#
dotnet restore
Go
go get

依存関係を更新したら、CDK Toolkitnpm update -g aws-cdk を発行してリリースバージョンに更新します。

AWS CDKv1 から CDK v2 への移行

アプリをAWS CDK v2 に移行するには、cdk.jsonまず内の機能フラグを更新します。次に、アプリの依存関係を更新し、アプリが記述されているプログラミング言語に合わせて必要に応じてインポートします。

機能フラグを更新する

v1 の機能フラグはAWS CDK v2 ではデフォルトですべてアクティブになっているため、cdk.jsonからすべて削除します。

特定の v1 動作に戻すために、falseいくつかのAWS CDK v1 機能フラグを設定できます。フラグ付き機能の無効化詳細なリストについては、を参照してください。cdk diffコマンドを使用して合成テンプレートへの変更を調べ、これらのフラグのいずれかが必要かどうかを確認します。

CDK Toolkit との互換性

CDK v2 には、v2 以降の CDK ツールキットが必要です。このバージョンは CDK v1 アプリとの下位互換性があります。そのため、グローバルにインストールされた単一バージョンの CDK Toolkit を、v1 か v2 かを問わず、AWS CDKすべてのプロジェクトで使用できます。ただし、CDK ツールキット v2 では CDK v2 プロジェクトのみが作成されます。

v1 と v2 の CDK プロジェクトの両方を作成する必要がある場合は、CDK Toolkit v2 をグローバルにインストールしないでください。 (npm remove -g aws-cdk既にインストールされている場合は削除してください:.) CDK ツールキットを呼び出すには、npxを使用して CDK ツールキットの v1 または v2 を必要に応じて実行します。

npx aws-cdk@1.x init app --language typescript npx aws-cdk@2.x init app --language typescript
ヒント

cdkcdk1およびコマンドを使用して目的のバージョンの CDK Toolkit を呼び出すことができるように、コマンドラインエイリアスを設定します。

macOS/Linux
alias cdk1="npx aws-cdk@1.x" alias cdk="npx aws-cdk@2.x"
Windows
doskey cdk1=npx aws-cdk@1.x $* doskey cdk=npx aws-cdk@2.x $*

依存関係とインポートの更新

アプリの依存関係を更新してから、新しいパッケージをインストールします。最後に、コード内のインポートを更新します。

TypeScript
アプリケーション

CDK アプリの場合、package.json次のように更新します。v1スタイルの個々の安定モジュールへの依存関係を取り除き、アプリケーションに必要な最低バージョン(ここでは2.0.0)を確立します。aws-cdk-lib

実験用コンストラクトは、名前の末尾がでアルファバージョン番号が付いたalpha、独立したバージョン管理された個別のパッケージで提供されます。アルファバージョン番号は、互換性のある最初のリリースに対応しています。aws-cdk-libここでは v2.0.0-alpha.1aws-codestar にピン留めしています。

{ "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 の両方を 1 つのライブラリでサポートすることはできません。v1 をまだ使用しているお客様を引き続きサポートするには、以前のリリースをparallel 保守するか、v2 用の新しいパッケージを作成します。

AWS CDKv1 のお客様をどのくらいの期間サポートし続けるかはあなた次第です。2022年6月1日にメンテナンスが開始され、2023年6月1日にリリースされるCDK v1自体のライフサイクルからヒントを得るかもしれません。 end-of-life 詳細については、「AWS CDKメンテナンスポリシー」を参照してください。

ライブラリとアプリの両方

npm installまたはを実行して、yarn install新しい依存関係をインストールします。

Constructインポートは、constructs使用するサービスの新しいモジュール、トップレベルなどのコアタイプ、AppStackおよび以下の名前空間から使用するサービスの安定した Construct Libraryaws-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スタイルの個々の安定モジュールへの依存関係を取り除き、アプリケーションに必要な最低バージョン(ここでは2.0.0)を確立します。aws-cdk-lib

実験用コンストラクトは、名前の末尾がでアルファバージョン番号が付いたalpha、独立したバージョン管理された個別のパッケージで提供されます。アルファバージョン番号は、互換性のある最初のリリースに対応しています。aws-cdk-libここでは v2.0.0-alpha.1aws-codestar にピン留めしています。

{ "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新しい依存関係をインストールします。

アプリのインポートを変更して、以下の操作を行います。

  • Constructconstructs新しいモジュールからインポート

  • AppStackやなどのコアタイプをのトップレベルからインポートします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.txtinstall_requiressetup.py以下のように定義を更新します。v1スタイルの個々の安定版モジュールへの依存関係を削除します。

実験用コンストラクトは、名前の末尾がでアルファバージョン番号が付いたalpha、独立したバージョン管理された個別のパッケージで提供されます。アルファバージョン番号は、互換性のある最初のリリースに対応しています。aws-cdk-libここでは、v2.0.0alpha1aws-codestar にピン留めしています。

install_requires=[ "aws-cdk-lib>=2.0.0", "constructs>=10.0.0", "aws-cdk.aws-codestar-alpha>=2.0.0alpha1", # ... ],
ヒント

を使用して、AWS CDKpip uninstallアプリの仮想環境に既にインストールされている他のバージョンのモジュールをアンインストールします。次に、python -m pip install -r requirements.txtを使用して新しい依存関係をインストールします。

アプリのインポートを変更して、以下の操作を行います。

  • Constructconstructs新しいモジュールからインポート

  • AppStackやなどのコアタイプをのトップレベルからインポートします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.xmlsoftware.amazon.awscdk安定版モジュールの依存関係をすべて削除し、software.constructs (forConstruct) とへの依存関係に置き換えますsoftware.amazon.awscdk

実験用コンストラクトは、名前の末尾がでアルファバージョン番号が付いたalpha、独立したバージョン管理された個別のパッケージで提供されます。アルファバージョン番号は、互換性のある最初のリリースに対応しています。aws-cdk-libここでは v2.0.0-alpha.1aws-codestar にピン留めしています。

<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新しい依存関係をインストールします。

以下の操作を実行するようにコードを変更します。

  • Constructsoftware.constructs新しいライブラリからインポート

  • StackAppやなどのコアクラスのインポート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.LibConstructsおよびパッケージへの参照に置き換えます。

実験用コンストラクトは、名前の末尾がでアルファバージョン番号が付いたalpha、独立したバージョン管理された個別のパッケージで提供されます。アルファバージョン番号は、互換性のある最初のリリースに対応しています。aws-cdk-libここでは v2.0.0-alpha.1aws-codestar にピン留めしています。

<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プロジェクトのファイルを更新します。

デプロイ前に移行したアプリケーションをテストする

スタックをデプロイする前に、cdk diffを使用してリソースに予期しない変更がないか確認してください。論理 ID の変更 (リソースの置換の原因となる) は想定されていません

考えられる変更を次に示します (ただし、これらに限定されるものではありません)。

  • CDKMetadataリソースへの変更。

  • アセットハッシュを更新しました。

  • 新しいスタイルのスタック合成に関する変更。アプリが v1 のレガシースタックシンセサイザーを使用した場合に適用されます。(CDK v2 は従来のスタックシンセサイザーをサポートしていません)。

  • CheckBootstrapVersionルールの追加。

通常、AWS CDK v2 へのアップグレード自体によって予期しない変更が発生することはありません。通常、これらは以前に機能フラグによって変更された、非推奨の動作の結果です。これは、約1.85.xより前のバージョンのCDKからアップグレードした場合の症状です。最新の v1.x リリースにアップグレードしても同じ変更が表示されます。通常は、次の手順を実行することで解決できます。

  1. アプリを最新の v1.x リリースにアップグレード

  2. 機能フラグを削除する

  3. 必要に応じてコードを修正してください

  4. デプロイ

  5. v2 にアップグレード

注記

2 段階のアップグレード後にアップグレードしたアプリがデプロイできない場合は、問題を報告してください

スタックをアプリにデプロイする準備ができたら、テストできるようにまずコピーをデプロイすることを検討してください。そのための最も簡単な方法は、別のリージョンにデプロイすることです。ただし、スタックの ID を変更することもできます。テスト後は、テストコピーを必ずで破棄してください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 CDKv2 ではブートストラップスタックを更新する必要があります。さらに、すべての v2 デプロイメントにはブートストラップリソースが必要です。(v1 では、ブートストラップなしでシンプルなスタックをデプロイできました。) 詳細については、「ブートストラッピング」を参照してください。

v1 スタックの検索

CDK アプリケーションを v1 から v2 に移行する場合、v1AWS CloudFormation を使用して作成されたデプロイ済みスタックを特定したい場合があります。これを行うには、以下のコマンドを実行します。

npx awscdk-v1-stack-finder

使用方法の詳細については、awscdk-v1-スタックファインダーの README を参照してください。