Kubernetesトラブルシューティング完全ガイド:コマンド・エラー・解決策

要約:
Kubernetesのトラブルシューティングはボトムアップで進めます。Podのステータスを確認し、イベントを調べ、ログを確認し、必要に応じてインタラクティブにデバッグします。ほとんどの問題は、繰り返し発生する少数のエラー(ImagePullBackOff、CrashLoopBackOff、Pending、OOMKilled)に集約され、いずれも kubectl describe/logs で原因を追跡できます。適切なリソースのrequests/limitsの設定、プローブのチューニング、継続的なモニタリング、そして長期的なworkloadsのライトサイジングにより、問題の再発を防止できます。

よくあるKubernetesエラーコードと解決策

ImagePullBackOff

問題: ImagePullBackOff は、Podの起動に必要なコンテナイメージをKubernetesがプルできない場合に発生します。最初のイメージプルが失敗すると、Kubernetesは徐々に間隔を延ばしながら操作を再試行します。イメージが利用可能になるまで、Podは実行されない状態のままとなります。

診断: イメージプルの失敗は、無効なイメージ名、誤ったタグ、レジストリ認証情報の欠落、認証トークンの期限切れ、レジストリの障害、ネットワーク接続の問題が一般的な原因です。まず確認すべきは、kubectl describe の出力にあるEventsセクションです。

kubectl describe pod <pod-name> を実行し、ErrImagePull、pull access denied、unauthorized、manifest unknown といったメッセージを探します。これらのメッセージから、失敗の原因が認証、イメージの可用性、接続性のいずれに関連するかを判断できます。

解決ワークフロー:

1. kubectl describe pod <pod-name> を実行し、Eventsセクションを確認します。
2. イメージ名とタグが正しく、レジストリに存在することを確認します。
3. クラスタのノードからコンテナレジストリに到達できることを確認します。
4. Podまたはサービスアカウントに設定されたイメージプルシークレットを検証します。
5. レジストリの認証情報、権限、トークンの有効期限を確認します。
6. ワーカーノードからのDNS解決とアウトバウンドのネットワーク接続を確認します。
7. レジストリへのアクセスを妨げる可能性のあるプロキシ、ファイアウォール、ネットワークポリシーの設定を確認します。

例

kubectl describe pod my-pod
kubectl get secrets
kubectl describe secret registry-secret

CrashLoopBackOff

問題: CrashLoopBackOff は、コンテナが起動と終了を繰り返し、Kubernetesによって再起動され続けている状態を示します。連続して数回失敗すると、Kubernetesは絶え間ない再起動サイクルを避けるため、再起動試行の間隔を徐々に延ばします。

診断: この状態は通常、アプリケーションの起動失敗、無効な設定値、環境変数の欠落、依存関係の初期化失敗、データベース接続の問題、誤ったコンテナコマンドが原因です。

根本原因を特定する最速の方法は、多くの場合コンテナのログです。kubectl logs <pod-name> でログを確認します。コンテナの再起動が速すぎる場合は、--previous フラグを使用して、直前に失敗したインスタンスのログを取得します。kubectl describe の出力からも、終了理由、終了コード、再起動回数、プローブの失敗を確認できます。

解決ワークフロー:

1. kubectl logs <pod-name> でアプリケーションログを確認します。
2. 必要に応じて、--previous で前のコンテナインスタンスのログを取得します。
3. kubectl describe pod <pod-name> でPodのイベントと終了の詳細を検査します。
4. 環境変数、設定ファイル、シークレット、起動コマンドを検証します。
5. データベース接続、外部依存関係、サービスエンドポイントを確認します。
6. CPUとメモリの制限を確認し、リソース枯渇の兆候がないか調べます。
7. Readiness、Startup、Livenessの各プローブ設定を検証し、必要に応じてタイミングのしきい値を調整します。

例

kubectl logs my-pod
kubectl logs my-pod --previous
kubectl describe pod my-pod

Pending

問題: Podが Pending 状態になるのは、KubernetesがPodの定義を受け入れたものの、適切なノードに割り当てられない場合です。すべてのスケジューリング要件が満たされるまで、workloadsはスケジュールされず、起動しません。

