Azure Kubernetes Service（AKS）のコントロールプレーンアップグレードは、ノードプール上のワークロードをすぐに変更せず、APIサーバーなどの管理面だけを先に新しいKubernetesバージョンへ進めるための手段です。結論として、本番AKSでは「いきなりクラスター全体をアップグレードする」のではなく、まずアップグレード可能なバージョン、廃止API、権限、クォータを確認し、--control-plane-onlyでコントロールプレーンを先に更新してからノードプールを段階的に進めるのが安全です。
Microsoft Learnの公式情報では、AKSクラスターを「Azureが管理するコントロールプレーン」と「ワークロードを実行するノードプール」に分けて整理し、コントロールプレーンだけを独立してアップグレードする手順を説明しています。これにより、ノードプールのアップグレードを別工程として管理しながら、新しいKubernetes APIや互換性を先に検証できます。(Microsoft Learn)
AKSコントロールプレーンアップグレードで何が変わるのか
AKSのコントロールプレーンのみをアップグレードする場合、主な対象はAPIサーバー、etcd、controller manager、schedulerなどの管理コンポーネントです。一方、通常はノードプールのKubernetesバージョンはそのまま残るため、既存Podをすぐにドレインしたり、ノードを再イメージ化したりする作業とは分けて考えられます。(Microsoft Learn)
| 項目 | 変わること | 注意点 |
|---|---|---|
| コントロールプレーン | APIサーバー、etcd、controller manager、schedulerなどが対象バージョンに更新される | kubectl、Helm、CI/CD、Admission WebhookなどAPIサーバーと通信する仕組みの検証が必要 |
| ノードプール | 原則としてコントロールプレーンのみの操作ではバージョンを維持する | アップグレード後にaz aks nodepool listで実際のバージョン確認が必要 |
| 既存ワークロード | ノードプールを同時に更新しなければ、Podの即時再配置は基本的に発生しにくい | 新しいAPIサーバーで非推奨APIや古いマニフェストが問題になる可能性がある |
| 運用プロセス | コントロールプレーンとノードプールを別工程で管理できる | 「コントロールプレーンのみ」で終わらせず、最終的にはノードプール更新計画も必要 |
実務上のポイントは、「ワークロードを止めずに済む」と短絡的に捉えないことです。コントロールプレーンだけを更新しても、デプロイ操作、kubectl操作、カスタムコントローラー、GitOpsツール、監視エージェントなどはAPIサーバーに依存します。つまり、既存Podが動き続けていても、新規デプロイやスケール操作で問題が表面化する可能性があります。
アップグレード種別の違いを理解する
AKSのアップグレードは、大きく「コントロールプレーンのみ」「クラスター全体」「ノードプールのみ」に分けて考えると整理しやすくなります。公式情報でも、コントロールプレーンのみはワークロードに影響を与える前に新しいKubernetes APIを検証する用途、フルクラスターアップグレードは標準的な更新、ノードプールのみは段階的なロールアウトに使うものとして整理されています。(Microsoft Learn)
| 種別 | 対象範囲 | 向いている場面 | 失敗しやすいポイント |
|---|---|---|---|
| コントロールプレーンのみ | APIサーバー、etcd、controller manager、scheduler | 先にAPI互換性を確認したい、本番前に管理面だけ進めたい | 廃止APIや古いCRD、Admission Webhookの検証不足 |
| クラスター全体 | コントロールプレーンと全ノードプール | 小規模環境、検証済み環境、運用負荷を減らしたい場合 | ノードドレイン、PDB、サージ容量、IP不足で止まりやすい |
| ノードプールのみ | 特定のノードプール | システム用、ユーザー用、GPU用などを段階的に更新したい | ノードごとのワークロード特性を考慮しないと停止リスクが高い |
本番環境では、まずコントロールプレーンをアップグレードし、API互換性や運用ツールの動作を確認した後、ノードプールをローリングアップグレードする流れが現実的です。特に複数チームが同じAKSを利用している場合、アプリケーションチームが使うマニフェストやHelmチャートの確認時間を確保できます。
バージョンルールで必ず押さえるべきこと
AKSのアップグレードでは、Kubernetesのマイナーバージョンを飛ばせません。たとえば1.28.xから1.29.x、1.29.xから1.30.xのような順次アップグレードは可能ですが、1.28.xから1.30.xへ直接進めることはできません。また、コントロールプレーンはノードプールより最大2マイナーバージョン先行できます。(Microsoft Learn)
このルールは、移行計画に大きく影響します。長期間アップグレードしていないAKSクラスターでは、目的のバージョンまで複数回の作業が必要になるため、1回のメンテナンス枠で完了しないことがあります。
実務での判断例
| 現在の状態 | 判断 |
|---|---|
| コントロールプレーン1.28、ノードプール1.28 | まず1.29へアップグレードする。1.30へ直接進めない |
| コントロールプレーン1.30、ノードプール1.28 | バージョン差は許容範囲内だが、ノードプール更新計画を立てる |
| ノードプールを先に1.30へ上げたい | 不可。コントロールプレーンは常にノードプール以上のバージョンである必要がある |
az aks get-upgradesで候補が出ない | 最新のサポートバージョン、またはサポート外バージョンで移行が必要な可能性がある |
ノードプールを先にアップグレードすることはできません。公式FAQでも、コントロールプレーンのバージョンは常にノードプール以上である必要があり、先にコントロールプレーンをアップグレードする必要があると説明されています。(Microsoft Learn)
管理者が事前に確認すべき設定
AKSコントロールプレーンのアップグレードは、コマンドを実行するだけでは不十分です。実行前に、ツール、権限、アップグレードパス、API互換性、クォータを確認しておく必要があります。
| 確認項目 | 確認内容 | 具体的な確認方法 |
|---|---|---|
| Azure CLI | バージョン2.34.1以降が必要 | az --version |
| Azure PowerShell | Az PowerShell 5.9.0以降が必要 | Get-InstalledModule -Name Az |
| RBAC権限 | アップグレード操作に必要な権限があるか | Microsoft.ContainerService/managedClusters/agentPools/writeを含むロールを確認 |
| アップグレード候補 | 現在のAKSで利用できるKubernetesバージョン | az aks get-upgrades |
| 廃止API | 対象バージョンで使えなくなるAPIがないか | Azure Portalの表示、kubentなどで確認 |
| コンピュートクォータ | アップグレード時に必要な容量があるか | サブスクリプション、リージョン、VM SKUのクォータを確認 |
| ノードプール状態 | 混在バージョンや過去の失敗がないか | az aks nodepool listで確認 |
| IaC定義 | Terraform、Bicep、ARMテンプレートなどと実環境がずれないか | Kubernetesバージョン指定を確認 |
公式情報では、Azure CLI 2.34.1以降、Azure PowerShell 5.9.0以降、アップグレード操作に必要なRBAC権限、十分なコンピュートクォータが前提として挙げられています。また、Kubernetes 1.30および1.27 LTSへアップグレードする場合、Beta APIが既定で無効になる点にも注意が必要です。(Microsoft Learn)
Azure CLIでコントロールプレーンのみをアップグレードする手順
最も実務で使いやすいのはAzure CLIによる実行です。以下は、コントロールプレーンだけをアップグレードし、ノードプールのバージョンが変わっていないことまで確認する流れです。
現在利用できるアップグレード候補を確認する
az aks get-upgrades \
--resource-group <resource-group-name> \
--name <cluster-name> \
--output tableこの時点で、現在のコントロールプレーンバージョンとアップグレード可能なバージョンを確認します。候補が複数ある場合でも、マイナーバージョンを飛ばさず、順番に進める必要があります。
コントロールプレーンのみをアップグレードする
az aks upgrade \
--resource-group <resource-group-name> \
--name <cluster-name> \
--kubernetes-version <target-version> \
--control-plane-only<target-version>には、az aks get-upgradesで表示された利用可能なバージョンを指定します。例として公式情報では1.29.4が使われていますが、実際には自社環境で利用できるバージョンを指定してください。(Microsoft Learn)
アップグレード完了を確認する
az aks show \
--resource-group <resource-group-name> \
--name <cluster-name> \
--output tableKubernetesVersionとProvisioningStateを確認します。ProvisioningStateがSucceededになっているかを見ます。
ノードプールのバージョンを確認する
az aks nodepool list \
--resource-group <resource-group-name> \
--cluster-name <cluster-name> \
--query "[].{Name:name,Version:orchestratorVersion}" \
--output tableコントロールプレーンのみのアップグレードでは、ノードプールは以前のKubernetesバージョンのまま表示される想定です。ここを確認しないと、「本当にノードプールへ影響がなかったか」を判断できません。
PowerShellとAzure Portalで実行する場合
PowerShellを使う場合は、Set-AzAksClusterに-ControlPlaneOnlyを付けて実行します。
Set-AzAksCluster `
-ResourceGroupName <resource-group-name> `
-Name <cluster-name> `
-KubernetesVersion <target-version> `
-ControlPlaneOnly確認にはGet-AzAksClusterを使います。
Get-AzAksCluster `
-ResourceGroupName <resource-group-name> `
-Name <cluster-name> |
Format-Table -Property Name, Location, KubernetesVersion, ProvisioningStateAzure Portalの場合は、AKSクラスターリソースを開き、Cluster configurationからUpgrade versionを選び、Control plane onlyを選択します。Portalでは、現在のバージョンとアップグレード先の間にある廃止APIが表示されるため、CLI中心の運用でも一度確認しておく価値があります。(Microsoft Learn)
開発者が確認すべきAPI互換性
コントロールプレーンのアップグレードで最も見落とされやすいのは、アプリケーションの実行そのものではなく、デプロイや更新の失敗です。古いAPIバージョンを使ったマニフェスト、更新されていないHelmチャート、CRD、Operator、Admission Webhookがあると、新しいAPIサーバーでエラーになることがあります。
特に確認したい対象は次のとおりです。
- Deployment、Ingress、HPA、PodDisruptionBudgetなどの標準マニフェスト
- Helm chart内に残っている古い
apiVersion - CRDを提供するOperatorやアドオン
- Gatekeeper、Kyverno、Azure Policyなどのポリシー系コンポーネント
- Argo CD、Flux、GitHub Actions、Azure DevOpsなどのデプロイ経路
- Kubernetes APIを直接呼び出す社内ツール
公式情報では、廃止APIの確認ツールとしてkube-no-trouble（kubent）が紹介されており、問題がある場合はアップグレード前にマニフェストをサポート対象のAPIバージョンへ更新する必要があります。(Microsoft Learn)
kubentあわせて、対象マニフェストを本番に適用する前にサーバー側ドライランで確認しておくと、API互換性の問題を早めに見つけやすくなります。
kubectl apply --server-side --dry-run=server -f ./manifests/本番環境での展開計画の作り方
本番AKSでは、コントロールプレーンのアップグレードを単発作業として扱わないことが重要です。次のように、検証環境、本番コントロールプレーン、本番ノードプールの順に段階を分けると、影響を切り分けやすくなります。
| フェーズ | 実施内容 | 合格条件 |
|---|---|---|
| 検証環境 | 本番に近い構成でコントロールプレーンをアップグレード | 主要マニフェスト、CI/CD、監視、ログ収集が正常 |
| 本番事前確認 | 廃止API、クォータ、権限、バックアップ、メンテナンス時間を確認 | 作業手順と切り戻し方針がレビュー済み |
| 本番コントロールプレーン | --control-plane-onlyでアップグレード | ProvisioningStateがSucceeded、ノードプールが想定通り |
| スモークテスト | デプロイ、スケール、ログ、監視、Ingressを確認 | 通常運用と同じ操作が通る |
| ノードプール更新 | ノードプールを段階的にアップグレード | PDB、レプリカ数、サージ容量、IP不足で停止しない |
コントロールプレーンアップグレードは、公式FAQでは一般的に5〜15分程度で完了すると説明されています。ただし、クラスター構成やリージョン側の負荷に依存するため、必ず短時間で終わると決め打ちせず、デプロイ頻度の低い時間帯に実行するのが現実的です。(Microsoft Learn)
ノードプールが意図せずアップグレードされるケース
--control-plane-onlyを指定しても、必ずノードプールに一切の変化がないと考えるのは危険です。公式FAQでは、クラスターの準拠性や健全性を保つため、AKSがコントロールプレーンアップグレードと並行してローリングノードプールアップグレードを起動する場合があると説明されています。典型例は、過去のノードアップグレード失敗や、ノードが混在バージョンのまま残っているケースです。(Microsoft Learn)
そのため、作業前後で必ずノードプールの状態を比較してください。
az aks nodepool list \
--resource-group <resource-group-name> \
--cluster-name <cluster-name> \
--query "[].{Name:name,Version:orchestratorVersion,ProvisioningState:provisioningState}" \
--output tableもしノードプールにも変更が入る可能性がある環境なら、PDB、レプリカ数、サージ用の容量、サブネットIPの余裕も確認しておくべきです。AKSのアップグレード全般では、PDB設定、クォータ、サブネットIP、証明書やサービスプリンシパルなどの事前検証が失敗要因になり得ます。(Microsoft Learn)
よくある失敗と対処方法
| 事象 | 主な原因 | 対処 |
|---|---|---|
az aks get-upgradesで候補が出ない | すでに最新のサポートバージョン、またはサポート外バージョン | サポート状況を確認。サポート外の場合は新規クラスター作成とワークロード移行を検討 |
| アップグレードが廃止APIで失敗する | 古いapiVersionのマニフェストやCRDが残っている | kubentやPortalで確認し、マニフェストを更新 |
| 権限不足で実行できない | 必要なAzure RBAC権限がない | 作業者またはマネージドIDのロールを確認 |
| クォータ不足で失敗する | リージョンやVM SKUのコンピュートクォータが不足 | 事前にクォータを増やす、対象リージョンやノード構成を確認 |
| コントロールプレーンだけのつもりがノードも動いた | 過去のアップグレード失敗や混在バージョン | 作業前後のaz aks nodepool listを保存し、差分を確認 |
| ノードプール更新フェーズでPodが退避できない | PDBが厳しすぎる、レプリカ不足、終了処理が長い | PDBのmaxUnavailableやレプリカ数を見直し、事前にステージングで検証 |
公式情報では、az aks get-upgradesで候補がない場合、クラスターが最新のサポートバージョンであるか、サポート外バージョンで移行が必要な可能性があると説明されています。サポート外バージョンの場合は、サポート対象バージョンの新しいクラスターを作成し、ワークロードを移行する方針になります。(Microsoft Learn)
管理者・開発者別の確認チェックリスト
AKS管理者・プラットフォーム担当者
az aks get-upgradesでアップグレード候補を確認する- コントロールプレーンと各ノードプールの現在バージョンを記録する
- Azure CLI、PowerShell、RBAC権限を確認する
- コンピュートクォータ、サブネットIP、VM SKUの余裕を確認する
- 自動アップグレード設定やメンテナンスウィンドウの有無を確認する
- 過去に失敗したノードプールアップグレードや混在バージョンがないか確認する
アプリケーション開発者
- Kubernetesマニフェストの
apiVersionを確認する - Helm chart、Kustomize、GitOpsリポジトリを更新する
- CRD、Operator、Admission Webhookの対応バージョンを確認する
- サーバー側ドライランでマニフェスト適用を検証する
- デプロイ、ロールバック、スケール操作を検証環境で試す
SRE・運用担当者
- アップグレード中の監視項目を決める
- APIサーバー操作、デプロイ頻度、アラートの影響を確認する
- 作業前後でイベント、Pod状態、Ingress、ログ収集を確認する
- ノードプール更新に進む前に、PDBとレプリカ数を見直す
- 失敗時の連絡先、判断基準、作業中止条件を決めておく
アップグレード後に必ず確認する項目
コントロールプレーンアップグレードが終わったら、Succeededだけで判断せず、実際の運用操作が通るかを確認します。
kubectl get nodes
kubectl get pods -A
kubectl get events -A --sort-by=.lastTimestamp
kubectl get deployments -A次に、普段のデプロイ経路で小さな変更を流します。たとえば、検証用NamespaceにConfigMapを適用する、ステージング相当のDeploymentを再適用する、GitOpsの同期を手動実行するなどです。ここで失敗する場合、アプリケーション本体ではなく、API互換性、RBAC、Webhook、CRD、CI/CD側に問題がある可能性があります。
kubectl apply --server-side --dry-run=server -f ./manifests/ノードプールを後続でアップグレードする場合は、コントロールプレーン更新後の検証結果を残してから進めます。フルクラスターアップグレードでは、AKSはコントロールプレーンを先に更新し、その後に各ノードプールを順番に更新します。ノードプール側はドレインや再イメージ化を伴うため、コントロールプレーンのみの作業よりも時間と影響範囲が大きくなります。(Microsoft Learn)
次に取るべき行動
AKSコントロールプレーンアップグレードで最初にやるべきことは、すぐにaz aks upgradeを実行することではありません。まず、現在のクラスターとノードプールのバージョンを棚卸しし、利用可能なアップグレード先、廃止API、RBAC権限、クォータ、IaC定義の差分を確認してください。
安全な進め方は、次の順番です。
az aks get-upgradesでアップグレード候補を確認するkubentやAzure Portalで廃止APIを確認する- 検証環境でコントロールプレーンのみをアップグレードする
- 本番で
--control-plane-onlyを実行する - ノードプールが想定通り維持されているか確認する
- CI/CD、GitOps、kubectl操作、監視、Ingressを確認する
- 問題がなければノードプールのローリングアップグレードを計画する
コントロールプレーンのみのアップグレードは、AKS運用のリスクを分割するための有効な手段です。ただし、API互換性やノードプール更新計画を後回しにすると、次のデプロイやノード更新で問題が出ます。管理者と開発者が同じチェックリストを見ながら、「APIサーバーを上げる作業」と「ワークロード実行基盤を上げる作業」を分けて進めることが、AKSアップグレードを安定させる近道です。
コメント