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

Autopilot Standard

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 を実行して最新のバージョンを取得する。
注: gcloud CLI がすでにインストールされている場合には、必ず compute/region と compute/zone のプロパティを設定してください。デフォルトのロケーションを設定することで、gcloud CLI のエラー（One of [--zone, --region] must be supplied: Please specify location など）を防止できます。

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

ノードプールをアップグレードする前に、保持するデータが、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

クラスタのコントロールプレーンで使用可能なバージョンを確認するには、次のコマンドを実行します。

gcloud container get-server-config

デフォルトのクラスタバージョンにアップグレードするには、次のコマンドを実行します。

gcloud container clusters upgrade CLUSTER_NAME --master

デフォルト以外の特定のバージョンにアップグレードするには、--cluster-version フラグを指定します。次に例を示します。

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

VERSION は、クラスタのアップグレード後のバージョンに置き換えます。1.18.17-gke.100 のように特定のバージョンを使用することも、latest のようにバージョンのエイリアスを使用することもできます。詳細については、クラスタバージョンの指定をご覧ください。

コンソール

クラスタコントロールプレーンを手動で更新するには、次の手順に沿って操作します。

Google Cloud コンソールで Google Kubernetes Engine のページに移動します。

Google Kubernetes Engine に移動
目的のクラスタ名をクリックします。
[クラスタの基本] で、[バージョン] の横にある [ アップグレード可能] をクリックします。
目的のバージョンを選択し、[変更を保存] をクリックします。

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

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

ダウングレード後にコントロールプレーンが自動的にアップグレードされないように、ダウングレードする前にメンテナンスの除外を設定します。
クラスタコントロールプレーンを以前のパッチバージョンにダウングレードします。
```
 gcloud container clusters upgrade CLUSTER_NAME \
     --master --cluster-version VERSION
```

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

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

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

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

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

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

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

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

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

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

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

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

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

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

gcloud

このセクションのコマンドでは、次の変数を使用します。

CLUSTER_NAME: アップグレードするノードプールのクラスタの名前。
NODE_POOL_NAME: アップグレードするノードプールの名前。
VERSION: ノードのアップグレード先の Kubernetes バージョン。たとえば、--cluster-version=1.7.2 や cluster-version=latest です。

ノードプールをアップグレードします。

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

ノードで GKE の別のバージョンを指定するには、オプションの --cluster-version フラグを使用します。

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

バージョンの指定の詳細については、バージョニングに関する記事をご覧ください。

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

コンソール

Google Cloud コンソールを使用してノードプールをアップグレードするには、次の手順に沿って操作します。

Google Cloud コンソールで Google Kubernetes Engine のページに移動します。

Google Kubernetes Engine に移動
編集するクラスタの横にある [ アクション] をクリックし、[ 編集] をクリックします。
[クラスタの詳細] ページで [ノード] タブをクリックします。
[ノードプール] セクションで、アップグレードするノードプールの名前をクリックします。
[ 編集] をクリックします。
[ノードのバージョン] で [変更] をクリックします。
[ノードのバージョン] プルダウンリストから目的のバージョンを選択し、[変更] をクリックします。

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

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

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

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

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

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

アップグレードのステータスは、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 アップグレードをキャンセルするをご覧ください。

アップグレードのオペレーション ID を取得します。
```
gcloud container operations list
```
アップグレードをキャンセルします。
```
gcloud container operations cancel OPERATION_ID
```

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

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

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

たとえば、バージョン 1.23.1-gke.100 への進行中のアップグレードを一時停止した場合、バージョン 1.23.1-gke.100 を対象とするノードプールで同じアップグレードを再度開始すると、キャンセルしたアップグレードを再開できます。

アップグレードを再開した場合の影響については、サージアップグレードを再開すると 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 時間余分にかかります。

トラブルシューティング

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

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

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

gcloud container get-server-config

次のステップ

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

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

始める前に

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

アップグレードについて

制限事項

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

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

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

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

gcloud

コンソール

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

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

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

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

gcloud

コンソール

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

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

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

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

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

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

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

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

既知の問題

トラブルシューティング

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

次のステップ

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

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

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