GKE のトラブルシューティング

このドキュメントには、Google Kubernetes Engine（GKE）の使用時に発生する可能性のある一般的な問題のトラブルシューティング ドキュメントの一覧を掲載します。ImagePullBackOff や CrashLoopBackOff などのワークロード エラーの診断、クラスタの自動スケーリング動作のデバッグ、PersistentVolume の問題の解決、ノード登録の問題のトラブルシューティングなどを行う際に、ここに記載されているドキュメントが役立ちます。

GKE のトラブルシューティングが初めての場合は、トラブルシューティングの概要から確認してください。

発生した問題を診断して解決するには、次のセクションのドキュメントをご覧ください。

GKE ネットワーキングのトラブルシューティングを行うには、GKE ネットワーキングのドキュメントで GKE ネットワーキングのトラブルシューティングをご覧ください。

このドキュメントは、GKE 構成のトラブルシューティングを行う管理者とアーキテクト、セキュリティ スペシャリスト、ネットワーク スペシャリスト、ストレージ スペシャリストを対象としています。GKE ロールの詳細については、GKE の一般的なユーザーロールとタスクをご確認ください。

トラブルシューティングの概要

トピック 説明
GKE のトラブルシューティングの概要 GKE のトラブルシューティングを開始できるよう、全体的なプロセスと基本的なコンセプトについて説明します。
サービスの健全性とインシデントを確認する GKE と関連する Google Cloud サービスの健全性を確認して、プラットフォームの問題を除外する方法について説明します。
Google Cloud コンソールでクラスタとワークロードの健全性を確認する Google Cloud コンソールを使用して GKE の問題を調査、解決する方法について説明します。
kubectl を使用してクラスタの状態を調査する クラスタとワークロードの問題を診断するための一般的な kubectl コマンドと手法について説明します。
Cloud Logging で履歴分析を行う Cloud Logging を効果的に使用して、GKE の問題の根本原因を見つける方法について説明します。
Cloud Monitoring を使用して事前対応型のモニタリングを行う Cloud Monitoring のダッシュボードと指標を使用して、GKE の問題を特定、診断、解決します。
Gemini Cloud Assist で診断を迅速化する GKE の問題の診断と解決に Gemini をどのように役立てるかを確認します。
すべてをまとめる: トラブルシューティングのシナリオの例 GKE でよくあるシナリオにおけるトラブルシューティングの手順の例を確認します。

クラスタの設定

トピック 説明
クラスタの作成 クラスタの作成に関する問題を解決します。
Autopilot クラスタ クラスタの作成、Namespace の削除、スケーリング、ワークロードの問題など、GKE Autopilot クラスタを診断してトラブルシューティングを行います。
Kubectl コマンドライン ツール 認証や認可に関する問題など、GKE の kubectl コマンドライン ツールのトラブルシューティングを行います。このページでは、Konnectivity プロキシのトラブルシューティングを行う方法についても説明します。このプロキシが原因で kubectl logs、attach、exec、port-forward コマンドが応答しなくなっているかどうかを確認できます。
Standard ノードプール ノードプールの作成、ベスト エフォート型のプロビジョニング、インスタンス メタデータの破損、新しいノードプールへのワークロードの移行に関する問題など、GKE Standard ノードプールのトラブルシューティングを行います。
ノード NotReady のステータス リソース不足、ネットワークの問題、コンポーネントの障害といった一般的な原因のトラブルシューティングを行い、GKE でノードの NotReady ステータスを診断して解決する方法を確認します。
ノードの登録 GKE Standard クラスタにノードを追加する際に発生する問題（ノード登録の失敗、ノード登録に成功するための前提条件を満たしていないなど）のトラブルシューティングを行います。
コンテナ ランタイム containerd と dockershim や、限定公開レジストリに関する問題など、GKE のコンテナ ランタイムのトラブルシューティングを行います。

自動スケーリング

トピック 説明
クラスタ オートスケーラーがスケールダウンしない クラスタが使用率の低いノードを削除しない一般的な理由を診断して解決します。制限の厳しい PodDisruptionBudgets、ローカル ストレージを使用する Pod、ノードの削除を妨げる特定のアノテーション（"cluster-autoscaler.kubernetes.io/safe-to-evict": "false" など）といった問題を確認する方法について説明します。
クラスタ オートスケーラーがスケールアップしない クラスタ オートスケーラーが需要を満たすために新しいノードを追加しない理由を確認します。スケジュール不可能な Pod の有無を確認し、クラスタまたはノードプールのサイズ上限に達していないか確認し、リソース割り当てまたはリージョン VM の可用性に関する潜在的な問題を特定します。
水平 Pod 自動スケーリング HorizontalPodAutoscaler がアプリケーションの Pod レプリカをスケーリングしない問題のトラブルシューティングを行います。HorizontalPodAutoscaler オブジェクトの構成ミスや指標パイプラインの問題など、一般的な問題を解決します。

