クラスタのアップグレードに関するトラブルシューティングを行う

Google Kubernetes Engine（GKE）コントロール プレーンまたはノードプールのアップグレードが失敗した場合、停止した場合、または予期しないワークロードの動作が発生した場合は、プロセスのトラブルシューティングが必要になることがあります。コントロール プレーンとノードプールを最新の状態に保つことは、セキュリティとパフォーマンスにとって不可欠です。また、問題を解決することで、環境の安定性を維持できます。

一般的なアップグレードの問題を解決する最初のステップとして、クラスタのアップグレード プロセスをモニタリングすることをおすすめします。その後、次のような問題の解決に関するアドバイスが表示されます。

この情報は、アップグレードの停止や失敗の根本原因を診断し、メンテナンス ポリシーを管理して、バージョンの非互換性を解決したいプラットフォーム管理者と運用担当者にとって重要です。アプリケーション デベロッパーは、アップグレード後のワークロードの問題を解決するためのガイダンスを確認して、PodDisruptionBudgets などのワークロード構成がアップグレード時間にどのように影響するかを理解できます。 Google Cloud のコンテンツで使用されている一般的なロールとタスクの例の詳細については、一般的な GKE ユーザーのロールとタスクをご覧ください。

クラスタのアップグレード プロセスをモニタリングする

アップグレードの問題をより効果的に解決するには、まずアップグレード プロセスで何が起こったかを把握します。GKE には、このプロセスを可視化するためのツールがいくつか用意されています。

Google Cloud コンソールのアップグレード ダッシュボードには、進行中のすべてのクラスタ アップグレードのプロジェクト全体のビュー、最近のイベントのタイムライン、アクティブなメンテナンス除外や今後のバージョンの非推奨などの考えられる阻害要因に関する警告が表示されます。コマンドラインまたは自動チェックの場合は、gcloud container operations list コマンドを使用して、特定のアップグレード オペレーションのステータスを取得できます。詳細については、クラスタのアップグレードの可視性を高めるをご覧ください。

詳細な調査を行う場合は、Cloud Logging が主な情報源となります。GKE は、コントロール プレーンとノードプールのアップグレード プロセスの詳細情報を Cloud Logging に記録します。これには、主なアップグレード オペレーションを追跡する高レベルの監査ログに加え、特定のエラーに関する詳細情報を表示できる Kubernetes イベントやノード コンポーネントのログなど、より詳細なログも含まれます。

以降のセクションでは、ログ エクスプローラまたは gcloud CLI を使用してこれらのログをクエリする方法について説明します。詳細については、アップグレードのログを確認するをご覧ください。

監査ログでアップグレード オペレーションを特定する

どのアップグレード オペレーションが失敗したかわからない場合は、GKE 監査ログを使用できます。監査ログは管理アクションを追跡し、アップグレードが開始された日時とその最終ステータスの信頼できる記録を提供します。ログ エクスプローラで次のクエリを使用して、関連するオペレーションを見つけます。

イベントタイプ ログクエリ
コントロール プレーンの自動アップグレード 
resource.type="gke_cluster"
protoPayload.methodName="google.container.internal.ClusterManagerInternal.UpdateClusterInternal"
log_id("cloudaudit.googleapis.com/activity")
protoPayload.metadata.operationType="UPGRADE_MASTER"
resource.labels.cluster_name="CLUSTER_NAME"

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

このクエリは、対象となるコントロール プレーンのバージョンと以前のコントロール プレーンのバージョンを示します。
コントロール プレーンの手動アップグレード 
resource.type="gke_cluster"
log_id("cloudaudit.googleapis.com/activity")
protoPayload.response.operationType="UPGRADE_MASTER"
resource.labels.cluster_name="CLUSTER_NAME"

 
ノードプールの自動アップグレード（対象となるバージョンのみ） 
resource.type="gke_nodepool"
protoPayload.methodName="google.container.internal.ClusterManagerInternal.UpdateClusterInternal"
log_id("cloudaudit.googleapis.com/activity")
protoPayload.metadata.operationType="UPGRADE_NODES"
resource.labels.cluster_name="CLUSTER_NAME"
resource.labels.nodepool_name="NODEPOOL_NAME"

