これは AWS CDK v2 デベロッパーガイドです。古い CDK v1 は 2022 年 6 月 1 日にメンテナンスを開始し、2023 年 6 月 1 日にサポートを終了しました。
翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
AWS CDK v1 から AWS CDK v2 への移行
のバージョン 2 AWS Cloud Development Kit (AWS CDK) は、希望するプログラミング言語でのコードとしてのインフラストラクチャの記述を容易にするように設計されています。このトピックでは、 の v1 と v2 の間の変更について説明します AWS CDK。
ヒント
AWS CDK v1 でデプロイされたスタックを特定するには、awscdk-v1-stack-f Finder
AWS CDK v1 から CDK v2 への主な変更は次のとおりです。
-
AWS CDK v2 は、コアライブラリを含む 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
後に に移行し、メインコンストラクタライブラリが厳密なセマンティックバージョニングに準拠できるようにします。安定性はサービスレベルで指定されます。例えば、この書き込みでは L1 コンストラクトのみを持つ Amazon の 1 つ以上の L2 コンストラクトの作成を開始した場合、それらはまず という名前のモジュールに表示されます
@aws-cdk/aws-appflow-alpha
。 AppFlow L1 その後、新しいコンストラクトが顧客の基本的なニーズを満たすと思われるaws-cdk-lib
とき、 に移行します。モジュールが安定していると指定され、 に組み込まれると
aws-cdk-lib
、次の箇条書きで説明するAPIs が追加されます。 BetaN各実験モジュールの新しいバージョンは、 のすべてのリリースでリリースされます AWS CDK。ただし、ほとんどの場合、同期しておく必要はありません。
aws-cdk-lib
または実験的なモジュールはいつでもアップグレードできます。ただし、2 つ以上の関連する実験モジュールが相互に依存している場合、同じバージョンである必要があります。 -
新しい機能が追加されている安定したモジュールの場合、新しい APIs (まったく新しいコンストラクトでも、既存のコンストラクトの新しいメソッドやプロパティでも)
Beta1
は作業の進行中にサフィックスを受け取ります。(重大な変更が必要な場合はBeta3
、、Beta2
などによって実行されます。) サフィックスのない API のバージョンは、API が安定していると指定されたときに追加されます。その後、最新の (ベータ版または最終版) を除くすべてのメソッドが廃止されます。例えば、コンストラクト
grantPower()
に新しいメソッドを追加すると、最初は と表示されますgrantPowerBeta1()
。重大な変更が必要な場合 (例えば、新しい必須パラメータまたはプロパティ)grantPowerBeta2()
、次のバージョンのメソッドには という名前が付けられます。作業が完了し、API が確定されると、 メソッドgrantPower()
(サフィックスなし) が追加され、BetaN メソッドは非推奨になります。すべてのベータ APIs、次のメジャーバージョン (3.0) リリースまで Construct Library に残り、署名は変更されません。使用した場合は非推奨の警告が表示されるため、できるだけ早く API の最終バージョンに移行する必要があります。ただし、今後の AWS CDK 2.x リリースではアプリケーションが破損することはありません。
-
Construct
クラスは、 から、関連するタイプとともに別のライブラリ AWS CDK に抽出されています。これは、構成プログラミングモデルを他のドメインに適用する作業をサポートするために行われます。独自のコンストラクトを記述する場合、または関連する APIsを使用する場合は、constructs
モジュールを依存関係として宣言し、インポートにわずかな変更を加える必要があります。CDK アプリのライフサイクルへのフックなどの高度な機能を使用している場合は、さらに多くの変更が必要になる場合があります。詳細については、「RFC」を参照してください。 -
AWS CDK v1.x とそのコンストラクトライブラリの非推奨プロパティ、メソッド、タイプは CDK v2 API から完全に削除されました。サポートされているほとんどの言語では、これらの APIs v1.x で警告を生成するため、代替 APIsに既に移行している可能性があります。CDK v1.x の非推奨 APIs の完全なリスト
は、 で入手できます GitHub。 -
AWS CDK v1.x の特徴フラグによってゲートされた動作は、CDK v2 ではデフォルトで有効になっています。以前の機能フラグはもう必要ではなく、ほとんどの場合はサポートされません。いくつかの は、非常に特定の状況でも CDK v1 の動作に戻すことができます。詳細については、「機能フラグの更新」を参照してください。
-
CDK v2 では、 にデプロイする環境は、最新のブートストラップスタックを使用してブートストラップする必要があります。レガシーブートストラップスタック (v1 のデフォルト) はサポートされなくなりました。CDK v2 では、最新のスタックの新しいバージョンがさらに必要になりました。既存の環境をアップグレードするには、環境を再ブートストラップします。最新のブートストラップスタックを使用するために、機能フラグや環境変数を設定する必要がなくなりました。
重要
最新のブートストラップテンプレートは、 によって暗示されているアクセス許可--cloudformation-execution-policies
を--trust
リスト内の任意の AWS アカウントに効果的に付与します。デフォルトでは、これにより、ブートストラップされたアカウントの任意のリソースに対する読み取りと書き込みのアクセス許可が拡張されます。ブートストラップスタックには、使い慣れたポリシーと信頼できるアカウントを設定してください。
新しい前提条件
AWS CDK v2 のほとんどの要件は AWS CDK v1.x の要件と同じです。その他の要件を以下に示します。
-
TypeScript デベロッパーには、 TypeScript 3.8 以降が必要です。
-
CDK v2 で使用するには、CDK Toolkit の新しいバージョンが必要です。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
、プロジェクトにインストールされているモジュールを更新します。
依存関係を更新したら、 を発行npm update -g aws-cdk
して CDK Toolkit を リリースバージョンに更新します。
AWS CDK v1 から CDK v2 への移行
アプリケーションを AWS CDK v2 に移行するには、まず の機能フラグを更新しますcdk.json
。次に、記述されているプログラミング言語に応じて、必要に応じてアプリケーションの依存関係とインポートを更新します。
最新の v1 への更新
古いバージョンの AWS CDK v1 から最新バージョンの v2 にアップグレードしたお客様は、1 回のステップで多数表示されます。それは確実に可能ですが、数年にわたる変更 (現時点ではすべての進化テストが同じではない可能性があります) でアップグレードするだけでなく、新しいデフォルトや別のコード組織でバージョン間でアップグレードすることもあります。
最も安全なアップグレードエクスペリエンスを提供し、予期しない変更の原因をより簡単に診断するには、2 つのステップを分けることをお勧めします。まず最新の v1 バージョンにアップグレードしてから、v2 に切り替えることです。
機能フラグの更新
次の v1 機能フラグが存在するcdk.json
場合は、 から削除します。これらは 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 の動作に戻すには、いくつかの AWS CDK v1 機能フラグを に設定できます。完全なリファレンス GitHub についてはfalse
、v1 の動作に戻す「」または「」のリストを参照してください。
どちらのタイプのフラグでも、 cdk diff
コマンドを使用して合成されたテンプレートの変更を調べ、これらのフラグのいずれかの変更がインフラストラクチャに影響するかどうかを確認します。
CDK ツールキットの互換性
CDK v2 には、CDK Toolkit の v2 以降が必要です。このバージョンは CDK v1 アプリと下位互換性があります。したがって、グローバルにインストールされた単一のバージョンの CDK Toolkit を、v1 または v2 のどちらを使用する場合でも、すべての AWS CDK プロジェクトで使用できます。例外は、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 でレガシースタックシンセライザーを使用した場合に適用されます。(CDK v2 はレガシースタック合成子をサポートしていません)。
-
CheckBootstrapVersion
ルールの追加。
予期しない変更は、通常、 AWS CDK v2 自体へのアップグレードが原因ではありません。通常、これらは機能フラグによって以前に変更された非推奨の動作の結果です。これは、約 1.85.x より前のバージョンの CDK からアップグレードする兆候です。最新の v1.x リリースへのアップグレードと同じ変更が表示されます。通常、これを解決するには、以下を実行します。
-
アプリケーションを最新の v1.x リリースにアップグレードする
-
機能フラグを削除する
-
必要に応じてコードを修正する
-
デプロイ
-
v2 へのアップグレード
注記
アップグレードしたアプリが 2 段階アップグレード後にデプロイできない場合は、問題を報告します
アプリケーションにスタックをデプロイする準備ができたら、最初にコピーをデプロイしてテストできるようにすることを検討してください。これを行う最も簡単な方法は、別のリージョンにデプロイすることです。ただし、スタックIDs を変更することもできます。テスト後は、必ず を使用してテストコピーを破棄してくださいcdk destroy。
トラブルシューティング
TypeScript 'from' expected
インポートの または ';' expected
エラー
TypeScript 3.8 以降にアップグレードします。
「cdk bootstrap」を実行する
次のようなエラーが表示された場合:
❌ 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 では、ブートストラップなしでシンプルなスタックをデプロイできます)。詳細については、「ブートストラッピング」を参照してください。
v1 スタックの検索
CDK アプリケーションを v1 から v2 に移行する場合、v1 を使用して作成されたデプロイされた AWS CloudFormation スタックを特定できます。これを行うには、次のコマンドを実行します。
npx awscdk-v1-stack-finder
使用の詳細については、awscdk-v1-stack-f Finder README