これは AWS CDK v2 デベロッパーガイドです。旧版の CDK v1 は 2022 年 6 月 1 日にメンテナンスを開始し、2023 年 6 月 1 日にサポートを終了しました。 翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。 # AWS CDK v1 から AWS CDK v2 への移行 AWS Cloud Development Kit (AWS CDK) のバージョン 2 は、インフラストラクチャを任意のプログラミング言語でコードとして簡単に記述できるように設計されています。このトピックでは、AWS CDK の v1 と v2 間の変更について説明します。 **ヒント** AWS CDK v1 でデプロイされたスタックを特定するには、[awscdk-v1-stack-finder](https://www.npmjs.com/package/awscdk-v1-stack-finder) ユーティリティを使用します。 AWS CDK v1 から CDK v2 への主な変更点は次のとおりです。 + AWS CDK v2 は、コアライブラリを含む AWS コンストラクトライブラリの安定した部分を 1 つのパッケージである `aws-cdk-lib` に統合します。デベロッパーは、使用する個々の AWS サービスに追加のパッケージをインストールする必要がなくなりました。この単一パッケージアプローチは、さまざまな CDK ライブラリパッケージのバージョンを同期する必要がないことも意味します。 AWS CloudFormation で利用可能な正確なリソースを表す L1 (CfnXXXX) コンストラクトは、常に安定していると考えられているため、`aws-cdk-lib` に含まれています。 + コミュニティと協力して新しい [L2 または L3 コンストラクト](constructs.md#constructs-lib-levels)を開発している実験モジュールは、`aws-cdk-lib` に含まれていません。代わりに、個々のパッケージとして配布されます。実験パッケージには `alpha` サフィックスおよびセマンティックバージョン番号で名前が付けられます。セマンティックバージョン番号は、互換性がある AWS コンストラクトライブラリの最初のバージョンと一致し、これも `alpha` サフィックスが付いています。コンストラクトは、安定と指定された後に `aws-cdk-lib` に移動し、メインコンストラクトライブラリが厳密なセマンティックバージョニングに従うことを許可します。 安定性はサービスレベルで指定されます。例えば、これを記述している時点で L1 コンストラクトのみを持つ Amazon AppFlow 用に 1 つ以上の [L2 コンストラクト](constructs.md#constructs-lib-levels)の作成を開始する場合、最初は `@aws-cdk/aws-appflow-alpha` という名前のモジュールに表示されます。次に、新しいコンストラクトが顧客の基本的なニーズを満たしていると判断したら、`aws-cdk-lib` に移行します。 モジュールが安定と指定されて `aws-cdk-lib` に組み込まれたら、次の箇条書きで説明されている BetaN 規定を使用して APIs が追加されます。 各実験モジュールの新しいバージョンは、AWS CDK のリリースごとにリリースされます。ただし、ほとんどの場合、同期する必要はありません。いつでも `aws-cdk-lib` または実験モジュールをアップグレードできます。ただし、複数の関連する実験モジュールが相互に依存している場合、同じバージョンである必要があります。 + 新機能が追加される安定したモジュールの場合、新しい APIs (まったく新しいコンストラクトや新しいメソッドまたは既存のコンストラクト上のプロパティを問わず) は、作業の進行中に `Beta1` サフィックスを受け取ります。(大幅な変更が必要なとき、`Beta2` や `Beta3` などが続きます) API が安定と指定されているとき、サフィックスのない API のバージョンが追加されます。その後、最新版 (ベータ版または最終版を問わず) を除くすべてのメソッドは廃止されます。 例えば、コンストラクトに新しい `grantPower()` メソッドを追加すると、最初は `grantPowerBeta1()` として表示されます。大幅な変更が必要な場合 (例えば、新しい必須パラメータやプロパティなど)、メソッドの次のバージョンに `grantPowerBeta2()` という名前が付けられて、以下同様に適用されます。作業が完了して API が確定されると、メソッド `grantPower()` (サフィックスなし) が追加されて BetaN メソッドは廃止されます。 すべてのベータ API は次のメジャーバージョン (3.0) のリリースまでコンストラクトライブラリに残り、署名は変更されません。使用すると廃止の警告が表示されるため、できるだけ早く API の最終バージョンに移行する必要があります。ただし、今後の AWS CDK 2.x リリースはアプリケーションを破損することはありません。 + `Construct` クラスは、関連するタイプとともに、AWS CDK から別のライブラリに抽出されています。コンストラクトプログラミングモデルを他のドメインに適用する取り組みをサポートするために行われます。独自のコンストラクトを記述したり、関連する API を使用したりしている場合、`constructs` モジュールを依存関係として宣言し、インポートに小さな変更を加える必要があります。CDK アプリのライフサイクルへのフックなど、高度な機能を使用している場合、さらに変更が必要な場合があります。詳細については、「[RFC を参照してください](https://github.com/aws/aws-cdk-rfcs/blob/master/text/0192-remove-constructs-compat.md#release-notes)」。 + AWS CDK v1.x およびそのコンストラクトライブラリの廃止されたプロパティ、メソッド、タイプは、CDK v2 API から完全に削除されました。サポートされているほとんどの言語では、これらの API は v1.x で警告を生成するため、代替の API に既に移行している可能性があります。CDK v1.xの完全の[廃止された API のリスト](https://github.com/aws/aws-cdk/blob/master/DEPRECATED_APIs.md)は、GitHub で入手できます。 + AWS CDK v1.x の機能フラグによってゲートされた動作は、CDK v2 ではデフォルトで有効になっています。以前の機能フラグは不要になり、ほとんどの場合はサポートされません。特定の状況で CDK v1 の動作に戻すため、まだいくつかあります。詳細については、「[機能フラグの更新](#migrating-v2-v1-upgrade-cdk-json)」を参照してください。 + CDK v2 を使用すると、デプロイ先の環境は最新のブートストラップスタックを使用してブートストラップする必要があります。レガシーブートストラップスタック (v1 のデフォルト) はサポートされなくなりました。さらに、CDK v2 にはモダンスタックの新しいバージョンが必要です。既存の環境をアップグレードするには、再度ブートストラップしてください。最新のブートストラップスタックを使用するため、機能フラグや環境変数を設定する必要がなくなりました。 **重要** 最新のブートストラップテンプレートは、`--trust` リストで任意の AWS アカウントに `--cloudformation-execution-policies` が暗示するアクセス許可を効果的に付与します。デフォルトでは、ブートストラップされたアカウントに任意のリソースへの読み取りおよび書き込みのアクセス許可が拡張されます。使い慣れたポリシーおよび信頼されたアカウントを使用して[ブートストラップスタックを設定](bootstrapping-customizing.md)することを確認してください。 ## 新しい前提条件 AWS CDK v2 のほとんどの要件は AWS CDK v1.x と同じです。その他の要件はこちらに記載されています。 + TypeScript デベロッパーには、TypeScript 3.8 以降が必要です。 + CDK v2 を使用する場合、CDK Toolkit の新しいバージョンが必要です。CDK v2 が一般公開されたため、CDK Toolkit をインストールするときのデフォルトバージョンは v2 です。CDK v1 プロジェクトとの下位互換性があるため、CDK v1 プロジェクトを作成しない限り、以前のバージョンをインストールしたままにする必要はありません。アップグレードするには、`npm install -g aws-cdk` を発行します。 ## AWS CDK v2 デベロッパープレビューからのアップグレード CDK v2 デベロッパープレビューを使用している場合、プロジェクトには (`2.0.0-rc1` など) AWS CDK のリリース候補バージョンの依存関係があります。`2.0.0` に更新したら、プロジェクトにインストールされているモジュールを更新します。 **Example** `npm install` 、、または `yarn install` `npm install` 、、または `yarn install` ``` python -m pip install -r requirements.txt ``` ``` mvn package ``` ``` dotnet restore ``` ``` go get ``` 依存関係を更新したら、`npm update -g aws-cdk` を発行して CDK Toolkit をリリースバージョンに更新します。 ## AWS CDK v1 から CDK v2 への移行 アプリを AWS CDK v2 に移行するには、最初に `cdk.json` の機能フラグを更新します。次に、書き込まれているプログラミング言語に応じてアプリの依存関係およびインポートを更新します。 ### 最近の v1 への更新 1 ステップで AWS CDK v1 の古いバージョンから v2 の最新バージョンにアップグレードするお客様が多数います。確かに行うことは可能ですが、数年にわたる変更 (残念ながら、すべてが現在と同じ量の進化テストを受けているとは限らない) にアップグレードすることに加え、新しいデフォルトおよび異なるコード組織を持つバージョン間でアップグレードすることにもなります。 最も安全なアップグレードエクスペリエンスを実現し、予期しない変更の原因をより簡単に診断するには、次の 2 つのステップを分離することをお勧めします。最初に v1 の最新バージョンにアップグレードしたら、v2 に切り替えます。 ### 機能フラグの更新 次の v1 機能フラグはすべてデフォルトで AWS CDK v2 でアクティブになっているため、`cdk.json` に存在したら削除してください。古い効果がインフラストラクチャにとって重要な場合、ソースコードを変更する必要があります。詳細については、「[GitHub のフラグのリスト](https://github.com/aws/aws-cdk/blob/main/packages/%40aws-cdk/cx-api/FEATURE_FLAGS.md)」を参照してください。 + `@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` 特定の AWS CDK v1 動作に戻すには、いくつかの v1 機能フラグを `false` に設定することができます。完全なリファレンスについては、「[v1 の動作に戻す](featureflags.md#featureflags-disabling)」または GitHub のリストを参照してください。 両方のタイプのフラグには、`cdk diff` コマンドを使用して合成されたテンプレートの変更を検査し、これらのフラグの変更がインフラストラクチャに影響を与えるかどうかを確認します。 ### CDK Toolkit の互換性 CDK v2 は、CDK Toolkit の v2 以降が必要です。このバージョンは CDK v1 アプリと下位互換性があります。したがって、v1 または v2 を使用するかにかかわらず、すべての AWS CDK プロジェクトで CDK Toolkit のグローバルにインストールされたバージョンを 1 つ使用できます。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 の任意のバージョンを呼び出せるようにします。 ``` alias cdk1="npx aws-cdk@1.x" alias cdk="npx aws-cdk@2.x" ``` ``` doskey cdk1=npx aws-cdk@1.x $* doskey cdk=npx aws-cdk@2.x $* ``` ### 依存関係とインポートの更新 アプリの依存関係を更新したら、新しいパッケージをインストールします。最後に、コードのインポートを更新します。 **Example** **アプリケーション**: CDK アプリの場合、次のように `package.json` を更新します。v1 形式の個々の安定モジュールへの依存関係を削除し、アプリケーションに必要な `aws-cdk-lib` の最低バージョンを確立します (ここでは 2.0.0)。 実験コンストラクトは、`alpha` とアルファバージョン番号で終わる名前を持つ個別で独立したバージョニングパッケージで提供されます。アルファバージョン番号は、互換性のある `aws-cdk-lib` の最初のリリースに対応します。こちらでは、 v2.0.0-alpha.1 に `aws-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 互換ライブラリをリリースするとき、ライブラリのバージョン番号に対してメジャーバージョンバンプを実行する必要があります。1 つのライブラリで CDK v1 および v2 の両方をサポートすることはできません。v1 をまだ使用しているお客様のサポートを継続するには、以前のリリースを並行して維持するか、v2 用に新しいパッケージを作成できます。 AWS CDK v1 のお客様のサポートを継続する期間の長さは、ユーザー次第です。2022 年 6 月 1 日にメンテナンスを開始して 2023 年 6 月 1 日に製品終了となる CDK v1 自体のライフサイクルからヒントを得ることができます。詳細については、「[AWS CDK メンテナンスポリシー](https://github.com/aws/aws-cdk-rfcs/blob/master/text/0079-cdk-2.0.md#aws-cdk-maintenance-policy)」を参照してください。 **ライブラリとアプリの両方** `npm install` または `yarn install` を実行し、新しい依存関係をインストールします。 インポートを変更し、新しい `constructs` モジュール、`aws-cdk-lib` の最上位レベルから `App` および `Stack` などのコアタイプ、`aws-cdk-lib` の名前空間から使用するサービスの安定したコンストラクトライブラリモジュールから `Construct` をインポートします。 ``` 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 ``` 次のように `package.json` を更新します。v1 形式の個々の安定モジュールへの依存関係を削除し、アプリケーションに必要な `aws-cdk-lib` の最低バージョンを確立します (ここでは 2.0.0)。 実験コンストラクトは、`alpha` とアルファバージョン番号で終わる名前を持つ個別で独立したバージョニングパッケージで提供されます。アルファバージョン番号は、互換性のある `aws-cdk-lib` の最初のリリースに対応します。こちらでは、 v2.0.0-alpha.1 に `aws-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` を実行し、新しい依存関係をインストールします。 アプリのインポートを変更し、次の内容を実行します。 + 新しい `constructs` モジュールから `Construct` のインポート + `App` や `Stack` などのコアタイプを `aws-cdk-lib` の最上位レベルからインポート + `aws-cdk-lib` で名前空間から AWS コンストラクトライブラリモジュールのインポート ``` 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 ``` `setup.py` の `requirements.txt` または `install_requires` の定義を次のように更新します。v1 形式の個々の安定モジュールへの依存関係を削除します。 実験コンストラクトは、`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", # ... ], ``` `pip uninstall` を使用して、アプリの仮想環境に既にインストールされている AWS CDK モジュールの他のバージョンをすべてアンインストールします。次に、`python -m pip install -r requirements.txt` を持つ新しい依存関係をインストールします。 アプリのインポートを変更し、次の内容を実行します。 + 新しい `constructs` モジュールから `Construct` のインポート + `App` や `Stack` などのコアタイプを `aws_cdk` の最上位レベルからインポート + `aws_cdk` で名前空間から AWS コンストラクトライブラリモジュールのインポート ``` 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(...) ``` `pom.xml` で、安定したモジュールの`software.amazon.awscdk`依存関係をすべて削除し、`software.constructs` (`Construct` の場合) および `software.amazon.awscdk` の依存関係に置き換えます。 実験コンストラクトは、`alpha` とアルファバージョン番号で終わる名前を持つ個別で独立したバージョニングパッケージで提供されます。アルファバージョン番号は、互換性のある `aws-cdk-lib` の最初のリリースに対応します。こちらでは、 v2.0.0-alpha.1 に `aws-codestar` を固定しました。 ``` software.amazon.awscdk aws-cdk-lib 2.0.0 software.amazon.awscdk code-star-alpha 2.0.0-alpha.1 software.constructs constructs 10.0.0 ``` `mvn package` を実行して新しい依存関係をインストールします。 コードを変更し、次の内容を実行します。 + 新しい`software.constructs`ライブラリから `Construct` のインポート + `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\$1 CDK アプリケーションの依存関係をアップグレードする最も簡単な方法は、`.csproj` ファイルを手動で編集することです。安定した `Amazon.CDK.*` パッケージリファレンスをすべて削除し、`Amazon.CDK.Lib` および `Constructs` パッケージへの参照に置き換えます。 実験コンストラクトは、`alpha` とアルファバージョン番号で終わる名前を持つ個別で独立したバージョニングパッケージで提供されます。アルファバージョン番号は、互換性のある `aws-cdk-lib` の最初のリリースに対応します。こちらでは、 v2.0.0-alpha.1 に `aws-codestar` を固定しました。 ``` ``` `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 get` を発行し、依存関係を最新バージョンに更新してプロジェクトの `.mod` ファイルを更新します。 ## デプロイ前に移行したアプリのテスト スタックをデプロイする前に、`cdk diff` を使用してリソースに予期しない変更がないか確認します。論理 IDs の変更 (リソースの置き換えの原因になる) は想定**されません**。 予想される変更には次の内容が含まれますが、これらに限定されません。 + `CDKMetadata` リソースへの変更。 + アセットハッシュが更新されました。 + 新しいスタイルのスタック合成に関連する変更。アプリが v1 でレガシースタックシンセサイザーを使用した場合に適用されます。 + `CheckBootstrapVersion` ルールの追加。 予期しない変更は、通常は AWS CDK v2 自体にアップグレードすることで発生しません。通常、機能フラグによって以前に変更された廃止の動作によるものです。これはおおむね 1.85.x より前の CDK のバージョンからアップグレードすることによる症状です。最新の v1.x リリースのアップグレードには同じ変更を確認できます。この症状は次のように解決できます。 1. アプリを最新の v1.x リリースにアップグレード 1. 機能フラグの削除 1. 必要に応じたコードの修正 1. デプロイ 1. v2 へのアップグレード **注記** 2 段階アップグレード後にアップグレードされたアプリがデプロイできない場合、[問題を報告してください](https://github.com/aws/aws-cdk/issues/new/choose)。 アプリにスタックをデプロイする準備ができたら、テストするために最初にコピーをデプロイすることを検討してください。これを行う最も簡単な方法は、別のリージョンにデプロイすることです。ただし、スタックの 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 CDK v2 には更新されたブートストラップスタックが必要であり、さらにすべての v2 デプロイにはブートストラップリソースが必要です。(v1 では、ブートストラップなしで簡単なスタックをデプロイできます) 詳細については、「[AWS CDK ブートストラップ](bootstrapping.md)」を参照してください。 ## v1 スタックの検索 CDK アプリケーションを v1 から v2 に移行するとき、v1 を使用して作成されたデプロイされた AWS CloudFormation スタックを特定できます。これを行うには、次のコマンドを実行します。 ``` npx awscdk-v1-stack-finder ``` 使用状況の詳細については、awscdk-v1-stack-finder の「[README](https://github.com/cdklabs/awscdk-v1-stack-finder/blob/main/README.md)」を参照してください。