NODEPOOL_NAME は、クラスタに属するノードプールの名前に置き換えます。
ノードプールの手動アップグレード 
resource.type="gke_nodepool"
protoPayload.methodName="google.container.v1.ClusterManager.UpdateNodePool"
log_id("cloudaudit.googleapis.com/activity")
protoPayload.response.operationType="UPGRADE_NODES"
resource.labels.cluster_name="CLUSTER_NAME"
resource.labels.nodepool_name="NODEPOOL_NAME"

以前のノードプールのバージョンを確認するには、Kubernetes API ログを確認します。

resource.type="k8s_cluster"
resource.labels.cluster_name="CLUSTER_NAME"
protoPayload.methodName="nodes.patch"

GKE ログで詳細なエラー メッセージを確認する

監査ログで失敗したオペレーションとその日時を確認した後は、同じ時間帯に GKE コンポーネントからより詳細なエラー メッセージを検索できます。これらのログには、PodDisruptionBudget オブジェクトの構成ミスなど、アップグレードの失敗の具体的な理由が含まれている場合があります。

たとえば、監査ログで失敗した UPGRADE_NODES オペレーションを見つけた後、そのタイムスタンプを使用して検索を絞り込むことができます。ログ エクスプローラで次のクエリを入力し、時間範囲セレクタを使用して障害が発生した時間に焦点を当てます。

resource.type="k8s_node"
resource.labels.cluster_name="CLUSTER_NAME"
resource.labels.node_name="NODE_NAME"
severity=ERROR

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

  • CLUSTER_NAME: クラスタの名前。
  • NODE_NAME: エラーを確認するクラスタ内のノードの名前。

gcloud CLI を使用してアップグレード イベントを表示する

ログ エクスプローラに加え、gcloud CLI コマンドを使用してアップグレード イベントを確認することもできます。

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

gcloud container operations list --filter="TYPE=UPGRADE_MASTER"

出力は次のようになります。

NAME: operation-1748588803271-cfd407a2-bfe7-4b9d-8686-9f1ff33a2a96
TYPE: UPGRADE_MASTER
LOCATION: LOCATION
TARGET: CLUSTER_NAME
STATUS_MESSAGE:
STATUS: DONE
START_TIME: 2025-05-30T07:06:43.271089972Z
END_TIME: 2025-05-30T07:18:02.639579287Z

この出力には次の値が含まれます。

  • LOCATION: クラスタの Compute Engine のリージョンまたはゾーン（us-central1 や us-central1-a など）。
  • CLUSTER_NAME: クラスタの名前。

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

gcloud container operations list --filter="TYPE=UPGRADE_NODES"

出力は次のようになります。

NAME: operation-1748588803271-cfd407a2-bfe7-4b9d-8686-9f1ff33a2a96
TYPE: UPGRADE_NODES
LOCATION: LOCATION
TARGET: CLUSTER_NAME
STATUS_MESSAGE:
STATUS: DONE
START_TIME: 2025-05-30T07:06:43.271089972Z
END_TIME: 2025-05-30T07:18:02.639579287Z

例: ログを使用してコントロール プレーンのアップグレードのトラブルシューティングを行う

次の例では、ログを使用してコントロール プレーンのアップグレードが失敗した問題をトラブルシューティングする方法を示します。

  1. Google Cloud コンソールで、[ログ エクスプローラ] ページに移動します。

    [ログ エクスプローラ] に移動

  2. クエリペインで、次のクエリを入力してコントロール プレーンのアップグレード ログをフィルタします。

    resource.type="gke_cluster"
