クラスタまたはノードプールの手動アップグレード

Google Kubernetes Engine（GKE）クラスタと GKE Standard ノードプールでは、自動アップグレードがデフォルトで有効になっています。

このページでは、GKE クラスタのコントロール プレーンまたはノードのアップグレードとダウングレードを手動でリクエストする方法について説明します。次の方法を使用して、バージョンを手動でアップグレードできます。

• Autopilot: コントロール プレーンのバージョンをアップグレードします。
• Standard: コントロール プレーンのバージョンとノードプールのバージョンをアップグレードします。

クラスタをアップグレードするために、GKE はコントロール プレーンとノードで実行されているバージョンを更新します。クラスタが新しいマイナー バージョン（1.24 から 1.25 など）または新しいパッチ バージョン（1.24.2-gke.100 から 1.24.5-gke.200 など）にアップグレードされます。詳細については、GKE のバージョニングとサポートをご覧ください。

クラスタの自動アップグレードと手動アップグレードの仕組みをご確認ください。メンテナンスの時間枠と除外対象を構成することで、自動アップグレードのタイミングを管理することもできます。

新しいバージョンの GKE は定期的に発表されています。また、クラスタ通知を使用して、特定のクラスタで利用可能な新しいバージョンに関する通知を受け取ることができます。クラスタの特定の自動アップグレード ターゲットを確認するには、クラスタのアップグレードに関する情報を取得する（プレビュー）。

利用可能なバージョンについては、バージョニングに関する記事をご覧ください。クラスタの詳細については、クラスタのアーキテクチャをご覧ください。クラスタのアップグレードに関するガイダンスについては、クラスタのアップグレードに関するベスト プラクティスをご覧ください。

始める前に

作業を始める前に、次のことを確認してください。

• Google Kubernetes Engine API を有効にする。
Google Kubernetes Engine API の有効化
• このタスクに Google Cloud CLI を使用する場合は、gcloud CLI をインストールして初期化する。すでに gcloud CLI をインストールしている場合は、gcloud components update を実行して最新のバージョンを取得する。

データを永続ディスクに保存する

ノードプールをアップグレードする前に、保持するデータが、Persistent Disk を使用する永続ボリュームを使用した Pod に保存されていることを確認する必要があります。永続ディスクは、アップグレード時にデータを消去せずにマウント解除され、そのデータはポッド間で「引き渡され」ます。

永続ディスクには次の制限があります。

• ポッドを実行しているノードが Compute Engine VM であること
• これらの VM が Persistent Disk と同じ Compute Engine プロジェクトおよびゾーンに存在すること

既存のノード インスタンスに永続ディスクを追加する方法については、Compute Engine ドキュメントのゾーン永続ディスクの追加またはサイズ変更をご覧ください。

アップグレードについて

クラスタのコントロール プレーンとノードは個別にアップグレードされます。

クラスタのコントロール プレーンは、クラスタがリリース チャンネルに登録されているかどうかにかかわらず、定期的にアップグレードされます。

アップグレードの通知を事前に受け取るには、クラスタ通知の受信をご覧ください。

制限事項

アルファ クラスタはアップグレードできません。

サポート対象のバージョン

新しいバージョンがリリースされたときや、古いバージョンが廃止されたときに、リリースノートで通知されます。次のコマンドを使用すると、サポート対象のクラスタとノードのバージョンをいつでも確認できます。

gcloud container get-server-config

クラスタがリリース チャンネルに登録されている場合は、コントロール プレーンと同じマイナー バージョンの別のリリース チャンネルのパッチ バージョンにアップグレードできます。たとえば、クラスタを Regular チャンネルのバージョン 1.21.12-gke.1700 から Rapid チャンネルの 1.21.13-gke.900 にアップグレードできます。詳細については、新しいチャンネルからのパッチ バージョンの実行をご覧ください。すべての Autopilot クラスタがリリース チャンネルに登録されます。

ダウングレードの制限事項

特定のシナリオでは、クラスタのバージョンを以前のバージョンにダウングレードできます。

バージョンが同じマイナー バージョンの旧パッチ リリースであれば、クラスタ コントロール プレーンのアップグレードの失敗を回避するために、コントロール プレーンを以前のパッチ リリースにダウングレードできます。たとえば、クラスタのコントロール プレーンが GKE 1.25.3-gke.400 を実行している場合、そのバージョンがまだ使用可能であれば、コントロール プレーンを 1.25.2-gke.100 にダウングレードできます。

