AWS CDK が CLI と Construct Library を分割したことについて調べる
hassaku63新しいバージョニング体系での AWS CDK CLI の最初の新バージョンは
2.1000.0としてリリースされ、次のバージョンは2.1001.0に続きます。CDK コンストラクトライブラリは現在のバージョニング体系を継続し、2.174.0,2.175.0,2.176.0というように順次リリースされます。
バージョンの連続性の区切りを示すため、AWS CDK CLI のバージョン番号に大きな明確な区切りを設けます。
2.174.0の後、AWS CDK CLI のバージョンは2.1000.0にスキップし、その後2.1001.0に進みます。これによりメジャーバージョン番号を変更することなく、AWS CDK CLI と CDK コンストラクトライブラリのバージョニング体系の関連性が途切れていることが明確になることを期待しています。
2.174.0 よりも後ろの CLI バージョンは 2.1000.0 になる。このタイミングで、レポジトリが分離したらしいということがわかる。
一般 CDK ユーザーからみてどうなるかというと。
メジャーバージョンが変わってないのでそこまで劇的な変化があるわけじゃない。
ただし、CLI と本体で使えるバージョンの組み合わせは、その基準が変わるので注意する必要がある。
従来（2.174.01 以下）はバージョン番号の不等式によって既定されていた。すなわち、
CLI Version >= 本体 (Construct Lib) のバージョン であれば OK だった。
レポジトリが分離したあとは、この不等式が日付基準になる。
互換性を確保するために使用できるいくつかの有用なヒントを紹介します。従うべき簡単なルールは
CLI release date>=Lib release dateであれば確実に動作するということです。より複雑ではありますが、やはりライブラリリリース前の最新の AWS CDK CLI リリースは確実に動作し、それ以降のバージョンも同様に動作します。cdk.out ディレクトリ内のファイル形式に変更がない場合、古いバージョンでも動作する可能性がありますが、その互換性は保証されません。
任意の CDK CLI バージョンのリリースがあるとき、その時点でリリースされていた本体（Construct Lib）はどのバージョンでも確実に動作する、と言っている。
cdk.out の話は、要するに Cloud Assembly のファイル形式の話をしていると思われる。
つまり、ビルド (synth) の結果である中間形式 (Cloud Assmebly) の表現形式が変わってないならば、さきほどの不等式を満たさない CLI バージョンであっても問題なく動作する可能性がある、ただし無保証だけど・・・、という話と思われる。
hassaku63互換性モデルに変更はありません。AWS CDK CLI はそれ以前の過去ににリリースされた非推奨でないバージョンの CDK コンストラクトライブラリによって生成されたすべての cdk.out ディレクトリを常に読み取ることができます。互換性を確保するために、CDK コンストラクトライブラリのバージョンをアップグレードする頻度と同じかそれ以上の頻度で npm upgrade を使用して AWS CDK CLI バージョンをアップグレードすることをお勧めします。
ここまでの記述から、既に動作している CDK 本体 & CLI のバージョンの組み合わせであれば、CLI の方をバージョンアップするのは何ら問題なく、動作が保証されていると考えてOK。
※もちろん、メジャーバージョンが変わるような変更事案とか、非推奨バージョンを使っている場合など極端なケースは除く
なので、基本的に既存プロジェクトで依存関係のバージョンアップを考えている人は、CDK 本体よりも先に CLI をバージョンアップしておくのが無難だし、なんなら CLI の方は本体よりも普段からマメにアプデしておくといいよ、という話
hassaku63この変更により AWS CDK をより速いペースで改善できるようになることを嬉しく思います。お客様側での準備やスクリプトの更新が必要になる可能性はありますが、ユーザーへの影響は最小限に抑えられると考えています。ご質問がある場合や、この変更に関する議論に参加したい場合は GitHub の該当 Issue をご覧いただくか、AWS Support または Slack を通じて直接お問い合わせください。
issue は 32775
hassaku63以降の引用は、issue の rix0rrr のコメントから。
The fundamental compatibility model of the CLI remains the same: a CLI can process the output of all Construct Libraries released with it or before it. This used to manifest as the rule that CLI version >= Lib version is always a valid combination of versions. Because the versions will no longer be released in lockstep, the new rule will be CLI release date >= Lib release date.
It will be not as easy to spot that information at a glance from the version number, but we will include the minimum required CLI version number in the cdk.out manifest itself so that the error message will tell you what version is required, and we will publish a table with the compatibility information of every version to GitHub.
特に重要で、かつブログに書かれてなかった情報は太字部分。ざっくり翻訳＆意訳したのが以下
we will publish a table with the compatibility information of every version to GitHub.
と書いてあるが、2025/03/16 時点では CLI と本体の GitHub レポジトリにそれらしき記述は見当たらなかった。
hassaku63閑話休題
このテーマには関係ないが、ついでに見つけた面白そうな話を書いておく
新しい cli レポジトリを眺めていたら、たまたま nx.json とかいう見慣れないファイルが目に入った。
どうも Nx という面白そうなツールの設定ファイルらしかった。これはこれでそのうち調べたい
hassaku63試しに、久しく更新してない手元のプロジェクトで synth 動かしてみた。
$ cat package.json | grep "aws-cdk"
"aws-cdk": "2.146.0",
"aws-cdk-lib": "2.146.0",
$ npx cdk synth
(... 中略...)
NOTICES (What's this? https://github.com/aws/aws-cdk/wiki/CLI-Notices)
32775 (cli): CLI versions and CDK library versions have diverged
Overview: Starting in CDK 2.179.0, CLI versions will no longer be in
lockstep with CDK library versions. CLI versions will now be
released as 2.1000.0 and continue with 2.1001.0, etc.
Affected versions: cli: >=2.0.0 <=2.1005.0
More information at: https://github.com/aws/aws-cdk/issues/32775
If you don’t want to see a notice anymore, use "cdk acknowledge <id>". For example, "cdk acknowledge 32775".
CLI バージョンに注意が必要なことは、警告されている様子。
manifest.json ファイル中の "version" という文字列を探すと、Bootstrap 関係のバージョン (requiresBootstrapStackVersion) と、おそらく Cloud Assembly のバージョンしか言明されていない様子だった。CLI のバージョンが直接書かれているわけではなさそう。