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

このドキュメントでは、Google Kubernetes Engine（GKE）クラスタのコントロール プレーンまたはノードのアップグレードとダウングレードを手動でリクエストする方法について説明します。GKE は、コントロール プレーンとノードのバージョンを自動的にアップグレードし、クラスタに新機能、バグの修正、セキュリティ パッチが確実に適用されるようにします。ただし、このドキュメントで説明するように、これらのアップグレードを手動で実行することもできます。

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

バージョンは次のように手動でアップグレードできます。

クラスタをアップグレードするために、GKE はコントロール プレーンとノードが実行するバージョンを個別のオペレーションで更新します。クラスタは、新しいマイナー バージョン（1.33 から 1.34 など）または新しいパッチ バージョン（1.33.4-gke.1350000 から 1.33.5-gke.1080000 など）にアップグレードされます。クラスタのコントロール プレーンとノードは、常に同じバージョンを実行するとは限りません。バージョンの詳細については、GKE のバージョニングとサポートをご覧ください。

自動アップグレードや手動アップグレードなど、クラスタのアップグレードの仕組みについて詳しくは、GKE クラスタのアップグレードについてをご覧ください。

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

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

始める前に

作業を始める前に、次のタスクが完了していることを確認してください。

  • Google Kubernetes Engine API を有効にする。
    • Google Kubernetes Engine API を有効化
  • このタスクに Google Cloud CLI を使用する場合は、gcloud CLI をインストールして初期化する。gcloud CLI をインストール済みの場合は、gcloud components update コマンドを実行して最新のバージョンを取得します。以前のバージョンの gcloud CLI では、このドキュメントのコマンドを実行できない場合があります。
  • すでに Autopilot クラスタまたは Standard クラスタが存在していることを確認する。新しいクラスタを作成するには、Autopilot クラスタを作成するをご覧ください。

アップグレードについて

クラスタのコントロール プレーンとノードは個別にアップグレードされます。クラスタのコントロール プレーンとノードは、常に同じバージョンを実行するとは限りません。

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

制限事項

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

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

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

gcloud container get-server-config \
    --location=CONTROL_PLANE_LOCATION

CONTROL_PLANE_LOCATION は、コントロール プレーンのロケーション（リージョンまたはゾーン）（us-central1 や us-central1-a など）に置き換えます。

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

ダウングレードについて

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

上記のシナリオ以外では、クラスタをダウングレードできません。ワンステップのコントロール プレーンのマイナー アップグレード後を含め、クラスタ コントロール プレーンを以前のマイナー バージョンにダウングレードすることはできません。たとえば、コントロール プレーンが GKE バージョン 1.34 を実行している場合、1.33 にダウングレードすることはできません。これを行おうとすると、次のエラー メッセージが表示されます。

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

新しいマイナー バージョンが利用可能になり、それがクラスタの自動アップグレードの対象になる前に、テスト環境のクラスタでマイナー バージョンのアップグレードをテストして検証することをおすすめします。これは、次のマイナー バージョンの重要な変更（非推奨の API や機能の削除など）により、クラスタに影響が生じる可能性がある場合に特におすすめします。バージョンの可用性について詳しくは、チャンネルで使用できるバージョンをご覧ください。

クラスタのコントロール プレーンをアップグレードする

GKE は、クラスタのコントロール プレーンとノードを自動的にアップグレードします。GKE によるクラスタのアップグレード方法を管理するには、クラスタのアップグレードを制御するをご覧ください。

Autopilot クラスタとリージョン Standard クラスタの場合、コントロール プレーンのアップグレード中もコントロール プレーンは引き続き使用できます。ただし、ゾーンクラスタのコントロール プレーンのアップグレードを開始すると、コントロール プレーンに再びアクセスできるようになるまで、クラスタの構成を変更できません。コントロール プレーンのアップグレード中にワークロードが使用可能のままになるため、コントロール プレーンのアップグレードはワークロードが実行されるワーカーノードの可用性には影響しません。

