AWS CDK バージョニング - AWS クラウド開発キット (AWS CDK) v2
AWS CDK Toolkit の互換性AWS コンストラクトライブラリのバージョニングAWS コンストラクトライブラリのセマンティックバージョニングの明確化言語バインディングの安定性

これは AWS CDK v2 デベロッパーガイドです。旧版の CDK v1 は 2022 年 6 月 1 日にメンテナンスを開始し、2023 年 6 月 1 日にサポートを終了しました。

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

AWS CDK バージョニング

このトピックでは、AWS Cloud Development Kit (AWS CDK) がバージョニングを処理する方法に関するリファレンス情報を提供します。

バージョン番号は、major.minor.patch の 3 つの数値バージョン部分で構成され、AWS コンストラクトライブラリのセマンティックバージョニングの明確化で説明されているいくつかの注意点とともに、セマンティックバージョニングの原則に広く従っています。つまり、安定しているとみなされる 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 コンストラクトライブラリのリリース時に最新であったバージョンよりも古い AWS CDK Toolkit バージョンでも動作する場合があります。ただし、それは保証されません。互換性は、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 リポジトリ」の「互換性テーブル」を参照してください。

AWS コンストラクトライブラリのバージョニング

概念から成熟した API に発展しながら、AWS コンストラクトライブラリのモジュールはさまざまな段階を経ます。AWS CDK の後続バージョンでは、さまざまなステージによって API の安定性が異なります。

次のトピックで説明する注意事項が適用されるシナリオを除き、メイン AWS コンストラクトライブラリ (aws-cdk-lib) API は安定しており、ライブラリはセマンティックバージョニングの原則に広く従っています。ライブラリには、CloudFormation リソースプロバイダースキーマから自動生成されるすべての AWS サービスの AWS CloudFormation (L1) コンストラクトが含まれており、下位互換性のない更新が含まれる場合があります。また、高レベル (L2 および L3) のコンストラクトと、App や Stack などのコア CDK クラスも含まれており、これらはすべて安定しています。CDK の次のメジャーリリースまで、API はこのパッケージから削除されません (ただし、廃止される可能性があります)。安定した API には大幅な変更が必要なとき、完全に新しい API が追加されます。

aws-cdk-lib に既に組み込まれているサービスの開発中の新しい API は、Beta<N> サフィックスを使用して識別されます。N は 1 で始まり、新しい API に大幅な変更を加えるたびに増加します。 Beta<N>API は削除されませんが、廃止されるのみです。そのため、既存のアプリは aws-cdk-lib の新しいバージョンで引き続き動作します。API が安定していると見なされると、Beta<N> サフィックスのない新しい API が追加されます。

以前は L1 API しかなかった AWS サービス用に上位 (L2 または L3) API が開発されると、それらの API は最初に別のパッケージで配布されます。このようなパッケージには「アルファ」という名前のサフィックスがあり、そのバージョンは 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 が表示されます。

  • 特定の言語バインディング

    言語バインディングには、非常に限られた数の状況で下位互換性のないのない変更を含めることができます。これらは、サポートされている他の言語で下位互換性があるアップストリームタイプの変更によって発生します。これらのタイプの変更は、そうしない限りライブラリの発展性を大幅に制限するため、許可されます。

    次のリストは、すべての既知のインスタンスを説明しています。

    • Golang - 型付きスライスから任意のスライスへの変更: 単一の型のリストが複数の型 (TypeScript のユニオン型) のリストに変更されています。Go では、これらは任意 (*[]any) のスライスとして型付けされます。Go の型付け割り当てルールにより、*[]string から への変更は自動変換ではありません。したがって、この型の拡大では、コンシューマーコードを変更する必要があります。戦略については、「任意のスライスの使用」を参照してください。

言語バインディングの安定性

時間の経過とともに、追加のプログラミング言語用に AWS CDK にサポートが追加される場合があります。すべての言語で説明されている API は同じですが、API の表現方法は言語によって異なり、言語サポートの進化と共に変わる場合があります。このため、本番環境で使用する準備が整うまで、言語バインディングはしばらく実験的に扱われます。

言語 安定性

TypeScript

Stable

JavaScript

Stable

Python (パイソン)

Stable

Java

Stable

C#/.NET

Stable

Go

Stable