これは AWS CDK v2 デベロッパーガイドです。旧版の CDK v1 は 2022 年 6 月 1 日にメンテナンスを開始し、2023 年 6 月 1 日にサポートを終了しました。
翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# AWS CDK バージョニング
このトピックでは、 AWS クラウド開発キット (AWS CDK) がバージョニングを処理する方法に関するリファレンス情報を提供します。
バージョン番号は、*major*.*minor*.*patch* の 3 つの数値バージョン部分で構成され、[AWS コンストラクトライブラリのセマンティックバージョニングの明確化](https://docs.aws.amazon.com/cdk/v2/guide/versioning.html#aws-construct-lib-semver)で説明されているいくつかの注意点とともに、[セマンティックバージョニング](https://semver.org)の原則に広く従っています。つまり、安定しているとみなされる API の大幅な変更はメジャーリリースに制限されます。
マイナーリリースとパッチリリースは下位互換性があります。同じメジャーバージョンで以前のバージョンで記述されたコードは、同じメジャーバージョン内の新しいバージョンにアップグレードできます。ビルドと実行が継続され、機能的に同等の結果が得られます。一部の高度なユースケースでは、次のトピックで説明したように、コードの小さな変更が必要になります。
## AWS CDK Toolkit の互換性
メイン AWS コンストラクトライブラリ (`aws-cdk-lib`) の各バージョンは、コンストラクトライブラリのリリース時に最新だった AWS CDK Toolkit CLI (`aws-cdk-cli`) AWS および Toolkit Library (`@aws-cdk/toolkit-lib`) バージョンと互換性があります。また、 AWS CDK Toolkit の新しいバージョンとも互換性があります。 AWS コンストラクトライブラリの各バージョンは、ライブラリ*のサポート終了日*までこの互換性を維持します。したがって、サポートされている AWS コンストラクトライブラリのバージョンを使用している限り、 AWS CDK Toolkit のバージョンをアップグレードしても安全です。
AWS コンストラクトライブラリの各バージョンは、コンストラクトライブラリのリリース時に最新であったバージョンよりも古い AWS CDK Toolkit AWS バージョンでも動作する場合があります。ただし、それは保証されません。互換性は AWS 、コンストラクトライブラリのクラウドアセンブリスキーマのバージョンによって異なります。 AWS CDK は合成中にクラウドアセンブリを生成し、 AWS CDK Toolkit はそれをデプロイに消費します。クラウドアセンブリの形式を定義するスキーマは、厳密に指定されてバージョニングされます。したがって、 AWS CDK Toolkit の古いバージョンでは、互換性を確保するために AWS コンストラクトライブラリのクラウドアセンブリスキーマバージョンをサポートする必要があります。
AWS コンストラクトライブラリで必要なクラウドアセンブリバージョンが AWS CDK Toolkit でサポートされているバージョンと互換性がない場合、次のようなエラーメッセージが表示されます。
```
Cloud assembly schema version mismatch: Maximum schema version supported is 3.0.0, but found 4.0.0.
Please upgrade your CLI in order to interact with this app.
```
このエラーを解決するには、 AWS CDK Toolkit を必要なクラウドアセンブリバージョンと互換性のあるバージョン、または利用可能な最新バージョンに更新します。代替方法 (アプリが使用する AWS コンストラクトライブラリモジュールをダウングレードする) は通常お勧めしません。
**注記**
連携するバージョンの正確な組み合わせの詳細については、「*aws-cdk-cli GitHub リポジトリ*」の「[互換性テーブル](https://github.com/aws/aws-cdk-cli/blob/main/COMPATIBILITY.md)」を参照してください。
## AWS コンストラクトライブラリのバージョニング
AWS コンストラクトライブラリのモジュールは、概念から成熟した API まで、さまざまな段階を経て開発されます。 AWS CDK の後続バージョンでは、ステージによって API の安定性が異なります。
次のトピックで説明する注意事項が適用されるシナリオを除き、メインの AWS コンストラクトライブラリ (`aws-cdk-lib`) APIs は安定しており、ライブラリはセマンティックバージョニングの原則に広く従っています。このライブラリには、 AWS CloudFormation リソースプロバイダースキーマから自動生成されるすべての AWS サービスの CloudFormation (L1) コンストラクトが含まれており、下位互換性のない更新が含まれる場合があります。 [CloudFormation ](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/resource-type-schemas.html) また、高レベル (L2 および L3) のコンストラクトと、`App` や `Stack` などのコア CDK クラスも含まれており、これらはすべて安定しています。CDK の次のメジャーリリースまで、API はこのパッケージから削除されません (ただし、廃止される可能性があります)。安定した API には大幅な変更が必要なとき、完全に新しい API が追加されます。
`aws-cdk-lib` に既に組み込まれているサービスの開発中の新しい API は、`Beta` サフィックスを使用して識別されます。`N` は 1 で始まり、新しい API に大幅な変更を加えるたびに増加します。 `Beta`API は削除されませんが、廃止されるのみです。そのため、既存のアプリは `aws-cdk-lib` の新しいバージョンで引き続き動作します。API が安定していると見なされると、`Beta` サフィックスのない新しい API が追加されます。
以前は L1 APIs しかなかった AWS サービスに対して高レベル (L2 または L3) APIs の開発が開始されると、それらの APIsは最初に別のパッケージに分散されます。このようなパッケージには「アルファ」という名前のサフィックスがあり、そのバージョンは `alpha` サブバージョンを持ち、互換性がある `aws-cdk-lib` の最初のバージョンと一致します。モジュールが意図したユースケースをサポートすると、API が `aws-cdk-lib` に追加されます。
## AWS コンストラクトライブラリのセマンティックバージョニングの明確化
AWS コンストラクトライブラリはセマンティックバージョニングの原則に広く従っていますが、実装に固有の重要な注意点がいくつかあります。一般的に、 AWS コンストラクトライブラリは API コンシューマーの安定性を維持しますが、フレームワークの必要な進化を可能にするために作成者を構築する負担が増えることがあります。
+ **セキュリティに影響する変更**
セキュリティバーを満たすために、API を下位互換性のない方法で変更するか、完全に削除する必要がある場合があります。これにより、影響を受ける API が使用されなくなり、実装が強制的に更新されます。
+ **機能はインテント別に記述されます**
予期しない変更を最小限に抑えることを目指していますが、*実装の安定性よりもインテント*を優先します。 AWS コンストラクトライブラリは、コンストラクトが常にまったく同じ CloudFormation テンプレートに合成されること、またはまったく同じリソースセットを使用することを保証しません。これは特に、同じ目標をさまざまな方法で達成できる場合が多い高レベルのコンストラクトに適用されます。
+ **インターフェイスと抽象クラスの実装**
AWS コンストラクトライブラリのインターフェイスと抽象クラスは**、コンシューマー**には安定していますが、**実装者**には安定していません。つまり、 のようなインターフェイスに安全に依存し`s3.IBucket`て、インターフェイスまたは抽象クラスの使用を開始した時点 (AWS コンストラクトライブラリバージョン) と少なくとも同じ機能を提供できます。ただし、新しい (抽象) メンバーは定期的にインターフェイスと抽象クラスに追加されます。それらを**実装している**人は誰でも、実装がまだ新しいメンバーを実装していないため、これによりアップグレード時に考慮すべき追加の実装の負担が発生します。実装者のインターフェイスおよび抽象クラスへの追加を重大な変更として厳密に扱うと、 AWS コンストラクトライブラリの進化可能性が過度に制限されます。ほとんどの場合、実装者は `s3.Bucket` のような具体的なクラスを拡張することを選択します。
+ **L1 コンストラクト、生成されたコード、および外部としてマークされたその他の API**
AWS コンストラクトライブラリの一部は、 AWS サービスから直接取得されるデータソースから生成されます。これらの API を現実に合わせて維持するために、生成されたコードには下位互換性のない変更が含まれている可能性があります。ほとんどの場合、データソースは現在現実を正しく反映し、誤った表現を修正するように更新されます。*IDE の IntelliSense には、`@stability — external` 注釈付きの外部 API が表示されます。*
+ **意味的に正しいプログラムのみ**
正しいプログラムが引き続き新しいバージョンで動作するようにします。正式には正しくないが、実装の詳細が原因で動作するプログラムは対象外です。例えば、プログラムが [TypeScript の構造型付けルール](https://www.typescriptlang.org/docs/handbook/type-compatibility.html)に依存して予期しないオブジェクトタイプを渡す場合、または正常に合成されてデプロイに失敗する CloudFormation テンプレートを生成する場合、これらのプログラムは重大な変更を考慮せずに失敗する可能性があります。
+ **特定の言語バインディング**
言語バインディングには、非常に限られた数の状況で下位互換性のないのない変更を含めることができます。これらは、サポートされている他の言語で下位互換性があるアップストリームタイプの変更によって発生します。これらのタイプの変更は、そうしない限りライブラリの発展性を大幅に制限するため、許可されます。
次のリストは、すべての既知のインスタンスを説明しています。
+ **Golang - 型付きスライスから任意のスライスへの変更: **単一の型のリストが複数の型 (TypeScript のユニオン型) のリストに変更されています。`Go` では、これらは任意 (`*[]any`) のスライスとして型付けされます。Go の型付け割り当てルールにより、`*[]string ` から `` への変更は自動変換ではありません。したがって、この型の拡大では、コンシューマーコードを変更する必要があります。戦略については、「[任意のスライスの使用](https://docs.aws.amazon.com/cdk/v2/guide/work-with-cdk-go.html#go-cdk-idioms)」を参照してください。
## 言語バインディングの安定性
時間の経過とともに、追加のプログラミング言語のサポートが AWS CDK に追加される可能性があります。すべての言語で説明されている API は同じですが、API の表現方法は言語によって異なり、言語サポートの進化と共に変わる場合があります。このため、本番環境で使用する準備が整うまで、言語バインディングはしばらく実験的に扱われます。
| Language | 安定性 |
| --- | --- |
| TypeScript | Stable |
| JavaScript | Stable |
| Python | Stable |
| Java | Stable |
| C\$1/.NET | Stable |
| Go | Stable |