Kubernetes クラスタ コントロール プレーンを以前のマイナー バージョンにダウングレードすることはできません。たとえば、コントロール プレーンが GKE バージョン 1.25 を実行している場合、1.24 にダウングレードすることはできません。これを行おうとすると、次のエラー メッセージが表示されます。

ERROR: (gcloud.container.clusters.upgrade) ResponseError: code=400,
message=Master cannot be upgraded to "1.24.3-gke.100": specified version is not
newer than the current version.

クラスタのコントロール プレーンのマイナーバージョンはダウングレードできないため、新しいマイナー バージョンが利用可能になり、それがデフォルトのバージョンになる前に、テスト環境のクラスタでマイナー バージョンのアップグレードをテストして検証することをおすすめします。これは、次のマイナー バージョンの重要な変更（非推奨の API や機能の削除など）により、クラスタに影響が生じる可能性がある場合に特におすすめします。

ノードプールのアップグレードの失敗を回避するために、ノードプールを以前のパッチ リリースまたはマイナー バージョンにダウングレードできます。ノードは、クラスタ コントロール プレーンのバージョンより 2 つ前のマイナー バージョンにダウングレードしないでください。

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

クラスタとノードは自動的にアップグレードされます。クラスタとそのノードに適用される自動アップグレードの内容をより細かく管理するには、リリース チャンネルに登録します。すべての Autopilot クラスタがリリース チャンネルに自動的に登録されます。

クラスタの GKE バージョンの管理についての詳細は、アップグレードに関する記事をご覧ください。

手動アップグレードは、新しいバージョンの提供後であればいつでも開始できます。

コントロール プレーンの手動アップグレード

クラスタのアップグレードを開始すると、コントロール プレーンに再びアクセスできるようになるまで、数分間はクラスタの構成を変更できません。コントロール プレーンのアップグレード中のダウンタイムを防ぐ必要がある場合は、Autopilot クラスタまたは Standard リージョン クラスタの使用を検討してください。コントロール プレーンのアップグレード中にワークロードが使用可能のままになるため、このオペレーションはワークロードが実行されるワーカーノードの可用性には影響しません。

Google Cloud コンソールまたは Google Cloud CLI を使用して、Autopilot または Standard のコントロール プレーンを手動でアップグレードできます。

gcloud container get-server-config

gcloud container clusters upgrade CLUSTER_NAME --master

gcloud container clusters upgrade CLUSTER_NAME --master \
    --cluster-version VERSION

Standard コントロール プレーンをアップグレードした後、そのノードをアップグレードできます。デフォルトでは、Google Cloud コンソールで作成した Standard ノードでは自動アップグレードが有効になります。このため、アップグレードは自動的に行われます。Autopilot では、常にノードは自動的にアップグレードされます。

クラスタのダウングレード

1. ダウングレード後にコントロール プレーンが自動的にアップグレードされないように、ダウングレードする前にメンテナンスの除外を設定します。

2. クラスタ コントロール プレーンを以前のパッチ バージョンにダウングレードします。

    gcloud container clusters upgrade CLUSTER_NAME \
        --master --cluster-version VERSION
   

クラスタの自動アップグレードの無効化

GKE では、インフラストラクチャのセキュリティは優先度の高い事項であるため、コントロール プレーンのアップグレードは定期的に実施され、無効にはできません。ただし、メンテナンスの時間枠と除外を適用すると、コントロール プレーンとノードのアップグレードを一時停止できます。

推奨されませんが、ノードの自動アップグレードを無効にすることは可能です。

最近のコントロール プレーンのアップグレード履歴を確認する

クラスタの最近の自動アップグレード履歴のスナップショットを取得するには、クラスタのアップグレードに関する情報の取得（プレビュー）を行います。

または、最近のオペレーションを一覧表示して、コントロール プレーンがいつアップグレードされたかを確認することもできます。

gcloud container operations list --filter="TYPE:UPGRADE_MASTER AND TARGET:CLUSTER_NAME"

CLUSTER_NAME は、使用するクラスタの名前に置き換えます。

ノードプールのアップグレード

デフォルトでは、クラスタのノードで自動アップグレードが有効になっています。ノードの自動アップグレードにより、クラスタのコントロール プレーンとノードのバージョンが同期されており、Kubernetes バージョン スキュー ポリシーに準拠していることが保証されます。これにより、コントロール プレーンはコントロール プレーンの 2 つ前までのマイナー バージョンのノードと互換性が保証されています。たとえば、Kubernetes 1.29 コントロール プレーンは Kubernetes 1.27 ノードと互換性があります。