診断: Pending状態のPodは、クラスタリソースの不足、制限の厳しいスケジューリングルール、ストレージのプロビジョニング失敗、ノード配置の制約が主な原因です。よくあるスケジューリングメッセージには、CPU不足、メモリ不足、ノードセレクターの不一致、Taintの競合、バインドされていないPersistentVolumeClaimなどがあります。

kubectl describe pod <pod-name> で表示されるスケジューリングイベントには、通常、スケジューラーがworkloadsを配置できなかった正確な理由が示されます。

解決ワークフロー:

1. kubectl describe pod <pod-name> を実行し、スケジューラーのイベントを確認します。
2. kubectl get nodes でノードの可用性を確認します。
3. クラスタに十分なCPUとメモリのリソースがあることを確認します。
4. ノードセレクター、ノードアフィニティのルール、Taint、Tolerationを確認します。
5. 必要なノードラベルが存在することを検証します。
6. PersistentVolumeClaims(PVC)とストレージのプロビジョニング状態を確認します。
7. オートスケーリングが有効な場合は、クラスタオートスケーラーが正しく機能していることを確認します。

例

kubectl describe pod my-pod
kubectl get nodes
kubectl get pvc

OOMKilled

問題: OOMKilled は、コンテナが設定されたメモリ制限を超え、LinuxのOOM(out-of-memory)キラーによって強制終了された場合に発生します。Kubernetesはメモリ制限を厳格に適用するため、制限を超えるとコンテナは即座に停止します。

診断: メモリ枯渇は、メモリリーク、過剰なキャッシュ、非効率なアプリケーションの動作、トラフィックの急増、大規模なデータセット、あるいはworkloadsに対して低すぎるメモリ制限の設定が原因となり得ます。

kubectl describe の出力には、通常、終了理由として OOMKilled が表示されます。Prometheus、Grafana、Metrics Serverなどのリソースモニタリングツールを使えば、workloadsが持続的なメモリ圧迫を受けているのか、突発的な使用量の急増が発生しているのかを判断できます。

解決ワークフロー:

1. kubectl describe pod <pod-name> で終了理由を確認します。
2. 障害発生前のメモリ消費メトリクスを確認します。
3. メモリの急増、リーク、持続的な高使用率を特定します。
4. 実際のメモリ使用量を、設定されたrequestsとlimitsと比較します。
5. メモリ制限が明らかに小さすぎる場合は引き上げます。
6. キャッシュ、並行処理、メモリリークなど、アプリケーションレベルの原因を調査します。
7. アプリケーションのメモリ使用を最適化し、観測されたworkloadsの挙動に基づいてリソース設定を調整します。

例

kubectl describe pod my-pod
kubectl top pod my-pod
kubectl top nodes

Kubernetesの問題を未然に防ぐ5つの方法

優れたKubernetesチームは、よくある障害を最小限に抑えるようクラスタを設計しています。これにより回復力が高まり、問題が発生した際のトラブルシューティングも容易になります。

1. リソースのrequestsとlimitsを設定する

リソースのrequestsとlimitsは、Kubernetesがクラスタ全体でCPUとメモリを予測可能に割り当てるのに役立ちます。requestsはスケジューリングに必要な最小リソースを、limitsはコンテナが消費できる最大リソースを定義します。適切な設定により、workloadsが共有リソースを激しく奪い合うことを防げます。

requestsがないと、スケジューラーは正確な配置判断ができず、ノードの過負荷やworkloadsの不安定化を招く可能性があります。limitsがないと、1つのコンテナが過剰なメモリやCPUを消費し、同じノード上で稼働する他のアプリケーションに影響を及ぼすおそれがあります。

慎重に設定されたlimitsは、OOMKilled イベント、CPUスロットリング、ノードのリソース枯渇のリスクを軽減します。ただし、limitsを低く設定しすぎると、ピーク負荷時にアプリケーションが制限され、かえって不安定になる可能性もあります。

Namespaceレベルで LimitRange と ResourceQuota のポリシーを使用すると、チームや環境をまたいで一貫したリソース管理を徹底できます。こうした制御により、設定ミスのあるworkloadsがクラスタの安定性に影響を与える可能性を低減できます。

2. ReadinessプローブとLivenessプローブを慎重に使う

ReadinessプローブとLivenessプローブは、コンテナが健全でトラフィックを受け入れられる状態かをKubernetesが判断するのに役立ちます。適切なプローブ設定は、不健全なPodがリクエストを処理するのを防ぎ、失敗したコンテナを自動的に再起動することで、アプリケーションの信頼性を向上させます。