クラスタのバージョン管理の一環として、新しいバージョンが利用可能になった後、次のいずれかの方法で手動アップグレードをいつでも開始できます。

  • ワンステップ アップグレード: コントロール プレーンをできるだけ早く、より新しいマイナー バージョンまたはパッチ バージョンに直接アップグレードします。このアプローチは、新しいマイナー バージョンでクラスタとワークロードのパフォーマンスをすでに検証している場合に使用できます。
  • ロールバックの安全性を備えた 2 段階のコントロール プレーンのマイナー アップグレード （プレビュー）: 2 段階のプロセスを使用して、コントロール プレーンを新しいマイナー バージョンにアップグレードします。このプロセスでは、一定期間新しいマイナー バージョンを検証し、必要に応じてロールバックできます。このアップグレード方法は、手動のマイナー コントロール プレーン アップグレードで 1.33 以降にアップグレードする場合にのみ使用できます。

ワンステップ アップグレードでコントロール プレーンを手動でアップグレードする

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

コンソール

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

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

    Google Kubernetes Engine に移動

  2. クラスタの名前をクリックします。

  3. [クラスタの基本] で、[バージョン] の横にある [ アップグレード可能] をクリックします。

  4. 新しいバージョンを選択し、[変更を保存] をクリックします。

gcloud

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

gcloud container get-server-config \
    --location=CONTROL_PLANE_LOCATION

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

gcloud container clusters upgrade CLUSTER_NAME \
    --master \
    --location=CONTROL_PLANE_LOCATION

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

gcloud container clusters upgrade CLUSTER_NAME \
    --master \
    --location=CONTROL_PLANE_LOCATION \
    --cluster-version=VERSION

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

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

ロールバックの安全性を備えた 2 段階のコントロール プレーンのマイナー アップグレード

GKE Autopilot クラスタまたは Standard クラスタのコントロール プレーンは、2 段階のアップグレードで次のマイナー バージョンに手動でアップグレードできます。この 2 段階のプロセスでは、エミュレートされたバージョンと呼ばれる前のマイナー バージョンの機能と API を使用しながら、バイナリ バージョンと呼ばれる新しいマイナー バージョンでクラスタのパフォーマンスをテストできます。このソーク時間中、コントロール プレーンはエミュレート モードと呼ばれるモードで実行されます。必要に応じて、以前のマイナー バージョンにロールバックできます。Kubernetes でこのタイプのアップグレードがどのように許可されるかについては、Kubernetes コントロール プレーン コンポーネントの互換性バージョンをご覧ください。

2 段階アップグレードは次のように機能します。

  1. バイナリ アップグレード: GKE はコントロール プレーンのバイナリを新しいマイナー バージョンにアップグレードしますが、以前のマイナー バージョンをエミュレートします。

    • 以前のバージョンをエミュレートする: クラスタは新しいバイナリを実行しますが、以前のマイナー バージョンの API の動作をエミュレートし続けます。たとえば、新しいマイナー バージョンで削除されたが、以前のマイナー バージョンではまだ使用可能な API を呼び出すことができます。
    • 新しいバイナリをテストする: 新しいマイナー バージョンで使用可能な Kubernetes 機能を利用可能にする前に、回帰、修正、パフォーマンスの変更について新しいバイナリをテストできます。アプリケーションの指標、ログ、Pod のステータス、エラー率、レイテンシをモニタリングします。
    • 変更を浸透させる: テストとモニタリングを行う時間を確保するため、6 時間から 7 日間待ちます。この時間が経過すると、GKE はエミュレートされたバージョンのアップグレードを実行します。
    • アップグレードをロールバックまたは完了する: 必要に応じてロールバックできます。また、新しいマイナー バージョンに自信があり、ソーク時間の完了を待たずに、新機能と API の変更の使用を開始する準備ができている場合は、次のステージに進むこともできます。

  2. エミュレートされたバージョンのアップグレード: GKE は、新しいバイナリ バージョンに合わせてエミュレートされたバージョンを更新します。

    • 新機能を有効にする: 新しいマイナー バージョンのすべての新機能と API の変更が有効になります。
    • ロールバック不可: この手順が完了すると、元のマイナー バージョンにロールバックできなくなります。アップグレードが完了しました。