GKE ノードプールのアップグレードでは、サージ アップグレードと Blue/Green アップグレードの 2 つの構成可能なアップグレード戦略を選択できます。

クラスタ環境のニーズに最適な戦略を選択し、戦略を調整するパラメータを使用します。

ノードのアップグレードの仕組み

ノードがアップグレードされている間、GKE は新しい Pod のスケジュールを停止し、実行中の Pod を他のノードにスケジュールします。これは、ノードプールで機能を有効または無効にする場合など、ノードの再作成を行う他のイベントも同様です。

ノードの自動アップグレード中または手動アップグレード中、PodDisruptionBudgets（PDB）と Pod の停止猶予期間は最大 1 時間使用されます。ノードで実行中の Pod を 1 時間後に新しいノードにスケジュールできない場合でも、GKE はアップグレードを開始します。maxUnavailable フィールドを 0 または 0% に設定するか、minAvailable フィールドを 100% またはレプリカ数に設定して、すべてのレプリカを常に使用できるように PDB を構成している場合でも、この動作は適用されます。これらのシナリオではすべて、ノードの削除が行われるように、1 時間後に Pod が削除されます。

アップグレードは、すべてのノードが再作成され、クラスタが望ましい状態になったときにはじめて完了します。新しくアップグレードされたノードがコントロール プレーンに登録されると、GKE ではノードがスケジューリング可能であるとマークされます。

新しいノード インスタンスでは、目的の Kubernetes バージョンと次のものが実行されます。

• ノードイメージ
• kubelet
• kube-proxy

ノードプールの手動アップグレード

手動でアップグレードできるノードプールのバージョンは、コントロール プレーンと同じバージョンか、引き続き使用可能でコントロール プレーンと互換性のある以前のバージョンです。複数のノードプールを同時に手動でアップグレードできますが、GKE が自動で一度にアップグレードするノードプールは 1 つだけです。

ノードプールを手動でアップグレードすると、kubectl を使用して個々のノードに追加したラベルが削除されます。これを回避するには、ノードプールにラベルを適用します。

ノードプールを手動でアップグレードする前に、次の条件を検討してください。

• ノードプールをアップグレードすると、そのノードプールで実行中のワークロードが中断される可能性があります。これを回避するには、目的のバージョンで新しいノードプールを作成しワークロードを移行します。移行後、古いノードプールは削除できます。
• エラー状態の Ingress でノードプールをアップグレードすると、インスタンス グループは同期しません。この問題を回避するには、まず、kubectl get ing コマンドでステータスを確認します。インスタンス グループが同期されていない場合は、Ingress の作成に使用したマニフェストを再適用して問題を回避します。

ノードプールは、Google Cloud コンソールか Google Cloud CLI を使用して、コントロール プレーンと互換性のあるバージョンに手動でアップグレードできます。

gcloud container clusters upgrade CLUSTER_NAME \
  --node-pool=NODE_POOL_NAME

gcloud container clusters upgrade CLUSTER_NAME \
  --node-pool=NODE_POOL_NAME \
  --cluster-version VERSION

ノードプールのダウングレード

たとえば、ノードプールのアップグレードの失敗の可能性を軽減するために、ノードプールをダウングレードできます。ノードプールをダウングレードする前に、制限事項を確認してください。

1. ダウングレード後に GKE によってノードプールが自動的にアップグレードされないようにするには、メンテナンスの除外をクラスタに設定します。
2. ノードプールをダウングレードするには、ノードプールの手動アップグレードの手順に沿って、以前のバージョンを指定します。

サージ アップグレード パラメータを変更する

サージ アップグレード パラメータの変更の詳細については、サージ アップグレードを構成するをご覧ください。

ノードプールのアップグレード ステータスを確認する

アップグレードのステータスは、gcloud container operations で確認できます。

クラスタ内の実行中のオペレーションと完了したオペレーションの全リストを表示します。

gcloud container operations list

各オペレーションには、開始時刻と終了時刻、ターゲット クラスタ、ステータスとともに、オペレーション ID とオペレーション タイプが割り当てられています。このリストの表示例を次に示します。

NAME                              TYPE                ZONE           TARGET              STATUS_MESSAGE  STATUS  START_TIME                      END_TIME
operation-1505407677851-8039e369  CREATE_CLUSTER      us-west1-a     my-cluster                          DONE    20xx-xx-xxT16:47:57.851933021Z  20xx-xx-xxT16:50:52.898305883Z
operation-1505500805136-e7c64af4  UPGRADE_CLUSTER     us-west1-a     my-cluster                          DONE    20xx-xx-xxT18:40:05.136739989Z  20xx-xx-xxT18:41:09.321483832Z
operation-1505500913918-5802c989  DELETE_CLUSTER      us-west1-a     my-cluster                          DONE    20xx-xx-xxT18:41:53.918825764Z  20xx-xx-xxT18:43:48.639506814Z