Readinessプローブは、Podをサービスのエンドポイントリストに追加するかどうかを制御します。Readinessプローブが失敗すると、Podが回復するまでトラフィックのルーティングが停止します。これにより、初期化が不完全な、あるいは劣化したアプリケーションにユーザーが到達するのを防げます。

Livenessプローブは、アプリケーションのデッドロックや応答しないプロセスを検出します。Livenessプローブが繰り返し失敗すると、Kubernetesはコンテナを自動的に再起動します。この仕組みは自己修復性を高めますが、設定を誤ると不安定性を生む原因にもなります。

プローブのタイミングを厳しくしすぎることは、不要な再起動や CrashLoopBackOff 状態のよくある原因です。起動に時間がかかるアプリケーションは、初期化が完了する前にヘルスチェックに失敗することがあります。起動が遅いworkloadsには、Startupプローブが有効なケースが多くあります。

3. イベント・ログ・メトリクスを監視する

継続的なモニタリングは、Kubernetesの問題が障害に発展する前に検出するために不可欠です。ログ、メトリクス、クラスタイベントは、workloadsの挙動、リソース使用状況、インフラの健全性、運用上の障害を可視化します。

PrometheusやGrafanaといったメトリクスプラットフォームは、CPU使用率、メモリ消費、Podの再起動、ネットワーク遅延、ストレージ性能の追跡に役立ちます。長期的なトレンドを監視することで、サービスが不安定になる前に異常な挙動を特定できます。

集中型ロギングシステムは、コンテナログ、ノードログ、システムイベントを検索可能なプラットフォームに集約し、トラブルシューティングを効率化します。Kubernetesのログ収集と分析には、Elasticsearch、Fluent Bit、Loki、Splunkなどのツールが一般的に使用されます。

Kubernetesのイベントは、スケジューリングの失敗、イメージのプルエラー、Podの退避、設定の問題を記録することで、運用上の追加コンテキストを提供します。イベントは一時的なものであるため、外部に収集・保存しておくことで、長期的なトラブルシューティング能力が向上します。

4. Namespaceとラベルを一貫して使う

Namespaceは、Kubernetesクラスタ内でworkloadsを整理し、リソースを分離するのに役立ちます。Namespaceを一貫して活用することで、運用の明確さ、アクセス制御、リソース管理、トラブルシューティングの効率が向上します。

開発、ステージング、本番といった環境を別々のNamespaceに分離すると、workloads間の意図しない干渉のリスクが低減します。Namespaceレベルのポリシーで、セキュリティ境界やリソースクォータを強制することもできます。

ラベルは、workloadsの選択、グルーピング、モニタリング、自動化に使用されるメタデータを提供します。Kubernetesのサービス、Deployment、ネットワークポリシー、監視システムはいずれも、workloadsの識別をラベルに大きく依存しています。

一貫性のない、または設計の甘いラベル体系は、サービスルーティングの失敗、デプロイの混乱、運用の複雑化を招きがちです。標準化されたラベルにより、大規模クラスタ全体でのworkloadsの検索、監視、管理が容易になります。

5. 実際の使用状況に基づきworkloadsを継続的にライトサイジングする

workloadsのリソース要件は、アプリケーションの進化、トラフィックパターンの変化、インフラ使用量の増加に伴い、時間とともに変化します。workloadsを継続的にライトサイジングすることで、パフォーマンスを維持しながらクラスタリソースの無駄を削減できます。

過剰にプロビジョニングされたworkloadsはCPUとメモリを浪費し、インフラコストの増加とクラスタ効率の低下を招きます。逆にプロビジョニングが不足すると、不安定性、スケジューリングの失敗、CPUスロットリング、メモリ起因のクラッシュを引き起こします。

workloadsの実際の挙動を監視することで、リソースのrequestsとlimitsを最適化するためのデータが得られます。エンジニアは、短期的な急増や初期デプロイ時の見積もりだけに頼らず、長期的な使用パターンを確認すべきです。

Vertical Pod Autoscaler(VPA)のようなツールは、観測された消費量に基づいてリソース設定を推奨または自動調整できます。Horizontal Pod Autoscaler(HPA)は、負荷の変化に応じてレプリカ数をスケーリングすることで、このアプローチを補完します。

