これは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コアライブラリを含むコンストラクトライブラリの安定した部分を 1
aws-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
に接尾辞が付きます。(重大な変更が必要な場合はBeta2
Beta3
、、という順に続きます。) 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
、プロジェクトにインストールされているモジュールを更新します。
依存関係を更新したら、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 を呼び出すことができるように、コマンドラインエイリアスを設定します。
依存関係とインポートの更新
アプリの依存関係を更新してから、新しいパッケージをインストールします。最後に、コード内のインポートを更新します。
デプロイ前に移行したアプリケーションをテストする
スタックをデプロイする前に、cdk diff
を使用してリソースに予期しない変更がないか確認してください。論理 ID の変更 (リソースの置換の原因となる) は想定されていません。
考えられる変更を次に示します (ただし、これらに限定されるものではありません)。
-
CDKMetadata
リソースへの変更。 -
アセットハッシュを更新しました。
-
新しいスタイルのスタック合成に関する変更。アプリが v1 のレガシースタックシンセサイザーを使用した場合に適用されます。(CDK v2 は従来のスタックシンセサイザーをサポートしていません)。
-
CheckBootstrapVersion
ルールの追加。
通常、AWS CDK v2 へのアップグレード自体によって予期しない変更が発生することはありません。通常、これらは以前に機能フラグによって変更された、非推奨の動作の結果です。これは、約1.85.xより前のバージョンのCDKからアップグレードした場合の症状です。最新の v1.x リリースにアップグレードしても同じ変更が表示されます。通常は、次の手順を実行することで解決できます。
アプリを最新の v1.x リリースにアップグレード
機能フラグを削除する
-
必要に応じてコードを修正してください
デプロイ
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