特定のオペレーションに関する詳細情報を取得するには、次のコマンドに示すようにオペレーション ID を指定します。

gcloud container operations describe OPERATION_ID

次に例を示します。

gcloud container operations describe operation-1507325726639-981f0ed6
endTime: '20xx-xx-xxT21:40:05.324124385Z'
name: operation-1507325726639-981f0ed6
operationType: UPGRADE_CLUSTER
selfLink: https://container.googleapis.com/v1/projects/.../kubernetes-engine/docs/zones/us-central1-a/operations/operation-1507325726639-981f0ed6
startTime: '20xx-xx-xxT21:35:26.639453776Z'
status: DONE
targetLink: https://container.googleapis.com/v1/projects/.../kubernetes-engine/docs/zones/us-central1-a/clusters/...
zone: us-central1-a

ノードプールのアップグレード設定を確認する

ノードプールで使用されているノードのアップグレード戦略の詳細を確認するには、gcloud container node-pools describe コマンドを使用します。Blue/Green アップグレードの場合、このコマンドによりアップグレードの現在のフェーズも返されます。

次のコマンドを実行します。

gcloud container node-pools describe NODE_POOL_NAME \
--cluster=CLUSTER_NAME

次のように置き換えます。

• NODE_POOL_NAME: 記述するノードプールの名前。
• CLUSTER_NAME: 記述するノードプールのクラスタの名前。

このコマンドにより、現在のアップグレード設定が出力されます。次の例は、Blue/Green アップグレード戦略を使用している場合の出力を示しています。

upgradeSettings:
  blueGreenSettings:
    nodePoolSoakDuration: 1800s
    standardRolloutPolicy:
      batchNodeCount: 1
      batchSoakDuration: 10s
  strategy: BLUE_GREEN

Blue/Green アップグレード戦略を使用している場合、出力には Blue/Green アップグレードの設定と現在の中間フェーズの詳細も含まれます。 たとえば次のように表示されます。

updateInfo:
  blueGreenInfo:
    blueInstanceGroupUrls:
    - https://www.googleapis.com/compute/v1/projects/{PROJECT_ID}/zones/{LOCATION}/instanceGroupManagers/{BLUE_INSTANCE_GROUP_NAME}
    bluePoolDeletionStartTime: {BLUE_POOL_DELETION_TIME}
    greenInstanceGroupUrls:
    - https://www.googleapis.com/compute/v1/projects/{PROJECT_ID}/zones/{LOCATION}/instanceGroupManagers/{GREEN_INSTANCE_GROUP_NAME} 
    greenPoolVersion: {GREEN_POOL_VERSION}
    phase: DRAINING_BLUE_POOL

ノードプールのアップグレードをキャンセルする

アップグレードはいつでもキャンセルできます。サージ アップグレードをキャンセルした場合の影響については、サージ アップグレードをキャンセルするをご覧ください。 Blue/Green アップグレードをキャンセルした場合の影響については、Blue/Green アップグレードをキャンセルするをご覧ください。

1. アップグレードのオペレーション ID を取得します。

   gcloud container operations list
   

2. アップグレードをキャンセルします。

   gcloud container operations cancel OPERATION_ID
   

詳しくは、gcloud container operations cancel のドキュメントをご覧ください。

ノードプールのアップグレードを再開する

アップグレードを手動で開始することで、アップグレードを再開できます。その場合も、元のアップグレードのターゲット バージョンを指定します。

たとえば、アップグレードが失敗した場合や、進行中のアップグレードを一時停止した場合は、最初のアップグレード オペレーションのターゲット バージョンを指定して、ノードプールで同じアップグレードを再度開始することで、キャンセルしたアップグレードを再開できます。

アップグレードを再開した場合の影響については、サージ アップグレードを再開すると Blue/Green アップグレードを再開するをご覧ください。

アップグレードを再開するには、次のコマンドを使用します。

    gcloud container clusters upgrade CLUSTER_NAME \
      --node-pool=NODE_POOL_NAME \
      --cluster-version VERSION

次のように置き換えます。

• NODE_POOL_NAME: ノードプールのアップグレードを再開するノードプールの名前。
• CLUSTER_NAME: アップグレードを再開するノードプールのクラスタの名前。
• VERSION: キャンセルされたノードプールのアップグレードのターゲット バージョン。