protoPayload.metadata.operationType=~"(UPDATE_CLUSTER|UPGRADE_MASTER)"
resource.labels.cluster_name="CLUSTER_NAME"

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

  3. [クエリを実行] をクリックします。

  4. ログ出力で次の情報を確認します。

  5. アップグレードが開始されたことを確認する: アップグレードを開始した時間帯の UPGRADE_MASTER イベントを探します。これらのイベントが存在することにより、ユーザーまたは GKE のいずれかがアップグレード プロセスをトリガーしたことが確認されます。

    • バージョンを確認する: 次のフィールドをチェックして、以前のバージョンとターゲット バージョンを確認します。

      • protoPayload.metadata.previousMasterVersion: アップグレード前のコントロール プレーンのバージョンを示します。

      • protoPayload.metadata.currentMasterVersion: GKE がコントロール プレーンのアップグレードを試みたバージョンを示します。

        たとえば、バージョン 1.30.1-gke.1234 にアップグレードする予定だったが、誤って 1.30.2-gke.4321（ワークロードと互換性のない可能性がある新しいバージョン）を指定した場合、この 2 つのフィールドを確認すると、この不一致がわかります。また、currentMasterVersion フィールドに古いバージョンが長時間表示されている場合は、アップグレードで新しいバージョンが適用されなかったことを示します。

    • エラーを確認する: UPGRADE_MASTER イベントの繰り返しやその他のエラー メッセージがないか確認します。オペレーション ログが完了または失敗を示すことなく停止した場合、この検出結果により問題を確認できます。

ログから特定のエラーや動作を特定したら、その情報を使用して、このガイドで適切な解決策を見つけることができます。

ノードプールのアップグレードに通常より時間がかかる場合のトラブルシューティングを行う

ノードプールのアップグレードに想定よりも時間がかかる場合は、次の解決策を試してください。

  1. Pod のマニフェストで terminationGracePeriodSeconds の値を確認します。この値は、Kubernetes が Pod の正常なシャットダウンを待機する最大時間を定義します。値が大きい（数分など）と、Kubernetes は各 Pod の期間全体を待機するため、アップグレードの期間が大幅に長くなる可能性があります。この遅延により問題が発生する場合は、値を小さくすることを検討してください。

  2. PodDisruptionBudget オブジェクトを確認します。ノードがドレインされるとき、GKE はノードごとに最大 1 時間待機して、ワークロードを正常に強制排除します。PodDisruptionBudget オブジェクトの制限が厳しすぎると、正常な削除が成功しない可能性があります。このシナリオでは、GKE は 1 時間の猶予期間全体を使用してノードのドレインを試行し、最終的にタイムアウトしてアップグレードを強制的に続行します。この遅延が複数のノードで繰り返されると、クラスタ全体のアップグレードが一般的に遅くなる原因になります。制限付きの PodDisruptionBudget オブジェクトがアップグレードの遅延の原因であるかどうかを確認するには、ログ エクスプローラを使用します。

    1. Google Cloud コンソールで、[ログ エクスプローラ] ページに移動します。

      [ログ エクスプローラ] に移動

    2. クエリペインに次のクエリを入力します。

      resource.type=("gke_cluster" OR "k8s_cluster")
resource.labels.cluster_name="CLUSTER_NAME"
protoPayload.response.message="Cannot evict pod as it would violate the pod's disruption budget."
log_id("cloudaudit.googleapis.com/activity")

    3. [クエリを実行] をクリックします。

    4. ログ出力を確認します。PodDisruptionBudget オブジェクトが問題の原因である場合、出力は次のようになります。

      resourceName: "core/v1/namespaces/istio-system/pods/POD_NAME/eviction"

response: {
  @type: "core.k8s.io/v1.Status"
  apiVersion: "v1"
  code: 429
  details: {
  causes: [
    0: {
    message: "The disruption budget istio-egressgateway needs 1 healthy pods and has 1 currently"
    reason: "DisruptionBudget"
    }
  ]
  }
  kind: "Status"
  message: "Cannot evict pod as it would violate the pod's disruption budget."
  metadata: {
  }
  reason: "TooManyRequests"
  status: "Failure"
}

    5. PodDisruptionBudget オブジェクトが原因であることを確認したら、すべての PodDisruptionBudget オブジェクトを一覧表示し、設定が適切であることを確認します。

      kubectl get pdb --all-namespaces

      出力は次のようになります。

      NAMESPACE        NAME          MIN AVAILABLE   MAX UNAVAILABLE   ALLOWED DISRUPTIONS   AGE