このオペレーションでは、次の制限が適用されます。

  • ワンステップのコントロール プレーンのマイナー アップグレードを開始することはできません。
  • エミュレートされたバージョンより新しいバージョンでノードを作成またはアップグレードすることはできません。
  • GKE は、コントロール プレーンまたはノードに対して自動アップグレードを実行しません。

2 段階アップグレードを開始する

次のコマンドを実行して、2 段階のアップグレードを開始します。

gcloud beta container clusters upgrade CLUSTER_NAME \
  --location=CONTROL_PLANE_LOCATION \
  --cluster-version VERSION \
  --control-plane-soak-duration SOAK_DURATION \
  --master

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

  • CLUSTER_NAME: クラスタの名前。
  • CONTROL_PLANE_LOCATION: コントロール プレーンのロケーション（リージョンまたはゾーン）。たとえば、us-central1 や us-central1-a です。
  • VERSION: 次のマイナー バージョンの特定のパッチ。たとえば、クラスタが 1.33 を実行している場合は 1.34.1-gke.1829001 です。
  • SOAK_DURATION: ロールバック セーフ ステージでの待機時間。この値は、gcloud topic datetimes のリファレンスで説明されているように、絶対期間形式を使用して、最小 6 時間から最大 7 日間まで設定できます。たとえば、2 日と 1 時間のソーク時間の場合は 2d1h を使用します。

2 段階アップグレード中に新しいバイナリをテストする

ソーク時間中に、新しいバイナリを実行しているコントロール プレーンを含むクラスタとワークロードが想定どおりに動作することを確認します。ワークロードが新しいバイナリと互換性があることを確認できるかどうかに応じて、次のいずれかの手順を行います。

  • ロールバック: 新しいバイナリで実行されているワークロードで問題が発生した場合は、以前のマイナー バージョンにロールバックできます。
  • アップグレードを完了する: ワークロードが新しいバイナリで問題なく実行されることを確認したら、新しいバージョンの機能と API の使用を開始する場合は、アップグレードを完了できます。
  • 待機: ソーク時間が経過するまで待つこともできます。その後、GKE はエミュレートされたバージョンのアップグレードを実行し、新しいマイナー バージョンの機能と API の使用に移行します。
進行中のアップグレードを確認する

進行中のアップグレードに関する情報を取得するには、次のいずれかのリソースを使用します。

バイナリ バージョンのアップグレード後に 2 段階アップグレードをロールバックする

2 段階アップグレードでは、バイナリ バージョンのアップグレード後にソーク期間があります。この期間中は、必要に応じて以前のマイナー バージョンにロールバックできます。GKE がエミュレートされたバージョンのアップグレードを実行した後は、ロールバックできません。

ロールバック オペレーションが完了すると、コントロール プレーンは 2 段階アップグレードを開始する前と同じように、以前のマイナー バージョンを実行します。

可能であれば、次の手順でロールバックします。

  1. クラスタレベルでアップグレード情報を取得するで gcloud CLI コマンドを実行して、コントロール プレーンを以前のマイナー バージョンにロールバックできることを確認します。コマンドの出力から、ロールバックできるかどうかを判断します。

    • 出力に rollbackSafeUpgradeStatus セクションがある場合は、ロールバックできます。そのセクションで、次の手順の VERSION 変数の previousVersion を保存します。次のステップに進みます。
    • rollbackSafeUpgradeStatus セクションがない場合は、ロールバックできません。これは、GKE がすでにエミュレートされたバージョン アップグレードを実行したことを示します。次の手順を実行できません。

  2. 前の手順でロールバックが可能と判断された場合は、以前のバージョンにロールバックします。

    gcloud container clusters upgrade CLUSTER_NAME \
  --location=CONTROL_PLANE_LOCATION \
  --cluster-version VERSION
  --master

    VERSION は、以前に使用したパッチ バージョンと完全に一致している必要があります。このバージョンは前の手順で保存しました。

このコマンドを実行して以前のバージョンにダウングレードすると、新しいバイナリでワークロードが正しく実行されなかった理由を特定できます。必要に応じて、Cloud カスタマーケアにお問い合わせください。その際、関連するログ、エラー メッセージ、発生した検証エラーの詳細を提供してください。詳細については、サポートを利用するをご覧ください。

