Azure Kubernetes Service (AKS) クラスターのアップグレード

[アーティクル]
01/26/2024

AKS クラスターライフサイクルの一部には、最新の Kubernetes バージョンへの定期的なアップグレードの実行が含まれます。最新のセキュリティリリースを適用し、アップグレードして最新の機能を入手することが重要です。この記事では、AKS クラスターへのアップグレードを確認、適用する方法について説明します。

Kubernetes バージョンのアップグレード

サポートされている AKS クラスターをアップグレードする場合、Kubernetes マイナーバージョンはスキップできません。すべてのアップグレードは、メジャーバージョン番号の順番に実行する必要があります。たとえば、1.14.x ->1.15.x または 1.15.x ->1.16.x へのアップグレードは許可されています。 1.14.x ->1.16.x は許可されていません。複数のバージョンをスキップできるのは、サポートされていないバージョンからサポートされているバージョンにアップグレードする場合のみです。たとえば、サポートされていない 1.10.x からサポートされている 1.12.x (リリースされている場合) へのアップグレードを実行できます。

2 つ以上のマイナーバージョンをスキップしているサポート対象外バージョンからのアップグレードを実行すると、そのアップグレードは機能が保証されず、サービスレベルアグリーメントと限定的保証から除外されます。バージョンが大幅に古い場合は、代わりにクラスターを再作成することをお勧めします。

開始する前に

Azure CLI を使っている場合、この記事では Azure CLI バージョン 2.34.1 以降が必要です。バージョンを確認するには、az --version を実行します。インストールまたはアップグレードする必要がある場合は、Azure CLI のインストールに関するページを参照してください。
Azure PowerShell を使う場合、この記事では、Azure PowerShell バージョン 5.9.0 以降が必要です。バージョンを確認するには、Get-InstalledModule -Name Az を実行します。インストールまたはアップグレードする必要がある場合は、Azure PowerShell のインストールに関するページをご覧ください。
アップグレード操作を実行するには、Microsoft.ContainerService/managedClusters/agentPools/write RBAC ロールが必要です。 Azure RBAC ロールの詳細については、「Azure リソースプロバイダーの操作」を参照してください。
1.30 Kubernetes バージョンと 1.27 LTS バージョン以降、ベータ API は、アップグレード時に既定で無効になります。

警告

AKS クラスターのアップグレードで、ノードの切断とドレインがトリガーされます。使用可能なコンピューティングクォータが少ない場合は、アップグレードが失敗する可能性があります。詳しくは、「クォータの増加」をご覧ください。

利用できる AKS クラスターのアップグレードを確認する

Note

AKS の修正プログラム、リリース、更新プログラムの最新情報については、「AKS リリーストラッカー」を参照してください。

ご使用のクラスターに利用できる Kubernetes リリースを確認するには、az aks get-upgrades コマンドを使用します。

az aks get-upgrades --resource-group myResourceGroup --name myAKSCluster --output table

次の出力例では、現在のバージョンが 1.26.6 と示され、upgrades の下に使用可能なバージョンが一覧表示されます。

{
  "agentPoolProfiles": null,
  "controlPlaneProfile": {
    "kubernetesVersion": "1.26.6",
    ...
    "upgrades": [
      {
        "isPreview": null,
        "kubernetesVersion": "1.27.1"
      },
      {
        "isPreview": null,
        "kubernetesVersion": "1.27.3"
      }
    ]
  },
  ...
}

Get-AzAksVersion コマンドレットを使って、クラスターとそれが配置されているリージョンで使用可能な Kubernetes リリースを確認します。

Get-AzAksVersion -Location eastus | Where-Object OrchestratorVersion

次の出力例では、OrchestratorVersion の下に使用可能なバージョンが示されています。

Default     IsPreview     OrchestratorType     OrchestratorVersion
-------     ---------     ----------------     -------------------
                          Kubernetes           1.27.1
                          Kubernetes           1.27.3

AKS クラスターアップグレードのエラーメッセージのトラブルシューティング