example-app-one  one_pdb       3               0                 1                     12d

      この例では、one_pdb という名前の PodDisruptionBudget には、使用可能な Pod が 3 つ以上必要です。アップグレード中に Pod を強制排除すると、使用可能な Pod が 2 つだけになるため、このアクションは予算に違反し、アップグレードが停止します。

      PodDisruptionBudget オブジェクトが意図したとおりに機能している場合は、操作は必要ありません。機能していない場合は、アップグレード ウィンドウ中に PodDisruptionBudget 設定を緩和することを検討してください。

  3. ノード アフィニティを確認します。制限の厳しいルールでは、ノードが必須ラベルと一致しない場合、Pod が使用可能なノードに再スケジュールされないため、アップグレードが遅くなる可能性があります。この問題は、サージ アップグレード中に特に問題になります。これは、正しいラベルを持つノードに新しい Pod をホストするのに十分なクラスタ容量がない場合、ノード アフィニティによって同時にアップグレードできるノードの数が制限される可能性があるためです。

  4. 短時間のアップグレード方式を使用しているかどうかを確認します。GKE は、Flex Start ノードと、GKE バージョン 1.32.2-gke.1652000 以降を実行しているクラスタでキューに格納されたプロビジョニングのみを使用するノードに、短時間のアップグレード方式を使用します。このアップグレード方式を使用すると、アップグレード オペレーションに最大 7 日かかることがあります。

  5. 実行時間の長い Pod（Autopilot クラスタで使用可能）を使用しているかどうかを確認します。アップグレード中、GKE はプロセスを完了する前に、ノードからすべての Pod をドレインする必要があります。ただし、GKE が開始したアップグレード中は、GKE は最大 7 日間、実行時間の長い Pod を強制排除しません。この保護により、ノードのドレインが防止されます。GKE は、この期間が終了した後にのみ Pod を強制終了します。単一ノードのこの大幅な遅延により、Autopilot クラスタ内の他のノードのアップグレードが遅れる可能性があります。

  6. アタッチされた永続ボリュームは、これらのボリュームのライフサイクルを管理するのに時間がかかるため、アップグレード プロセスに通常よりも時間がかかる可能性があります。

  7. クラスタの自動アップグレードのステータスを確認します。理由が SYSTEM_CONFIG の場合、技術的理由またはビジネス上の理由により、自動アップグレードが一時停止されています。この理由が表示された場合は、必要な場合を除き、手動アップグレードを行わないことをおすすめします。

ノードプール未完了アップグレードのトラブルシューティングを行う

GKE がノードプールのアップグレードを完了できず、ノードプールが部分的にアップグレードされた状態になることがあります。アップグレードが完了しない原因はいくつかあります。

  • アップグレードが手動でキャンセルされた。
  • 新しいノードの登録の失敗、IP アドレスの枯渇、リソース割り当ての不足などの問題が原因で、アップグレードに失敗した。
  • GKE がアップグレードを一時停止した。この一時停止は、既知の問題があるバージョンへのアップグレードを回避するためや、Google が開始した特定のメンテナンス期間中などに発生する可能性があります。
  • 自動アップグレードを使用している場合に、アップグレードが完了する前にメンテナンスの時間枠が終了した。または、アップグレードが完了する前にメンテナンスの除外期間が開始された。詳細については、ノードの更新が完了しないメンテナンスの時間枠をご覧ください。

ノードプールが部分的にアップグレードされると、ノードは異なるバージョンで実行されます。この問題を解決し、ノードプール内のすべてのノードが同じバージョンで実行されていることを確認するには、アップグレードを再開するか、アップグレードをロールバックします。