問題を解決したら、新しいマイナー バージョンに手動でアップグレードできます。

2 段階のアップグレードを完了する

ソーク期間中に、新しいバイナリでワークロードが正常に実行されていることを確認したら、残りのソーク時間をスキップできます。

gcloud beta container clusters clusters complete-control-plane-upgrade CLUSTER_NAME  \
  --location=CONTROL_PLANE_LOCATION

このコマンドを実行すると、以前のマイナー バージョンにダウングレードできなくなります。

コントロール プレーンを以前のパッチ バージョンにダウングレードする

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

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

     gcloud container clusters upgrade CLUSTER_NAME \
     --master \
     --location=CONTROL_PLANE_LOCATION \
     --cluster-version=VERSION

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

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

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

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

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

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

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

ノードプールをアップグレードしてください

デフォルトでは、Standard ノードプールに対して自動アップグレードが有効になっています。また、Standard クラスタ内の Autopilot 管理のノードプールすべてに対して、常に自動アップグレードが有効になっています。ノードの自動アップグレードにより、クラスタのコントロール プレーンとノードのバージョンが同期され、Kubernetes バージョン スキュー ポリシーに準拠していることが保証されます。これにより、コントロール プレーンとその 2 つ前までのマイナー バージョンのノードとの適合性が保証されます。たとえば、Kubernetes 1.34 コントロール プレーンは Kubernetes 1.32 ノードと互換性があります。デフォルトでは、GKE は一度に 1 つのノードプールのみを自動的にアップグレードします。複数のノードプールを同時に自動アップグレードするには、ノードプールの同時アップグレードを構成します（プレビュー）。

ベスト プラクティス:

Standard ノードプールでノードの自動アップグレードを無効にすることは避けます。有効にしておくことで、クラスタは前の段落で説明したアップグレードのメリットを享受できます。

GKE Standard ノードプールのアップグレードでは、サージ アップグレード、Blue/Green アップグレード、自動スケーリングされる Blue/Green アップグレード（プレビュー）など、3 つの構成可能なアップグレード戦略から選択できます。Standard クラスタの Autopilot 管理ノードプールでは、常にサージ アップグレードが使用されます。

Standard ノードプールでは、いずれかの戦略を選択したうえで、クラスタ環境のニーズに合うようにパラメータを使用して戦略を調整します。

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

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

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

ベスト プラクティス:

Standard ノードプールで実行中のワークロードの正常終了にさらに柔軟性が必要な場合は、Blue/Green アップグレードを使用すると、PDB チェックをデフォルトの 1 時間より長くする追加のソーク時間を設定できます。

ノードが停止されるときの一般的な動作については、Pod に関するトピックをご覧ください。

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

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

ノードプールのアップグレードが完了したと見なされるには、ノードプール内のすべてのノードが再作成されている必要があります。アップグレードが開始されたものの完了せず、部分的にアップグレードされた状態になっている場合、ノードプールのバージョンにすべてのノードのバージョンが反映されていない可能性があります。詳細については、ノードプールのアップグレードが不完全で一部のノードのバージョンがノードプールのバージョンと一致していないをご覧ください。ノードプールのアップグレードが終了したかどうかは、ノードプールのアップグレード ステータスで確認します。アップグレード オペレーションが保持期間を超えている場合は、各ノードのバージョンとノードプールのバージョンが一致しているかどうかを確認します。

アップグレードする前にデータを永続ディスクに保存する

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

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

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

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

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

Standard クラスタの Standard ノードプールまたは Autopilot 管理ノードプールのバージョンは、手動でアップグレードできます。コントロール プレーンのバージョンと一致させるか、引き続き使用可能でコントロール プレーンと適合性のある以前のバージョンを使用できます。ノードプールの同時アップグレードを構成すると、GKE が複数のノードプールを同時にアップグレードできるのと同様に、複数のノードプールを同時に手動でアップグレードできます。