詳しくは、gcloud container clusters upgrade のドキュメントをご覧ください。

ノードプールのアップグレードのロールバック

ノードプールをロールバックして、アップグレードしたノードをノードプールのアップグレードを開始する前の元の状態にダウングレードできます。

進行中のアップグレードがキャンセルされた場合、アップグレードが失敗した場合、またはメンテナンスの時間枠のタイムアウトが原因でアップグレードが完了していない場合は、rollback コマンドを使用します。バージョンを指定する場合は、手順に沿ってノードプールをダウングレードします。

ノードプールのアップグレードをロールバックした場合の影響については、サージ アップグレードをロールバックするまたは Blue/Green アップグレードをロールバックするをご覧ください。

アップグレードをロールバックするには、次のコマンドを実行します。

gcloud container node-pools rollback NODE_POOL_NAME \
  --cluster CLUSTER_NAME

次のように置き換えます。

• NODE_POOL_NAME: ノードプールのアップグレードをロールバックするノードプールの名前。
• CLUSTER_NAME: アップグレードをロールバックするノードプールのクラスタの名前。

詳しくは、gcloud container node-pools rollback のドキュメントをご覧ください。

ノードプールのアップグレードを完了する

Blue/Green アップグレード戦略を使用している場合は、ソークフェーズ中にノードプールのアップグレードが完了すると、残りのソーク時間をスキップできます。

ノードプールのアップグレードを完了する方法については、ノードプールのアップグレードを完了するをご覧ください。

Blue/Green アップグレード戦略を使用している場合にアップグレードを完了するには、次のコマンドを実行します。

gcloud container node-pools complete-upgrade NODE_POOL_NAME \
  --cluster CLUSTER_NAME

次のように置き換えます。

• NODE_POOL_NAME: アップグレードを完了するノードプールの名前。
• CLUSTER_NAME: アップグレードを完了するノードプールのクラスタの名前。

詳しくは、gcloud container node-pools complete-upgrade のドキュメントをご覧ください。

既知の問題

追加の中断を許可できない PodDisruptionBudget オブジェクトが構成されている場合、ノードのアップグレードを繰り返し試行しても、コントロール プレーン バージョンへのアップグレードが失敗する可能性があります。このエラーを回避するには、Deployment または HorizontalPodAutoscaler をスケールアップして、PodDisruptionBudget 構成を維持しながらノードをドレインすることをおすすめします。

中断を許可しないすべての PodDisruptionBudget オブジェクトを表示するには、次を行います。

kubectl get poddisruptionbudget --all-namespaces -o jsonpath='{range .items[?(@.status.disruptionsAllowed==0)]}{.metadata.name}/{.metadata.namespace}{"\n"}{end}'

自動アップグレードで問題が発生する可能性がありますが、自動アップグレード プロセスではノードのアップグレードを強制的に行います。ただし、アップグレードは istio-system Namespace のノードが PodDisruptionBudget に違反するたびに 1 時間余分にかかります。

トラブルシューティング

未完了のノードプールのアップグレードを再開またはロールバックする

GKE がノードプールのアップグレードを完了せず、ノードが新しいバージョンに部分的にアップグレードされている場合は、アップグレードを再開するか、ロールバックできます。これは、ノード アップグレード戦略（サージ アップグレードまたは Blue/Green アップグレード）を使用するノードプールのアップグレードに関連しています。

ノードプールが部分的にアップグレードされる理由は次のとおりです。

• ノードプールのアップグレードをキャンセルしました。
• 予期しない問題が発生したため、アップグレードに失敗しました。
• メンテナンスの時間枠のタイムアウトが原因でアップグレードが完了していません。

手順に沿ってアップグレードを再開またはロールバックし、ノードプール内のすべてのノードが一貫したバージョンを実行するようにします。何もしないと、メンテナンスが利用可能になると、GKE はノードプールのアップグレードを再試行します。

ノードの CPU 使用率が予想より高い

一部の Pod の CPU 使用率が、実行中の Pod の予想値を上回ることがあります。

これは、クラスタまたはノードがサポートされているバージョンを実行していない場合に発生します。リリースノートで、使用しているバージョンが利用可能であり、サポートされていることを確認してください。次のコマンドを実行して、サポート対象のすべてのクラスタとノードのバージョンを一覧表示することもできます。

gcloud container get-server-config

次のステップ

• クラスタ アーキテクチャについて学習する。
• リリース チャンネルについて学習する。