ただし、サージ アップグレード方式と Blue/Green アップグレード方式は、メンテナンスの時間枠と異なる方法で連携します。

  • サージ アップグレード: アップグレード オペレーションがメンテナンスの時間枠を超えて実行されると、一時停止されます。アップグレードは、次回の定期メンテナンスの時間枠で自動的に再開されます。
  • Blue / Green アップグレード: アップグレード オペレーションは、メンテナンスの時間枠を超えても完了するまで続行されます。Blue / Green アップグレードでは、バッチやノードプールのソーク時間などの機能を使用して、アップグレードのペースをきめ細かく制御できます。また、追加のノードプールにより、ワークロードの運用を継続できます。

予期しない自動アップグレード動作のトラブルシューティングを行う

クラスタの自動アップグレードが想定どおりに実行されないことがあります。以降のセクションでは、次の問題の解決方法について説明します。

ノードの自動アップグレードが有効になっている場合にクラスタのアップグレードが失敗する

ノードの自動アップグレードを無効にしていないにもかかわらずアップグレードが行われない場合は、次の解決策をお試しください。

  1. リリース チャンネルを使用する場合は、ノードの自動アップグレードがブロックされていないことを確認します。リリース チャンネルに登録されているクラスタの場合、maintenancePolicy は自動アップグレードを制御する主な方法です。アップグレードの開始を阻止する可能性や、進行中のアップグレードを中断する可能性があります。メンテナンスの除外が有効になっていると、アップグレードが完全にブロックされることがあります。また、メンテナンスの時間枠のタイミングによって中断が発生することがあります。maintenancePolicy を確認して、次のいずれかの設定が原因かどうかを判断します。

    gcloud container clusters describe CLUSTER_NAME \
    --project PROJECT_ID  \
    --location LOCATION

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

    • CLUSTER_NAME: 記述するノードプールのクラスタの名前。
    • PROJECT_ID: クラスタのプロジェクト ID。
    • LOCATION: クラスタの Compute Engine のリージョンまたはゾーン（us-central1 や us-central1-a など）。

    出力は次のようになります。

    …
maintenancePolicy:
  maintenanceExclusions:
  - exclusionName: critical-event-q4-2025
    startTime: '2025-12-20T00:00:00Z'
    endTime: '2026-01-05T00:00:00Z'
    scope:
      noUpgrades: true # This exclusion blocks all upgrades
  window:
    dailyMaintenanceWindow:
      startTime: 03:00 # Daily window at 03:00 UTC
…

    出力で、maintenancePolicy セクションで次の 2 つの条件を確認します。

    • アップグレードがブロックされているかどうかを確認する: NO_MINOR_OR_NODE_UPGRADES スコープを持つアクティブな maintenanceExclusion を探します。この設定により、通常、GKE が新しいアップグレードを開始することはなくなります。
    • アップグレードが中断されたかどうかを確認する: dailyMaintenanceWindow または maintenanceExclusions のスケジュールを確認します。アップグレードがスケジュールされた時間枠を超えて実行されると、GKE はアップグレードを一時停止し、部分アップグレードになります。部分アップグレードの詳細については、未完了アップグレードのトラブルシューティングをご覧ください。

    これらの問題を解決するには、除外が終了するまで待つか、除外を削除するか、アップグレードの完了に十分な時間を確保できるようにメンテナンスの時間枠を調整します。

  2. リリース チャンネルを使用しない場合は、ノードプールで自動アップグレードが有効になっていることを確認します。

    gcloud container node-pools describe NODE_POOL_NAME \
    --cluster CLUSTER_NAME \
    --location LOCATION

    NODE_POOL_NAME は、説明を取得するノードプールの名前に置き換えます。

    このノードプールでノードプールの自動アップグレードが有効になっている場合、autoUpgrade フィールドの出力は次のようになります。

    management:
  autoUpgrade: true

    autoUpgrade が false に設定されている場合、またはフィールドが存在しない場合は、自動アップグレードを有効にします。

  3. リリースノートにアップグレードが記載されていても、クラスタが配置されているリージョンまたはゾーンにアップグレードがロールアウトされていない可能性があります。GKE アップグレードは、数日（通常は 4 日以上）にわたって段階的にロールアウトされます。アップグレードがリージョンまたはゾーンに到達すると、承認されたメンテナンスの時間枠内でのみアップグレードが開始されます。たとえば、ロールアウトはロールアウトの初日にクラスタのゾーンに到達する可能性がありますが、クラスタの次のメンテナンスの時間枠は 7 日目までありません。このシナリオでは、GKE は 7 日目までクラスタをアップグレードしません。詳細については、GKE リリース スケジュールをご覧ください。