GKE がノードプールをアップグレードすると（手動または自動）、kubectl を使用して個々のノードに追加したラベルが削除されます。ノードを再作成する GKE クラスタの他の種類の変更でも、ラベルが削除されます。ラベルが失われないようにするには、代わりにラベルをノードプールに適用します。

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

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

ノードプールは、コントロール プレーンと適合性のあるバージョンに手動でアップグレードできます。

  • Standard ノードプールの場合、 Cloud de Confiance コンソールまたは Google Cloud CLI を使用できます。

  • Autopilot 管理ノードプールの場合、Google Cloud CLI のみを使用できます。

コンソール

Cloud de Confiance コンソールを使用して Standard ノードプールをアップグレードするには、次の手順を行います。

  1. Cloud de Confiance コンソールで [Google Kubernetes Engine] ページに移動します。

    Google Kubernetes Engine に移動

  2. クラスタの名前をクリックします。

  3. [クラスタの詳細] ページで [ノード] タブをクリックします。

  4. [ノードプール] セクションで、アップグレードするノードプールの名前をクリックします。

  5. [ 編集] をクリックします。

  6. [ノードのバージョン] で [変更] をクリックします。

  7. [ノードのバージョン] プルダウン リストから必要なバージョンを選択し、[変更] をクリックします。

ノードのバージョンが変更されるまで数分かかることがあります。

gcloud

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

  • CLUSTER_NAME: アップグレードするノードプールのクラスタの名前。
  • NODE_POOL_NAME: アップグレードするノードプールの名前。
  • CONTROL_PLANE_LOCATION: コントロール プレーンのロケーション（リージョンまたはゾーン）。たとえば、us-central1 や us-central1-a です。
  • VERSION: ノードのアップグレード後の Kubernetes バージョン。たとえば、--cluster-version=1.34.1-gke.1293000 や cluster-version=latest です。

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

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

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

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

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

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

ノードプールをダウングレードする

GKE がノードプールのアップグレードを完了した場合、ノードプールをダウングレードできます。GKE は、部分的にアップグレードされたノードプールをダウングレードできません。ロールバックのみ可能です。部分的にアップグレードされたノードプールのダウングレードをトリガーしようとすると、GKE はそのオペレーションでノードプール内のノードを更新しません。ノードプールが完全にアップグレードされておらず、ロールバックのみ可能な状態かどうかを確認するには、まずノードプールのアップグレード ステータスを確認します。アップグレードがキャンセルされたか失敗した場合は、ノードプール内のノードを調べて、以前のバージョンを実行しているノードがまだあるかどうかを確認することで、ノードプールのアップグレードが完了していないことを確認できます。

ノードプールのアップグレードが完了せず、アップグレードされたノードを以前のバージョンにロールバックする場合は、ノードプールのアップグレードをロールバックするの手順に沿って操作します。ノードプールのアップグレードが完了し、ワークロードで問題が発生したため、アップグレードを元に戻す場合は、このセクションの手順に沿ってノードプールを以前のバージョンにダウングレードできます。ノードプールをダウングレードする前に、制限事項を確認してください。

ベスト プラクティス:

ワークロードに影響するノードプールのアップグレードのリスク軽減を最適化する必要がある場合は、ノードの Blue/Green アップグレード戦略を使用します。この戦略では、アップグレードが失敗した場合に、進行中のアップグレードを元のノードにロールバックできます。

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

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

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

ノードプールの同時アップグレードを構成する

デフォルトでは、GKE はノードプールを 1 つずつ自動的にアップグレードします。ノードプールが多いクラスタでは、ノードプールの同時アップグレードを構成して、クラスタのアップグレードに必要な合計時間を短縮できます。この設定を行うには、GKE が同時に自動アップグレードできるノードプールの最大数を設定します。Standard クラスタでは、この設定により、Standard ノードプールと Autopilot 管理ノードプールのノード アップグレードの同時実行数が決まります。Autopilot クラスタでは、この設定によってノードのグループのノード アップグレードの同時実行数が決まります。

同時実行数の上限は、gcloud CLI を使用して新しいクラスタを作成するか、既存のクラスタを更新するときに構成できます。同時に自動アップグレードするノードプールで、自動アップグレードが有効になっていることを確認します。