PerfectScaleがKubernetesの問題の予防と解決を支援

Kubernetesのトラブルシューティングは、その多くが事後対応型です。Podがクラッシュするのを待ってから、イベント、ログ、メトリクスを掘り下げて原因を探す——PerfectScaleはこのモデルを転換し、workloadsを自律的にライトサイジングし、ダウンタイムを防止し、リソース使用を最適化して99.99%の可用性を維持します。OOMKilled、CrashLoopBackOff、スロットリングイベントを手作業で追いかける代わりに、DevOps、SRE、プラットフォームエンジニアリングの各チームは、K8sスタックのあらゆるレイヤーにわたって継続的かつデータドリブンな修復を実現できます。

PerfectScaleの主な機能:

• 問題の自動修復: 回復力のリスクを即座に特定・修正して稼働時間を最大化し、遅延を排除します。OOM、CPUスロットリング、Podの退避といった問題を、障害に連鎖する前に解消します。
• 設定エラーの防止: CPUのrequests未設定、メモリのrequests未設定、メモリlimitsの未設定など、よくある障害の背後にある設定ミスを検出し、workloadsが確実に起動・稼働できるようにします。
• プロビジョニング不足の検出: プロビジョニングが不足しているCPUとメモリ(requestsとlimitsの両方)や、メモリリークの疑いを明らかにします。これらは、ノードが健全に見えてもPodが再起動ループから抜け出せない根本原因です。
• インフラの強化: ノード全体を横断的に可視化してノードの過剰コミットを防止し、ノードアフィニティやTaintを検証し、workloadsに最適なノードタイプを選択できます。
• 影響度に基づく優先順位付け: アラートをSLA・SLOに合わせ、Slack、MS Teams、Datadogで即時通知を受け取り、ワンクリックで問題をチケットにエスカレーションできます。
• オートスケーリングの最適化: 水平・垂直オートスケーリングの設定を微調整してスケーリングトリガーを正確に発火させ、不安定性の原因となる「HPAが最大レプリカ数に到達」やリソース枯渇のシナリオを防止します。

FAQ

Podに問題があるとき、最初に実行すべきコマンドは何ですか? kubectl get pods で失敗しているPodを特定し、次に kubectl describe pod <pod-name> で状態と最近のイベントの詳細を確認します。

CrashLoopBackOffの原因は何ですか? コンテナが起動、終了、再起動を繰り返す状態です。通常は起動失敗、不正な設定、環境変数の欠落、データベースや依存関係の接続エラーが原因です。まず kubectl logs <pod-name> --previous を確認してください。

ImagePullBackOffの原因は何ですか? Kubernetesがコンテナイメージをプルできない状態です。多くの場合、無効なイメージ名やタグ、レジストリ認証情報の欠落や期限切れ、レジストリへのネットワーク到達の問題が原因です。

PodがPendingのまま動かないのはなぜですか? スケジューラーがPodを配置できない状態です。一般的には、クラスタのCPU/メモリ不足、ノードセレクターやTaintの不一致、バインドされていないPersistentVolumeClaimが原因です。kubectl describe pod <pod-name> でスケジューリングの正確な理由を確認できます。

OOMKilledとはどういう意味ですか? コンテナがメモリ制限を超え、LinuxのOOMキラーによって強制終了されたことを意味します。設定されたrequests/limitsに対するメモリ使用量を確認し、リークや過小な制限がないか調べてください。

ネットワークやDNSの問題はどうデバッグすればよいですか? kubectl get endpoints でPodがサービスに紐づいていることを確認し、kubectl exec -it <pod-name> -- nslookup <service-name> でPod内部からDNS解決をテストします。

事後対応ではなく、こうした問題を予防するにはどうすればよいですか? 適切なリソースrequests/limitsを設定し、Readiness/Livenessプローブを慎重に構成し、ログ・イベント・メトリクスを継続的に監視し、Namespaceとラベルを一貫して使用し、長期的にworkloadsをライトサイジングします(VPA/HPAや、PerfectScaleのようなツールの活用など)。

Kubernetesの障害対応に追われる日々から抜け出しませんか? PerfectScaleのKubernetesパフォーマンス・レジリエンスプラットフォームをご覧いただき、自律的な最適化がクラスタの安定性、回復力、コスト効率をどのように維持するかをご確認ください。