自動アップグレードが有効になっていない場合にクラスタが自動的にアップグレードされる

GKE 環境の信頼性、可用性、セキュリティ、パフォーマンスを維持するために、自動アップグレードを使用していない場合でも、GKE がクラスタを自動的にアップグレードすることがあります。

GKE は、次のような重要な理由で必要なアップグレードを実行するために、メンテナンスの時間枠、除外、無効になっているノードプールの自動アップグレードをバイパスすることがあります。

  • コントロール プレーンで、サポート終了日を迎えた GKE バージョンが実行されているクラスタ。クラスタのサポート終了日が近づいていることを確認するには、リリース チャンネルのおおよそのスケジュールをご覧ください。
  • サポート終了日を迎えた GKE バージョンを実行しているクラスタ内のノード。
  • 実行状態にあるが、長期間アクティビティがないクラスタ。たとえば、GKE は、API 呼び出しがなく、ネットワーク トラフィックがなく、サブネットがアクティブに使用されていないクラスタを放棄されたクラスタと見なすことがあります。
  • 動作状態を繰り返し循環する永続的な不安定性を示すクラスタ。たとえば、実行から劣化、修復、一時停止、そして実行に戻るというように状態がループしているが、解決されていない場合などです。

予期しない自動アップグレードが発生し、このアップグレードがクラスタに与える影響について懸念がある場合は、Cloud カスタマーケアにお問い合わせください。

アップグレードの失敗に関するトラブルシューティングを行う

アップグレードが失敗すると、GKE はエラー メッセージを生成します。以降のセクションでは、次のエラーの原因と解決策について説明します。

エラー: kube-apiserver が異常です

クラスタの GKE バージョンのコントロール プレーンの手動アップグレードを開始すると、次のエラー メッセージが表示されることがあります。

FAILED: All cluster resources were brought up, but: component
"KubeApiserverReady" from endpoint "readyz of kube apiserver is not successful"
is unhealthy.

このメッセージは、gcloud CLI およびリソースタイプ gke_cluster と gke_nodepool のログエントリに表示されます。

この問題は、一部のユーザーがデプロイしたアドミッション Webhook が、システム コンポーネントをブロックし、正常に機能するために必要な制限の少ない RBAC ロールの作成を妨げる場合に発生します。

コントロール プレーンのアップグレード中に、GKE は Kubernetes API サーバー（kube-apiserver）コンポーネントを再作成します。Webhook が API サーバー コンポーネントの RBAC ロールをブロックしている場合、API サーバーは起動せず、クラスタのアップグレードは完了しません。Webhook が正しく機能していても、新しく作成されたコントロール プレーンから Webhook に到達できないため、クラスタのアップグレードが失敗する可能性があります。

Kubernetes は、最新のマイナー バージョンのデフォルト ポリシーを使用して、デフォルトのシステム RBAC ロールを自動調整します。システムロールのデフォルトのポリシーは、新しい Kubernetes バージョンで変更される可能性があります。

この調整を行うために、GKE はクラスタ内の ClusterRoles と ClusterRoleBinding を作成または更新します。デフォルトの RBAC ポリシーが使用する権限のスコープにより、作成リクエストまたは更新リクエストをインターセプトして拒否する Webhook がある場合、API サーバーは新しいマイナー バージョンで機能しません。

失敗した Webhook を特定するには、次の情報を使用して RBAC 呼び出しの GKE 監査ログを確認します。

protoPayload.resourceName="RBAC_RULE"
protoPayload.authenticationInfo.principalEmail="system:apiserver"