次の出力例は、appservice-kube 拡張機能が Azure CLI のバージョンと互換性がないことを意味します (バージョン 2.34.1 以降が必要)。

The 'appservice-kube' extension is not compatible with this version of the CLI.
You have CLI core version 2.0.81 and this extension requires a min of 2.34.1.
Table output unavailable. Use the --query option to specify an appropriate query. Use --debug for more info.

この出力が返された場合は、Azure CLI のバージョンを更新する必要があります。 az upgrade コマンドはバージョン 2.11.0 で追加されたもので、2.11.0 より前のバージョンでは動作しません。以前のバージョンを更新するには、「Azure CLI のインストール」の説明に従って Azure CLI を再インストールします。 Azure CLI のバージョンが 2.11.0 以降の場合は、az upgrade を実行して Azure CLI を最新バージョンにアップグレードします。

Azure CLI が更新され、次の出力例が返された場合は、アップグレードが利用できないということです。

ERROR: Table output unavailable. Use the --query option to specify an appropriate query. Use --debug for more info.

アップグレードを使用できない場合、サポートされている Kubernetes バージョンを使用して新しいクラスターを作成し、既存のクラスターからこの新しいクラスターにワークロードを移行します。 AKSでは、az aks get-upgrades でアップグレードを使用できないことが示される場合に、クラスターを新しい Kubernetes バージョンにアップグレードすることはサポートされていません。

アップグレードを使用できない場合、サポートされている Kubernetes バージョンを使用して新しいクラスターを作成し、既存のクラスターからこの新しいクラスターにワークロードを移行します。 AKSでは、Get-AzAksUpgradeProfile でアップグレードを使用できないことが示される場合に、クラスターを新しい Kubernetes バージョンにアップグレードすることはサポートされていません。

AKS クラスターのアップグレード

クラスターのアップグレードプロセス中に、AKS では次の操作が実行されます。

指定された Kubernetes バージョンを実行するクラスターに 1 つの新しいバッファーノード (または最大サージに構成されている数のノード) が追加されます。
実行中のアプリケーションの中断を最小限に抑えるために、古いノードを 1 つ切断およびドレインします。最大サージを使用している場合は、指定されたバッファーノードの数と同数のノードが同時に切断およびドレインされます。
実行時間の長いポッドの場合、ノードドレインタイムアウトを構成し、ポッドの削除やノード別の正常終了の待機時間をカスタマイズできます。指定されていない場合、既定値は 30 分です。
古いノードが完全にドレインされると、新しいバージョンを受け取るための再イメージ化が実行され、次にアップグレードされるノード用のバッファーノードになります。
必要に応じて、ノードをドレインしてから再イメージ化して次のノードに進むまでの待機時間を設定できます。短い間隔で、アップグレードプロセス中に他のタスク (Grafana ダッシュボードからアプリケーションの正常性を確認するタスクなど) を完了できます。アップグレードプロセスの短い期間 (合理的にできるだけ 0 分近く) をお勧めします。それ以外の場合、ノードのソーク時間が長いほど、問題が検出されるまでの時間に影響します。最小のソーク時間の値は 0 分で、最大 30 分です。指定しない場合、既定値の 0 分が使用されます。
このプロセスは、クラスター内のすべてのノードがアップグレードされるまで繰り返されます。
プロセスの最後に、最後にバッファーノードが削除され、既存のエージェントノードの数とゾーンバランスが維持されます。

Note

パッチが指定されていない場合、クラスターは、指定されたマイナーバージョンの最新 GA パッチに自動的にアップグレードされます。たとえば、--kubernetes-version を 1.21 に設定すると、クラスターは 1.21.9 にアップグレードされます。

詳細については、AKS でサポートされている Kubernetes マイナーバージョンのアップグレードに関する記事を参照してください。

az aks upgrade コマンドを使用してクラスターをアップグレードします。

az aks upgrade \
    --resource-group myResourceGroup \
    --name myAKSCluster \
    --kubernetes-version <KUBERNETES_VERSION>