ストレージ

トピック 説明
ストレージ リージョン永続ディスク、ディスク パフォーマンス、ボリューム拡張に関する問題など、ストレージのトラブルシューティングを行います。

クラスタ セキュリティ

トピック 説明
認証 RBAC、Workload Identity Federation for GKE、GKE メタデータ サーバーに関する問題など、GKE での認証のトラブルシューティングを行います。
サービス アカウント デフォルトのサービス アカウントの復元や Compute Engine のデフォルトのサービス アカウントの有効化など、サービス アカウントのトラブルシューティングを行います。
アプリケーション レイヤでの Secret アプリケーション レイヤでの Secret の暗号化の構成時に発生する可能性のある問題（更新の失敗、Cloud KMS 鍵を使用できないエラー、Cloud KMS 鍵バージョンが破棄されたエラーなど）のトラブルシューティングを行います。

クラスタのルート認証局の有効期限が近づいている

トピック 説明
ルート認証局（CA）の有効期限が近づいている クラスタのルート認証局（CA）の有効期限が近づいている場合は、認証情報のローテーションを行う方法を確認し、通常のクラスタ オペレーションが中断されないようにします。

ワークロード

トピック 説明
デプロイされたワークロード GKE クラスタで実行されているワークロードのエラー（PodUnschedulable など）をトラブルシューティングします。MatchNodeSelector や Does not have minimum availability などのエラーに関する参考情報については、PodUnschedulable セクションをご覧ください。
イメージの pull イメージの pull に関するトラブルシューティングを行います。ImagePullBackOff や ErrImagePull などのステータスの原因と、認証やネットワーク接続といった一般的な問題を解決してこれらのステータスを解決する方法を確認します。
CrashLoopBackOff イベント GKE で CrashLoopBackOff イベントのトラブルシューティングを行います。リソースの枯渇、アプリの構成ミス、liveness プローブの失敗などの問題を診断します。
OOM イベント Kubernetes のメモリ不足（OOM）イベントのトラブルシューティングを行います。原因を特定し、イベントタイプを区別して、コンテナレベルとノードレベルの両方の OOM 終了に効果的な解決策を適用します。
Arm ワークロード Arm ワークロードに関する問題（Arm ノードの Pod のクラッシュなど）のトラブルシューティングを行います。
TPU 割り当て、ノード自動プロビジョニング、ワークロードの構成、スケジューリングに関する問題など、TPU のトラブルシューティングを行います。
GPU GPU ドライバのインストール、デバイス プラグインのエラー、コンテナ イメージに関する問題など、GPU のトラブルシューティングを行います。

クラスタ管理

トピック 説明
クラスタのアップグレード 長時間または完了しないアップグレード、予期しない自動アップグレード、失敗、アップグレード後の問題など、GKE クラスタとノードのアップグレードに関する問題のトラブルシューティングと解決を行います。
Webhook アドミッション Webhook を使用する際のトラブルシューティング方法やクラスタ コントロール プレーンの安定性を確保する方法について説明します。
Namespace が Terminating 状態のままになる 削除をブロックしている異常なコンポーネントを特定して削除することで、Namespace が Terminating 状態のままになる問題のトラブルシューティングを行います。
同時実行オペレーション これらのエラーを特定し、オペレーションの完了を待つことで解決する方法を確認して、同時実行オペレーションのトラブルシューティングを行います。

モニタリング

トピック 説明
システム指標 Cloud Monitoring にシステム指標が表示されない問題のトラブルシューティングを行います。
モニタリング ダッシュボード モニタリングの有効化、Kubernetes リソースの不足、権限に関する問題など、モニタリング ダッシュボードのトラブルシューティングを行います。
ログが見つからない場合のトラブルシューティング GKE ログが見つからない場合のトラブルシューティング方法です。API のステータス、クラスタ設定、権限、割り当て、フィルタ、アプリケーションの動作を確認する方法について説明します。

4xx エラー

トピック 説明
4xx エラー GKE の使用時に発生する可能性のある 400、401、403、404 エラーのトラブルシューティングを行います。このページには、アカウントに対する編集権限がないエラーのトラブルシューティング方法も記載されています。

既知の問題

トピック 説明
既知の問題 GKE の使用に影響する可能性がある既知の問題を特定して解決します。

次のステップ

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