この出力で、RBAC_RULE は RBAC ロールの完全な名前です（rbac.authorization.k8s.io/v1/clusterroles/system:controller:horizontal-pod-autoscaler など）。

失敗した Webhook の名前が次の形式でログに表示されます。

admission webhook WEBHOOK_NAME denied the request

この問題を解決するには、次のことを試してください。

  1. ClusterRole を確認して、過度に制限されていないことを確認する。ポリシーで、デフォルトの system: 接頭辞を持つ ClusterRole を作成または更新する GKE のリクエストがブロックされないようにする必要があります。
  2. システム RBAC ロールの作成と更新のリクエストをインターセプトしないように Webhook を調整する。
  3. Webhook を無効にする。

エラー: DeployPatch が失敗しました

クラスタのアップグレード オペレーションが次のエラーで失敗することがあります。

DeployPatch failed

このエラーは、Kubernetes コントロール プレーンが 20 分以上正常な状態を維持できない場合に発生することがあります。

コントロール プレーンはオペレーションが成功するまで再試行するため、このエラーは一時的なものであることがよくあります。このエラーでアップグレードが引き続き失敗する場合は、Cloud カスタマーケアにお問い合わせください。

アップグレード完了後の問題のトラブルシューティングを行う

アップグレードの完了後に予期しない動作が発生した場合は、以降のセクションで、次の一般的な問題のトラブルシューティング ガイダンスを確認してください。

互換性を破る変更による予期しない動作

アップグレードが正常に完了したにもかかわらず、アップグレード後に予期しない動作が発生した場合は、GKE リリースノートで、クラスタがアップグレードされたバージョンに関連するバグと重大な変更点を確認してください。

Standard クラスタのアップグレード後に強制排除されるワークロード

次のすべての条件に該当する場合、クラスタ アップグレード後にワークロードが強制排除のリスクにさらされる可能性があります。

  • クラスタのコントロール プレーンが新しい GKE バージョンを実行しており、より多くのスペースがシステム ワークロードに必要になっている。
  • 既存のノードに、新しいシステム ワークロードと既存のワークロードを実行するための十分なリソースがない。
  • クラスタ オートスケーラーがクラスタで無効になっている。

この問題を解決するには、次のことを試してください。

  1. 既存のノードプールの自動スケーリングを有効にする。
  2. ノード自動プロビジョニングを有効にする。
  3. 新しいノードプールを作成する。
  4. 既存のノードプールをスケールアップする。

ノード割り当て可能を構成した後、Pod が Pending 状態のままになる

ノード割り当て可能を構成している場合、ノードのバージョンをアップグレードすると、Running 状態の Pod が Pending 状態のままになることがあります。この変更は通常、アップグレードされたノードがわずかに異なるシステム リソースを消費するため、または再スケジュールされた Pod が新しいノードまたは変更されたノードの Node Allocatable 上限内に収まる必要があるため、より厳しい条件で発生します。

アップグレード後に Pod のステータスが Pending になった場合は、次の解決策を試してください。

  1. Pod の CPU リクエストとメモリ リクエストがピーク時の使用量を超えていないことを確認します。オーバーヘッド用に CPU とメモリを予約している GKE では、Pod はこのリソースをリクエストできません。実際の使用量よりも多くの CPU またはメモリをリクエストする Pod では、他の Pod がこのリソースをリクエストすることができなくなり、クラスタが十分に活用されないことがあります。詳細については、Kubernetes ドキュメントのリソース リクエストを含む Pod のスケジュール設定をご覧ください。
  2. クラスタのサイズを大きくすることを検討してください。
  3. アップグレードがこの問題の原因かどうかを確認するには、ノードプールをダウングレードしてアップグレードを元に戻します。
  4. Kubernetes スケジューラー指標を Cloud Monitoring に送信し、スケジューラー指標を表示するようにクラスタを構成する。 これらの指標をモニタリングすることで、Pod の実行に十分なリソースがあるかどうかを判断できます。

バージョンと互換性に関する問題のトラブルシューティングを行う

