次の方法で共有

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

  • [アーティクル]

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"
      }
    ]
  },
  ...
}

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 バージョンにアップグレードすることはサポートされていません。

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

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

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

Note

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

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

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

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

  2. 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

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

クラスターに自動アップグレード チャネルを設定することができます。 詳細については、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 --name mynodepool --resource-group MyResourceGroup --cluster-name MyManagedCluster --max-surge 33%

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

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

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

ドレイン タイムアウト値が経過し、ポッドがまだ実行中の場合、アップグレード操作は停止されます。 後続の PUT 操作では、停止されたアップグレードが再開されます。 また、実行時間の長いポッドに対しては、[terminationGracePeriodSeconds][https://kubernetes.io/docs/concepts/containers/container-lifecycle-hooks/] を構成することもお勧めします。

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

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

# Update drain timeout for an existing node pool
az aks nodepool update --name mynodepool --resource-group 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 --name MyNodePool --resource-group MyResourceGroup --cluster-name MyManagedCluster --node-soak-duration 10

# Update node soak time for an existing node pool
az aks nodepool update --name MyNodePool --resource-group 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 --name MyNodePool --resource-group 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 のパッチとアップグレードのガイダンス」を参照してください。