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 クラウド開発キット (AWS CDK) がバージョニングを処理する方法に関するリファレンス情報を提供します。

バージョン番号は、major.minor.patch の 3 つの数値バージョン部分で構成され、 コンストラクトライブラリのセマンティックバージョニングの明確化で説明されているいくつかの注意点とともに、セマンティックバージョニングの原則に広く従っています。 AWSつまり、安定していると見なされる APIs への重大な変更は、メジャーリリースに限定されます。

マイナーリリースとパッチリリースは下位互換性があります。同じメジャーバージョンで以前のバージョンで記述されたコードは、同じメジャーバージョン内の新しいバージョンにアップグレードできます。ビルドと実行が継続され、機能的に同等の結果が得られます。一部の高度なユースケースでは、次のトピックで説明したように、コードへの小さな変更が必要になります。

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 リポジトリの互換性表を参照してください。

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

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

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

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

以前は L1 APIs しか持っていなかった AWS サービスに対して高レベル (L2 または L3) APIs の開発が開始されると、それらの APIsは最初に別のパッケージに分散されます。このようなパッケージには「アルファ」という名前のサフィックスがあり、そのバージョンは alpha サブバージョンを持ち、互換性がある aws-cdk-lib の最初のバージョンと一致します。モジュールが意図したユースケースをサポートすると、API が aws-cdk-lib に追加されます。

AWS コンストラクトライブラリのセマンティックバージョニングの明確化

AWS コンストラクトライブラリはセマンティックバージョニングの原則に広く従っていますが、実装に固有の重要な注意点がいくつかあります。一般的に、 AWS コンストラクトライブラリは API コンシューマーの安定性を維持しますが、フレームワークの必要な進化を可能にするために、コンストラクト作成者に負担を追加することがあります。

  • セキュリティに影響する変更

    セキュリティバーを満たすために、下位互換性のない方法で APIsを変更したり、完全に削除したりする必要がある場合があります。これにより、影響を受ける APIsが使用されなくなり、実装が強制的に更新されます。

  • 機能はインテント別に記述されます

    予期しない変更を最小限に抑えることを目指していますが、実装の安定性よりもインテントを優先します。 AWS コンストラクトライブラリは、コンストラクトが常にまったく同じ CloudFormation テンプレートに合成されること、またはまったく同じリソースセットを使用することを保証しません。これは特に、同じ目標をさまざまな方法で達成できる高レベルのコンストラクトに適用されます。

  • インターフェイスと抽象クラスの実装

    AWS コンストラクトライブラリのインターフェイスと抽象クラスは、コンシューマーには安定していますが、実装者には安定していません。つまり、 のようなインターフェイスに安全に依存しs3.IBucketて、インターフェイスまたは抽象クラスの使用を開始した時点 (AWS コンストラクトライブラリバージョン) と少なくとも同じ機能を提供できます。ただし、新しい (抽象) メンバーは定期的にインターフェイスと抽象クラスに追加されます。実装はまだ新しいメンバーを実装していないため、実装を実装するユーザーにとって、アップグレード時に考慮すべき追加の実装負担が発生します。実装者のインターフェイスおよび抽象クラスへの追加を重大な変更として厳密に扱うと、 AWS コンストラクトライブラリの進化可能性が過度に制限されます。ほとんどの場合、実装者は のような具体的なクラスを拡張することをお勧めしますs3.Bucket。

  • L1 コンストラクト、生成されたコード、および外部としてマークされたその他の APIs

    AWS コンストラクトライブラリの一部は、 AWS サービスから直接取得されるデータソースから生成されます。これらの APIs現実に合わせて維持するために、生成されたコードには下位互換性のない変更が含まれている可能性があります。ほとんどの場合、データソースは現実を正しく反映し、誤った表現を修正するように更新されます。IDE の IntelliSense には、 @stability — external注釈付きの外部 APIs が表示されます。

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

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

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

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

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

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

言語 安定性

TypeScript

安定

JavaScript

安定

Python

安定

Java

安定

C#/。NET

安定

Go

安定