安定性とパフォーマンスを確保するには、クラスタのすべてのコンポーネントでサポートされている互換性のあるバージョンを維持することが不可欠です。以降のセクションでは、アップグレード プロセスに影響する可能性のあるバージョニングと互換性の問題を特定して解決する方法について説明します。

コントロール プレーンとノードのバージョンの非互換性を確認する

コントロール プレーンとノード間のバージョン スキューにより、クラスタが不安定になる可能性があります。GKE バージョン スキュー ポリシーでは、コントロール プレーンは 2 つ前までのマイナー バージョンのノードとのみ互換性があると規定されています。たとえば、1.19 コントロール プレーンは 1.19、1.18、1.17 のノードで動作します。

ノードがこのサポート対象期間外にある場合、重大な互換性の問題が発生する可能性があります。これらの問題は API 関連であることが多く、たとえば、古いノードのワークロードが、新しいコントロール プレーンで非推奨または削除された API バージョンを使用している可能性があります。この非互換性により、互換性のないワークロードが通信を中断すると、ノードがクラスタに登録できなくなるなど、より深刻な障害が発生する可能性もあります。

GKE チームはユーザーに代わって定期的にクラスタ コントロール プレーンのアップグレードを行います。コントロール プレーンは、新しい安定版の Kubernetes にアップグレードされます。ノードがアップグレードされたコントロール プレーンと互換性を維持するには、ノードも最新の状態に保つ必要があります。デフォルトでは、クラスタのノードで自動アップグレードが有効になっているため、GKE がこのアップグレードを処理します。自動アップグレードを無効にしないことをおすすめします。クラスタのノードの自動アップグレードが無効になっていて、手動でアップグレードしない場合、コントロール プレーンは最終的にノードと互換性がなくなります。

コントロール プレーンとノードのバージョンに互換性がないかどうかを確認するには、クラスタのコントロール プレーンとノードプールで実行されている Kubernetes のバージョンを確認します。

gcloud container clusters describe CLUSTER_NAME \
    --project PROJECT_ID  \
    --location LOCATION

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

  • CLUSTER_NAME: 記述するノードプールのクラスタの名前。
  • PROJECT_ID: クラスタのプロジェクト ID。
  • LOCATION: クラスタの Compute Engine のリージョンまたはゾーン（us-central1 や us-central1-a など）。

出力は次のようになります。

…
currentMasterVersion: 1.32.3-gke.1785003
…
currentNodeVersion: 1.26.15-gke.1090000
…

この例では、コントロール プレーンのバージョンとノードプールのバージョンに互換性がありません。

この問題を解決するには、ノードプールのバージョンをコントロール プレーンと互換性のあるバージョンに手動でアップグレードします。

アップグレード プロセスにより、影響を受けるノードで実行されているワークロードが中断される懸念がある場合は、次の手順でワークロードを新しいノードプールに移行します。

  1. 互換性のあるバージョンで新しいノードプールを作成します。
  2. 既存のノードプールのノードを閉鎖します。
  3. 省略可: 既存のノードプールで実行されているワークロードを更新して、ラベル cloud.google.com/gke-nodepool:NEW_NODE_POOL_NAME の nodeSelector を追加します。NEW_NODE_POOL_NAME は、新しいノードプールの名前に置き換えます。この操作により、GKE はこれらのワークロードを新しいノードプールのノードに配置します。
  4. 既存のノードプールをドレインします。
  5. 新しいノードプールでワークロードが正常に実行されていることを確認する。 問題がなければ、古いノードプールを削除できます。ワークロードの中断が発生した場合は、既存のノードプール内のノードの閉鎖を解除し、新しいノードをドレインして、既存のノードでワークロードを再スケジュールします。

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

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

この問題は、手動アップグレードを使用している場合に、クラスタまたはノードがサポートされているバージョンを実行するようにアップグレードされていないと発生する可能性があります。リリースノートで、使用しているバージョンが利用可能であり、サポートされていることを確認してください。

次のステップ

  • このドキュメントで問題を解決できない場合は、サポートを受けるで、次のトピックに関するアドバイスなど、詳細なヘルプをご覧ください。