az aks show コマンドを使用して、アップグレードが成功したことを確認します。

az aks show --resource-group myResourceGroup --name myAKSCluster --output table

次の出力例は、クラスターが現在 1.27.3 を実行していることを示しています。

Name          Location    ResourceGroup    KubernetesVersion    ProvisioningState    Fqdn
------------  ----------  ---------------  -------------------  -------------------  ----------------------------------------------
myAKSCluster  eastus      myResourceGroup  1.27.3               Succeeded            myakscluster-dns-379cbbb9.hcp.eastus.azmk8s.io

Set-AzAksCluster コマンドを使用してクラスターをアップグレードします。

Set-AzAksCluster -ResourceGroupName myResourceGroup -Name myAKSCluster -KubernetesVersion <KUBERNETES_VERSION>

Get-AzAksCluster コマンドを使用して、アップグレードが成功したことを確認します。

Get-AzAksCluster -ResourceGroupName myResourceGroup -Name myAKSCluster |
 Format-Table -Property Name, Location, KubernetesVersion, ProvisioningState, Fqdn

次の出力例は、クラスターが現在 1.27.3 を実行していることを示しています。

Name         Location KubernetesVersion ProvisioningState Fqdn                                   
----         -------- ----------------- ----------------- ----                                   
myAKSCluster eastus   1.27.3            Succeeded         myakscluster-dns-379cbbb9.hcp.eastus.azmk8s.io

自動アップグレードチャネルを設定する

クラスターに自動アップグレードチャネルを設定することができます。詳細については、AKS クラスターの自動アップグレードに関する記事を参照してください。

ノードサージアップグレードのカスタマイズ

重要

ノードサージには、アップグレード操作ごとに、要求された最大サージカウントに対するサブスクリプションクォータが必要です。たとえば、クラスターに 5 つのノードプールがあり、そのそれぞれに 4 つのノードが含まれる場合、合計で 20 個のノードがあります。各ノードプールの最大サージ値が 50% の場合、アップグレードを完了するには、10 ノード (2 ノード * 5 プール) の追加のコンピューティングおよび IP クォータが必要です。
ノードプールの最大サージ設定は永続的です。以降の Kubernetes アップグレードまたはノードバージョンのアップグレードでは、この設定が使用されます。ノードプールの最大サージ値はいつでも変更できます。運用ノードプールの場合は、最大サージ設定を 33% にすることをお勧めします。
Azure CNI を使用している場合は、Azure CNI の IP 要件を満たすだけの使用可能な IP がサブネット内にあることを検証します。

AKS は、既定で、1 つの追加ノードを使ってサージするようにアップグレードを構成します。最大サージ設定の既定値は 1 です。これにより、AKS は、既存のアプリケーションの遮断またはドレインの前に追加のノードを作成して古いバージョンのノードを置き換えることにより、ワークロードの中断を最小限に抑えることができます。ノードプールあたりの最大サージ値をカスタマイズできます。最大サージ値を大きくするとアップグレードプロセスはより速く完了し、アップグレードプロセス中に中断が発生する可能性があります。

たとえば、最大サージ値が 100% の場合、可能な限り最速のアップグレードプロセスが提供されますが、ノードプール内のすべてのノードが同時にドレインされます。テスト環境では、このようなより大きな値を使用することができます。運用環境のノードプールの場合は、max_surge 設定を 33% にすることをお勧めします。

AKS では、最大サージに対して整数値とパーセント値の両方を受け入れます。たとえば、整数 5 は、サージする 5 つの追加ノードを示します。値 50% は、プール内の現在のノード数の半分のサージ値を示します。最大サージのパーセント値には、最低 1%、最大 100% の値を指定できます。パーセント値は、最も近いノード数に切り上げられます。最大サージ値が、アップグレードが必要なノードの数より大きい場合、アップグレードするノードの数が最大サージ値に使用されます。アップグレード中、最大サージ値には、最小値を 1 とし、最大値をノードプール内のノード数とする値を指定することができます。より大きな値を設定することはできますが、最大サージに使うノードの最大数を、アップグレード時のプール内のノード数より大きく設定することはできません。