カスタム ステージを含むロールアウト シーケンス（プレビュー）に登録されているクラスタでこの機能を有効にすることはできません。

同時ノードプールのアップグレードを構成するには、次のいずれかのコマンドを実行します。

  • ノードプールの同時アップグレードが構成された新しいクラスタを作成します。

    gcloud beta container clusters create CLUSTER_NAME \
    --project=PROJECT_NAME
    --location CONTROL_PLANE_LOCATION \
    --node-pool-upgrade-concurrency-config=max-count=MAX_COUNT

  • 既存のクラスタを更新して、ノードプールを同時にアップグレードします。

    gcloud beta container clusters update CLUSTER_NAME \
    --project=PROJECT_NAME \
    --location=CONTROL_PLANE_LOCATION \
    --node-pool-upgrade-concurrency-config=max-count=MAX_COUNT

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

  • CLUSTER_NAME: クラスタの名前。
  • PROJECT_NAME: プロジェクトの名前。
  • LOCATION: クラスタのコンピューティング ロケーション。
  • MAX_COUNT: 同時にアップグレードするノードプールの最大数。値は 1～100 の整数にする必要があります。デフォルトの順次動作に戻すには、この値を 1 に設定します。

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

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

オペレーションの数が 5,000 件未満の場合は過去 12 日間、5,000 件以上の場合は過去 5,000 件の、クラスタ内の実行中のオペレーションと完了したオペレーションの全リストを表示します。

gcloud container operations list \
    --location=CONTROL_PLANE_LOCATION

各オペレーションには、開始時刻と終了時刻、ターゲット クラスタ、ステータスとともに、オペレーション 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 \
    --location=CONTROL_PLANE_LOCATION

例:

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 \
    --location=CONTROL_PLANE_LOCATION

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

  • NODE_POOL_NAME: 記述するノードプールの名前。
  • CLUSTER_NAME: 記述するノードプールのクラスタの名前。
  • CONTROL_PLANE_LOCATION: コントロール プレーンのロケーション（リージョンまたはゾーン）。例: us-central1、us-central1-a

このコマンドにより、現在のアップグレード設定が出力されます。次の例は、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 \
      --location=CONTROL_PLANE_LOCATION

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

    gcloud container operations cancel OPERATION_ID \
      --location=CONTROL_PLANE_LOCATION

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

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

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

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

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

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

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

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

  • NODE_POOL_NAME: ノードプールのアップグレードを再開するノードプールの名前。
  • CLUSTER_NAME: アップグレードを再開するノードプールのクラスタの名前。
  • CONTROL_PLANE_LOCATION: コントロール プレーンのロケーション（リージョンまたはゾーン）。例: us-central1、us-central1-a
  • VERSION: キャンセルされたノードプールのアップグレードのターゲット バージョン。

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

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

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

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

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

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

gcloud container node-pools rollback NODE_POOL_NAME \
    --cluster CLUSTER_NAME \
    --location=CONTROL_PLANE_LOCATION

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

  • NODE_POOL_NAME: ノードプールのアップグレードをロールバックするノードプールの名前。
  • CLUSTER_NAME: アップグレードをロールバックするノードプールのクラスタの名前。
  • CONTROL_PLANE_LOCATION: コントロール プレーンのロケーション（リージョンまたはゾーン）。例: us-central1、us-central1-a

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

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

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

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

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

gcloud container node-pools complete-upgrade NODE_POOL_NAME \
    --cluster CLUSTER_NAME \
    --location=CONTROL_PLANE_LOCATION

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

  • NODE_POOL_NAME: アップグレードを完了するノードプールの名前。
  • CLUSTER_NAME: アップグレードを完了するノードプールのクラスタの名前。
  • CONTROL_PLANE_LOCATION: コントロール プレーンのロケーション（リージョンまたはゾーン）。例: us-central1、us-central1-a

詳しくは、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 時間余分にかかります。

トラブルシューティング

トラブルシューティングについては、クラスタのアップグレードのトラブルシューティングをご覧ください。

次のステップ