Azure REST APIの「Update the api-version to 2026-03-02-preview for the dotnet and java client generation config for containerservice」は、AKSそのものを即座に変える更新ではありません。結論から言うと、2026年5月20日にAzure公式のREST API仕様リポジトリでマージされた、Microsoft.ContainerService/aks向けのSDK生成設定の更新です。特に.NET（C#）とJavaの生成設定で、2026-03-01に固定されていた指定を見直し、2026-03-02-preview側の生成に揃える意図があります。既存の本番環境をすぐ切り替える必要はありませんが、AKSをREST API、SDK、IaC、社内自動化で管理しているチームは、api-versionとSDKパッケージの固定箇所を確認しておくべきです。(GitHub)
なお、この更新は「AI/Copilot機能の追加」ではなく、Azure REST API仕様とSDK生成設定に関する変更です。Azure REST APIを直接呼ぶ開発者、.NET/Java SDKでAKSを操作する開発者、AKS管理基盤を運用する管理者向けに、変更点、影響範囲、移行・展開時の注意点を整理します。
Azure REST API documentation updateの要点
Azure REST APIの仕様は、Azureの公式GitHubリポジトリである Azure/azure-rest-api-specs に集約されています。このリポジトリはMicrosoft Azure REST API仕様のcanonical source、つまり基準となるソースとして説明されています。(GitHub)
今回のPR #42536は、2026年5月20日に main ブランチへマージされました。PRタイトルは「Update the api-version to 2026-03-02-preview for the dotnet and java client generation config for containerservice」で、対象は containerservice、実務上はAKSの管理プレーンAPIである Microsoft.ContainerService/aks です。(GitHub)
重要なのは、PR本文で「API仕様を変更せず、SDK構成のみを変更する」趣旨が明示されている点です。つまり、既存のREST APIエンドポイントがこのPRだけで突然変わる、既存クラスターの挙動が自動的に変わる、という種類の更新ではありません。(GitHub)
| 観点 | 今回の内容 | 実務上の意味 |
|---|---|---|
| 対象サービス | Azure REST API / AKS / Microsoft.ContainerService/aks | AKSの管理プレーンAPIを扱うコードや自動化が確認対象 |
| 変更種別 | SDK生成設定の変更 | REST API仕様そのものの大規模変更とは分けて考える |
| 主な対象言語 | .NET（C#）とJava | 該当SDKを使う開発チームは依存関係と生成モデルを確認 |
| APIバージョン | 2026-03-02-preview | プレビューAPIのため、本番適用は慎重に判断 |
| 直接の対応 | 即時移行ではなく棚卸しと検証 | api-version固定箇所、SDKバージョン、CI/CDを確認 |
具体的に何が変わったのか
差分としては、specification/containerservice/resource-manager/Microsoft.ContainerService/aks/tspconfig.yaml の1ファイルが変更されています。PRのFiles changedでは、追加0行、削除3行として表示され、Java用設定とC#管理SDK・C#プロビジョニングSDK用設定から api-version: "2026-03-01" の明示指定が削除されています。(GitHub)
対象になっている設定は、主に次の3系統です。
| 生成設定 | 関連するSDK・名前空間 | 確認すべき人 |
|---|---|---|
@azure-tools/typespec-java | com.azure.resourcemanager.containerservice | JavaでAKS管理SDKを使う開発者 |
@azure-typespec/http-client-csharp-mgmt | Azure.ResourceManager.ContainerService | .NETでAKS管理SDKを使う開発者 |
@azure-typespec/http-client-csharp-provisioning | Azure.Provisioning.ContainerService | .NETのプロビジョニング系SDKを使う開発者 |
現在の tspconfig.yaml では、Java用の出力先や名前空間、C#管理SDKの名前空間、C#プロビジョニングSDKの名前空間が定義されています。ここから 2026-03-01 固定の api-version 指定が外れたことで、対象言語のSDK生成時にプレビュー側のバージョンを利用しやすい構成になったと捉えるのが実務上は分かりやすいです。(GitHub)
一方で、AKSのTypeSpec定義側には安定版 2026-03-01 とプレビュー版 2026-03-02-preview の両方が定義されています。2026-03-02-preview は @previewVersion として扱われているため、最新だからといって無条件に本番標準へ置き換えるべきものではありません。(GitHub)
2026-03-02-previewはどのような位置づけか
Azure SDKのREST API仕様一覧では、Microsoft.ContainerService/aks に安定版 2026-03-01 とプレビュー版 2026-03-02-preview が並んでいます。2026-03-02-preview は2026年5月9日に作成されたプレビュー仕様として掲載されています。(Azure)
Azure REST APIでは、Azure Resource Manager provider APIの呼び出しに api-version クエリパラメーターが必要です。Microsoft LearnのAzure REST APIリファレンスでも、Azure Resource Manager provider APIsは https://management.azure.com/ を使い、api-version query-string parameterを必要とすると説明されています。(Microsoft Learn)
つまり、REST APIを直接呼び出している場合、どのAPIバージョンを使うかはURLの ?api-version=... によって明示されます。
GET https://management.azure.com/subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.ContainerService/managedClusters/<clusterName>?api-version=2026-03-02-preview既存コードが 2026-03-01 やそれ以前のバージョンを指定しているなら、このPRのマージだけで自動的に 2026-03-02-preview に変わるわけではありません。変更が起きるのは、SDKを更新した場合、生成済みクライアントの既定バージョンが変わった場合、または自分たちのREST呼び出し・IaC定義で明示的に 2026-03-02-preview を指定した場合です。
影響範囲：誰が何を確認すべきか
REST APIを直接呼んでいる開発者
az rest、curl、PowerShell、社内HTTPクライアントなどでAKSの管理APIを直接呼んでいる場合、最初に見るべきなのはURL内の api-version です。Azure REST APIではリクエストURIのquery stringにAPI versionを含める形が基本で、AKSの各REST APIページでも api-version は必須のqueryパラメーターとして示されています。(Microsoft Learn)
たとえば、Microsoft Learnには 2026-03-02-preview を使うAKS REST APIとして、Agent PoolsのComplete Upgrade、JWT AuthenticatorsのDelete、Identity BindingsのListなどが掲載されています。これらは Microsoft.ContainerService/managedClusters/... 配下の管理プレーン操作です。(Microsoft Learn)
確認ポイントは次のとおりです。
| 確認項目 | 具体例 | 判断基準 |
|---|---|---|
api-versionの固定 | 2026-03-01、2026-03-02-preview、古いAKS APIバージョン | 本番は安定版、検証・新機能確認はプレビューに分ける |
| リクエスト本文 | properties配下の設定値、プレビュー専用のプロパティ | 未対応環境で送信していないか確認 |
| レスポンス処理 | 存在前提にしているフィールド、enum、null許容 | 追加・変更・欠落に強い実装にする |
| LRO処理 | 202 Accepted後のポーリング | Azure-AsyncOperationやLocationを正しく追跡 |
| エラーハンドリング | Other Status Codes、Error Response | preview特有の失敗をログで識別できるようにする |
特に注意したいのは、api-version を「最新にすれば良い」と考えないことです。プレビュー版は新機能の検証には有効ですが、運用自動化の標準バージョンにするには、ロールバック手順と検証結果が必要です。
.NET SDKを使っている開発者
.NETでは、今回の差分にC#管理SDK用の Azure.ResourceManager.ContainerService と、プロビジョニング系の Azure.Provisioning.ContainerService が関係します。tspconfig.yaml 上でも、それぞれのnamespaceと出力先が定義されています。(GitHub)
確認すべきなのは、アプリケーションコードそのものよりも、まず依存関係です。
grep -RIn --exclude-dir=.git \
-e 'Azure.ResourceManager.ContainerService' \
-e 'Azure.Provisioning.ContainerService' \
-e '2026-03-01' \
-e '2026-03-02-preview' \
.次に、.csproj、Directory.Packages.props、packages.lock.json、CI/CDのrestore設定を確認します。SDKを自動更新している場合、生成モデルやメソッドのシグネチャが変わっても、レビュー前にビルドへ入ってくる可能性があります。
.NET側では、次の観点で検証してください。
| 確認箇所 | 見るべき内容 |
|---|---|
| NuGetパッケージのバージョン固定 | Azure.ResourceManager.ContainerService を明示固定しているか |
| 生成モデル | 新しいプロパティ、enum、nullableの扱い |
| シリアライズ | 送信されるJSONに不要なpreviewプロパティが混ざらないか |
| LRO | Begin... 系メソッドの戻り値やポーリング完了条件 |
| プロビジョニングコード | Azure.Provisioning.ContainerService を使うテンプレート生成やデプロイ処理 |
PRがマージされたことと、NuGetで新しいパッケージを使うことは同じではありません。実務では「PR確認」「SDKリリース確認」「依存関係更新」「非本番検証」「本番展開」を別々の工程として扱うのが安全です。
Java SDKを使っている開発者
Javaでは、com.azure.resourcemanager.containerservice が確認対象です。今回の設定差分では、Java用TypeSpec emitterの設定から api-version: "2026-03-01" が外れています。(GitHub)
MavenまたはGradleで次のような依存関係を使っている場合は、更新対象に含めてください。
grep -RIn --exclude-dir=.git \
-e 'azure-resourcemanager-containerservice' \
-e 'com.azure.resourcemanager.containerservice' \
-e '2026-03-01' \
-e '2026-03-02-preview' \
.Java SDKでは、Fluent APIやモデルクラスの変更が呼び出し側に影響しやすいです。特に、AKSクラスター作成・更新、Agent Pool更新、ID関連設定、プレビュー機能の有効化を自動化しているコードは、コンパイルが通るだけでなく、実際のHTTPリクエスト内容まで確認してください。
管理者・SRE・プラットフォームチーム
管理者がまず押さえるべき点は、今回の更新がAKSクラスター内のKubernetes APIバージョンではなく、Azure Resource Manager経由でAKSを操作する管理プレーンAPIの話だということです。
確認対象は、アプリケーションコードだけではありません。
| 領域 | 確認するもの | 失敗しやすいポイント |
|---|---|---|
| IaC | ARM template、Bicep、Terraform AzAPI | apiVersionだけ先に変えて検証不足になる |
| CI/CD | AKS作成・更新・ノードプール操作ジョブ | REST呼び出しが古いAPIバージョンに固定されている |
| 社内共通ライブラリ | AKS操作用HTTPクライアント、SDKラッパー | 呼び出し側からはAPIバージョンが見えない |
| Azure Policy | preview API利用の制限、タグ・リージョン制約 | 検証環境では通るが本番サブスクリプションで拒否される |
| 監査ログ | 操作ログ、デプロイログ、HTTPログ | どのAPIバージョンで呼んだか追跡できない |
本番環境では、api-version をログに残すことをおすすめします。障害時に「どのSDKバージョンで、どのAPIバージョンを使って、どの操作を実行したか」が分からないと、切り戻し判断が遅れます。
まず実施すべき棚卸し手順
今回のAzure REST API更新で最も大切なのは、すぐに 2026-03-02-preview へ移行することではなく、自社環境の固定箇所を見つけることです。
コードとIaCからapi-versionを探す
まず、リポジトリ全体でAKS関連のAPIバージョンを検索します。
grep -RIn --exclude-dir=.git \
-e 'Microsoft.ContainerService' \
-e 'managedClusters' \
-e 'agentPools' \
-e '2026-03-01' \
-e '2026-03-02-preview' \
-e 'api-version' \
.検索対象には、次のファイルを含めてください。
| ファイル種別 | 例 |
|---|---|
| IaC | .bicep、.json、.tf、.tfvars |
| アプリケーション設定 | appsettings.json、.env、ConfigMap |
| CI/CD | GitHub Actions、Azure Pipelines、Jenkinsfile |
| スクリプト | Bash、PowerShell、Python |
| SDK依存関係 | .csproj、pom.xml、build.gradle、lock file |
ここで見つかった箇所を、「本番」「検証」「開発」「一時スクリプト」に分類します。すべてを同じ優先度で扱うと対応が散らかるため、まずは本番デプロイや定期ジョブから確認するのが現実的です。
SDKパッケージの固定状況を確認する
SDK利用チームは、APIバージョンだけでなくパッケージ更新ポリシーを確認してください。
| 状況 | リスク | 推奨対応 |
|---|---|---|
| パッケージを明示固定している | 更新漏れはあるが、意図しない変更は入りにくい | 検証後に計画的に更新 |
| minor/patchを自動更新している | SDK生成差分がCIへ突然入る可能性 | AKS関連SDKだけ一時固定し、差分レビュー |
| 共通基盤がSDKをラップしている | 利用チームが影響に気づきにくい | ラッパー側で変更履歴と移行ガイドを出す |
| REST APIとSDKが混在している | 同じ処理で異なるAPIバージョンを使う可能性 | 操作単位で利用経路を整理 |
特に、AKSの作成・更新処理は一度失敗すると環境全体に影響します。SDK更新と本番デプロイを同じ日に実施しないようにしましょう。
2026-03-01と2026-03-02-previewの使い分け
安定版とプレビュー版は、目的を分けて使うのが基本です。AKSの仕様一覧では、2026-03-01 が安定版として、2026-03-02-preview がプレビュー版として扱われています。(Azure)
| 利用シーン | 推奨方針 |
|---|---|
| 本番のAKS作成・更新・削除 | 検証済みの安定版APIを優先 |
| 新しいAKS管理機能の検証 | 2026-03-02-preview を検証環境で試す |
| 社内共通モジュールの標準化 | 安定版を標準、previewは明示オプションにする |
| SDKの新機能確認 | SDK更新とAPIバージョン変更を分けてテスト |
| コンプライアンス要件が厳しい環境 | preview利用の承認ルールを設ける |
「新しいAPIバージョン＝常に安全」ではありません。特にpreviewは、将来の安定版で仕様が変わる可能性を前提に扱うべきです。
非本番での検証手順
同じ操作を複数APIバージョンで比較する
同じ操作が 2026-03-01 と 2026-03-02-preview の両方で利用できる場合は、同じリソースに対してレスポンス差分を比較します。
az rest --method get \
--url "https://management.azure.com/subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.ContainerService/managedClusters/<clusterName>?api-version=2026-03-01" \
> aks-2026-03-01.json
az rest --method get \
--url "https://management.azure.com/subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.ContainerService/managedClusters/<clusterName>?api-version=2026-03-02-preview" \
> aks-2026-03-02-preview.json
jq -S . aks-2026-03-01.json > stable.sorted.json
jq -S . aks-2026-03-02-preview.json > preview.sorted.json
diff -u stable.sorted.json preview.sorted.json見るべきなのは、単なるフィールド追加だけではありません。次のような差分があると、コード側の修正が必要になる可能性があります。
| 差分 | 影響例 |
|---|---|
| enum値の追加 | switch文やバリデーションが失敗する |
| null許容の変化 | 型変換やJSONパースで例外が出る |
| 読み取り専用プロパティの追加 | PUT/PATCHで不要な値を送り返して失敗する |
| LROヘッダーの扱い | 完了待ち処理が終わらない |
| エラーコードの変化 | リトライ条件やアラート条件がずれる |
SDK利用時はコンパイルだけでなく送信JSONを見る
.NETやJava SDKでは、コンパイルが通っても、生成されるHTTPリクエストが変わっている場合があります。検証環境では、可能であればHTTPログを有効化し、次の点を確認してください。
| 確認項目 | 理由 |
|---|---|
リクエストURLのapi-version | 意図したAPIバージョンか確認するため |
| リクエストボディ | preview専用プロパティが混入していないか見るため |
| レスポンスのモデル変換 | 新しいフィールドで例外が出ないか確認するため |
| 202応答後のポーリング | LRO完了まで正しく追跡できるか見るため |
| 失敗時のログ | 切り戻し判断に必要な情報を残すため |
Microsoft LearnのAKS REST API例では、Agent PoolのComplete Upgradeが 202 Accepted を返し、Azure-AsyncOperation や Location ヘッダーを使う例が示されています。REST APIを直接実装している場合は、SDKが自動で処理してくれる部分を自前で正しく実装しているか確認が必要です。(Microsoft Learn)
展開時に避けたい失敗
PRマージをSDKリリース完了と同一視する
今回のPRはAzure REST API仕様リポジトリ上のSDK生成設定変更です。PRがマージされたからといって、すべてのSDKパッケージが即座に利用可能になり、既存プロジェクトへ自動反映されるわけではありません。
実務では、次の4段階を分けて管理してください。
| 段階 | 確認内容 |
|---|---|
| 仕様・設定の変更 | PR、差分、対象APIバージョン |
| SDK生成・レビュー | 生成された言語別APIサーフェス |
| SDKパッケージ公開 | NuGet、Mavenなどの依存関係更新 |
| 自社環境への適用 | CI、検証、本番展開、ロールバック |
PR上ではAPIViewがGo、Java、Python、JavaScript、C#の言語別レビューを作成したことも示されています。差分の主対象がJavaとC#設定であっても、生成結果のレビューは複数言語に波及し得る点に注意が必要です。(GitHub)
previewを本番標準にしてしまう
2026-03-02-preview を使う理由が「新しいから」だけなら、本番への適用は見送るべきです。previewを使うのは、対象機能がpreview APIでしか利用できず、かつ影響範囲と切り戻し手順を確認できている場合に限定しましょう。
preview利用時は、少なくとも次の条件を満たすことを推奨します。
| 条件 | 内容 |
|---|---|
| 利用範囲を限定 | 検証サブスクリプション、検証リソースグループ、特定機能のみ |
| ロールバック可能 | 旧SDK・旧APIバージョンへ戻せる |
| 差分を記録 | リクエスト、レスポンス、SDK変更点を保存 |
| 監視できる | 失敗率、LRO失敗、エラーコードを追える |
| 承認済み | preview利用をチームまたは組織で合意している |
SDK更新とIaC更新を同時に行う
SDK更新とIaCの apiVersion 更新を同時に行うと、問題が起きたときに原因を切り分けにくくなります。
安全な順序は次のとおりです。
| 順序 | 作業 |
|---|---|
| 先に | 現行SDK・現行APIバージョンでテストを整備 |
| 次に | SDKだけ更新して差分を確認 |
| 次に | REST APIまたはIaCのAPIバージョンだけ変更 |
| 最後に | 本番へ段階展開 |
この順序にすると、「SDK生成モデルの変更が原因なのか」「REST APIバージョン変更が原因なのか」を分けて判断できます。
管理者向けチェックリスト
AKSを組織で運用している場合は、次のチェックリストを使って影響範囲を確認してください。
| チェック | 確認内容 |
|---|---|
| APIバージョン | Microsoft.ContainerService の api-version 固定箇所を洗い出したか |
| SDK | .NET / JavaのContainerService SDK依存関係を確認したか |
| IaC | Bicep、ARM template、Terraform AzAPIの apiVersion を確認したか |
| CI/CD | AKS作成・更新・削除ジョブで使うAPIバージョンを確認したか |
| RBAC | 自動化アカウントやサービスプリンシパルの権限を確認したか |
| Policy | preview API利用やAKS設定を制限するポリシーに抵触しないか |
| ログ | APIバージョン、SDKバージョン、操作対象を追跡できるか |
| ロールバック | 旧SDK・旧APIバージョンへ戻す手順があるか |
特に、複数チームが同じAKS基盤を操作している場合は、個別チームがpreview APIを使い始める前に、共通ルールを決めておくことが重要です。
開発者向けの実装上の注意点
レスポンスの追加フィールドに強い実装にする
Azure REST APIのバージョン更新では、レスポンスにフィールドが追加されることがあります。厳密なJSONスキーマで未知フィールドを拒否している場合、preview APIへの切り替えで失敗する可能性があります。
安全な実装例は次のとおりです。
| 実装方針 | 理由 |
|---|---|
| 未知フィールドを許容する | レスポンス拡張に耐える |
| enumのdefaultケースを用意する | 新しい値で落ちないようにする |
| nullチェックを追加する | preview差分や未設定値に備える |
| PUT/PATCHでGET結果を丸ごと送り返さない | 読み取り専用プロパティ送信を避ける |
| APIバージョンを定数化する | 切り戻しと比較を簡単にする |
APIバージョンを環境変数だけに逃がさない
api-version を環境変数化するのは便利ですが、誰がいつ変えたか分からない状態にすると危険です。おすすめは、コード上で許可するバージョンを明示し、設定値が想定外なら起動時に失敗させる方法です。
var allowedApiVersions = new[]
{
"2026-03-01",
"2026-03-02-preview"
};
if (!allowedApiVersions.Contains(configuredApiVersion))
{
throw new InvalidOperationException($"Unsupported AKS API version: {configuredApiVersion}");
}Javaでも同様に、許可リストを設けておくと、誤って古すぎるバージョンや未検証のpreviewへ切り替わるリスクを下げられます。
今回の更新への現実的な対応方針
今回のAzure REST API documentation updateに対して、すべての組織が同じ対応をする必要はありません。利用形態ごとに、次のように判断するとよいでしょう。
| 状況 | 対応方針 |
|---|---|
| REST APIを直接使っていない | すぐの対応は不要。AKS SDK利用有無だけ確認 |
| AKSをSDKで参照のみしている | SDK更新時にモデル差分とログを確認 |
| AKS作成・更新をSDKで自動化している | 非本番でSDK更新テストを実施 |
| IaCでAKSを管理している | apiVersion固定箇所を棚卸し |
| preview機能を使いたい | 2026-03-02-preview を検証環境で限定利用 |
| 本番基盤を安定運用したい | 安定版APIを維持し、previewは採用判断を分ける |
最初の一歩は、コード検索と依存関係の確認です。api-version とSDKパッケージの固定箇所を把握し、previewを使う理由があるかを判断してください。理由がなければ、本番では検証済みの安定版を維持し、2026-03-02-preview は検証用として扱うのが安全です。
今回の更新は、AKS管理APIを使うチームにとって「いますぐ移行」ではなく「生成SDKとAPIバージョン管理を見直すタイミング」です。REST API、.NET SDK、Java SDK、IaCのどこで Microsoft.ContainerService を操作しているかを棚卸しし、preview利用の範囲を明確にしてから段階的に展開しましょう。
コメント