最大サージ値を設定する

az aks nodepool add または az aks nodepool update コマンドを使って、新規または既存のノードプールの最大サージ値を設定します。

# Set max surge for a new node pool
az aks nodepool add -n mynodepool -g MyResourceGroup --cluster-name MyManagedCluster --max-surge 33%

# Update max surge for an existing node pool 
az aks nodepool update -n mynodepool -g MyResourceGroup --cluster-name MyManagedCluster --max-surge 5

ノードドレインタイムアウト値を設定する

場合によっては、特定のポッドで実行時間の長いワークロードがあり、実行時に別のノードに再スケジュールできない場合があります (たとえば、実行を完了する必要があるメモリ負荷の高いステートフルワークロードなど)。これらのケースでは、アップグレードワークフローで AKS によって考慮されるノードドレインタイムアウトを構成できます。ノードドレインタイムアウト値が指定されない場合、既定値は 30 分です。ドレインタイムアウト値が経過し、ポッドがまだ実行中の場合、アップグレード操作は停止されます。後続の PUT 操作では、停止されたアップグレードが再開されます。

az aks nodepool add または az aks nodepool update コマンドを使用して、新しいまたは既存のノードプールのノードドレインタイムアウトを設定します。

# Set drain timeout for a new node pool
az aks nodepool add -n mynodepool -g MyResourceGroup --cluster-name MyManagedCluster  --drain-timeout 100

# Update drain timeout for an existing node pool
az aks nodepool update -n mynodepool -g MyResourceGroup --cluster-name MyManagedCluster --drain-timeout 45

ノードのソーク時間の値を設定する

ノードをドレインしてから再イメージ化して次のノードに進むまでの待機時間を長くするには、ソーク時間を 0 - 30 分の値に設定します。ノードソーク時間の値が指定されていない場合、既定値は 0 分です。

az aks nodepool add、az aks nodepool update、または az aks nodepool upgrade コマンドを使用して、新しいまたは既存のノードプールのノードドソーク時間を設定します。

# Set node soak time for a new node pool
az aks nodepool add -n MyNodePool -g MyResourceGroup --cluster-name MyManagedCluster --node-soak-duration 10

# Update node soak time for an existing node pool
az aks nodepool update -n MyNodePool -g MyResourceGroup --cluster-name MyManagedCluster --max-surge 33% --node-soak-duration 5

# Set node soak time when upgrading an existing node pool
az aks nodepool upgrade -n MyNodePool -g MyResourceGroup --cluster-name MyManagedCluster --max-surge 33% --node-soak-duration 20

アップグレードイベントを表示する

kubectl get events コマンドを使ってアップグレードイベントを表示します。

kubectl get events

次の出力例では、上記のイベントの一部がアップグレード中に一覧表示されています。

...
default 2m1s Normal Drain node/aks-nodepool1-96663640-vmss000001 Draining node: [aks-nodepool1-96663640-vmss000001]
...
default 1m45s Normal Upgrade node/aks-nodepool1-96663640-vmss000001   Soak duration 5m0s after draining node: aks-nodepool1-96663640-vmss000001
...
default 9m22s Normal Surge node/aks-nodepool1-96663640-vmss000002 Created a surge node [aks-nodepool1-96663640-vmss000002 nodepool1] for agentpool nodepool1
...

次のステップ

自動アップグレードの構成方法については、AKS クラスターの自動アップグレードの構成に関する記事を参照してください。

アップグレードのベストプラクティスとその他の考慮事項の詳細については、「AKS のパッチとアップグレードのガイダンス」を参照してください。

Azure Kubernetes Service (AKS) クラスターのアップグレード

Kubernetes バージョンのアップグレード

開始する前に

利用できる AKS クラスターのアップグレードを確認する

AKS クラスター アップグレードのエラー メッセージのトラブルシューティング

AKS クラスターのアップグレード

自動アップグレード チャネルを設定する

ノード サージ アップグレードのカスタマイズ