はじめに
Kubernetes運用でトラブルが発生した時、「どのコマンドを使えばいいんだっけ？」と慌ててしまうことがあります。特に緊急時は冷静に判断するのが難しいので、よくあるトラブルパターンとその対応コマンドを整理してみました。
基本情報確認コマンド
クラスター全体の状態確認
# クラスター情報
kubectl cluster-info
# ノードの状態確認
kubectl get nodes
kubectl describe nodes
# 全リソースの状態確認
kubectl get all --all-namespaces
# クラスターのイベント確認
kubectl get events --sort-by=.metadata.creationTimestamp
事例1: Podが起動しない
症状
- Podが
Pending状態で起動しない - Podが
CrashLoopBackOff状態 - Podが
ImagePullBackOff状態
対応コマンド
# Podの詳細情報確認
kubectl describe pod <pod-name> -n <namespace>
# Podのログ確認
kubectl logs <pod-name> -n <namespace>
kubectl logs <pod-name> -n <namespace> --previous # 前回のログ
# Podの状態確認
kubectl get pods -n <namespace> -o wide
# イベント確認
kubectl get events -n <namespace> --sort-by=.metadata.creationTimestamp
# リソース使用量確認
kubectl top pods -n <namespace>
kubectl top nodes
よくある原因と対処法
リソース不足:
# ノードのリソース確認
kubectl describe nodes | grep -A 5 "Allocated resources"
# リソース制限の確認
kubectl get pods -n <namespace> -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.spec.containers[*].resources}{"\n"}{end}'
イメージプルエラー:
# イメージの確認
kubectl get pods -n <namespace> -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.spec.containers[*].image}{"\n"}{end}'
# イメージプルシークレット確認
kubectl get secrets -n <namespace>
事例2: Serviceにアクセスできない
症状
- Service経由でアプリケーションにアクセスできない
- ロードバランシングが機能しない
- 外部からアクセスできない
対応コマンド
# Serviceの詳細確認
kubectl describe service <service-name> -n <namespace>
# Endpointの確認
kubectl get endpoints -n <namespace>
kubectl describe endpoints <service-name> -n <namespace>
# Podのラベル確認
kubectl get pods -n <namespace> --show-labels
# Serviceのセレクター確認
kubectl get service <service-name> -n <namespace> -o yaml | grep selector -A 5
# ネットワークポリシー確認
kubectl get networkpolicies -n <namespace>
接続テスト
# クラスター内からの接続テスト
kubectl run test-pod --image=busybox --rm -it --restart=Never -- nslookup <service-name>.<namespace>.svc.cluster.local
# ポート接続テスト
kubectl run test-pod --image=busybox --rm -it --restart=Never -- wget -O- <service-name>.<namespace>.svc.cluster.local:<port>
事例3: デプロイメントが失敗する
症状
- デプロイメントが
Progressing状態で止まる - ローリングアップデートが失敗する
- レプリカ数が期待値にならない
対応コマンド
# デプロイメントの詳細確認
kubectl describe deployment <deployment-name> -n <namespace>
# ReplicaSetの確認
kubectl get replicasets -n <namespace>
kubectl describe replicaset <replicaset-name> -n <namespace>
# デプロイメントの履歴確認
kubectl rollout history deployment/<deployment-name> -n <namespace>
# ロールアウトの状態確認
kubectl rollout status deployment/<deployment-name> -n <namespace>
# ロールバック
kubectl rollout undo deployment/<deployment-name> -n <namespace>
kubectl rollout undo deployment/<deployment-name> -n <namespace> --to-revision=<revision-number>
スケーリング関連
# レプリカ数の確認
kubectl get deployment <deployment-name> -n <namespace> -o jsonpath='{.spec.replicas}'
# 手動スケーリング
kubectl scale deployment <deployment-name> --replicas=<number> -n <namespace>
# HPAの確認
kubectl get hpa -n <namespace>
kubectl describe hpa <hpa-name> -n <namespace>
事例4: ストレージ関連の問題
症状
- 永続ボリュームがマウントできない
- ストレージクラスが見つからない
- データが消失した
対応コマンド
# PersistentVolumeの確認
kubectl get pv
kubectl describe pv <pv-name>
# PersistentVolumeClaimの確認
kubectl get pvc -n <namespace>
kubectl describe pvc <pvc-name> -n <namespace>
# ストレージクラスの確認
kubectl get storageclass
kubectl describe storageclass <storageclass-name>
# ボリュームの使用状況確認
kubectl get pods -n <namespace> -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.spec.volumes}{"\n"}{end}'
事例5: ネットワーク関連の問題
症状
- Pod間通信ができない
- 外部ネットワークにアクセスできない
- DNS解決ができない
対応コマンド
# ネットワークポリシーの確認
kubectl get networkpolicies -n <namespace>
kubectl describe networkpolicy <networkpolicy-name> -n <namespace>
# DNS設定の確認
kubectl get configmap -n kube-system | grep coredns
kubectl describe configmap coredns -n kube-system
# ネットワーク接続テスト
kubectl run test-pod --image=busybox --rm -it --restart=Never -- nslookup kubernetes.default
# サービスディスカバリの確認
kubectl get services -n <namespace>
kubectl get endpoints -n <namespace>
事例6: セキュリティ関連の問題
症状
- RBAC権限エラー
- セキュリティコンテキストの問題
- シークレットが読み込めない
対応コマンド
# RBAC権限の確認
kubectl auth can-i <verb> <resource> -n <namespace>
kubectl auth can-i list pods --as=system:serviceaccount:<namespace>:<serviceaccount>
# ServiceAccountの確認
kubectl get serviceaccounts -n <namespace>
kubectl describe serviceaccount <serviceaccount-name> -n <namespace>
# Role/RoleBindingの確認
kubectl get roles -n <namespace>
kubectl get rolebindings -n <namespace>
kubectl describe rolebinding <rolebinding-name> -n <namespace>
# シークレットの確認
kubectl get secrets -n <namespace>
kubectl describe secret <secret-name> -n <namespace>
事例7: リソース使用量の問題
症状
- ノードのリソース不足
- PodがOOMKilledされる
- スケジューリングができない
対応コマンド
# リソース使用量の確認
kubectl top nodes
kubectl top pods -n <namespace>
kubectl top pods --all-namespaces
# リソース制限の確認
kubectl describe nodes | grep -A 10 "Allocated resources"
# リソースクォータの確認
kubectl get resourcequotas -n <namespace>
kubectl describe resourcequota <resourcequota-name> -n <namespace>
# LimitRangeの確認
kubectl get limitranges -n <namespace>
kubectl describe limitrange <limitrange-name> -n <namespace>
便利なワンライナーコマンド
よく使う確認コマンド
# 全Podの状態を一覧表示
kubectl get pods --all-namespaces -o wide
# 異常なPodを検索
kubectl get pods --all-namespaces --field-selector=status.phase!=Running
# リソース使用量上位のPod
kubectl top pods --all-namespaces --sort-by=memory
# 最近のイベント
kubectl get events --all-namespaces --sort-by=.metadata.creationTimestamp | tail -20
# 全リソースの削除（危険）
kubectl delete all --all -n <namespace>
デバッグ用コマンド
# Pod内でコマンド実行
kubectl exec -it <pod-name> -n <namespace> -- /bin/bash
# 一時的なデバッグPod作成
kubectl run debug-pod --image=busybox --rm -it --restart=Never -- /bin/sh
# ポートフォワーディング
kubectl port-forward <pod-name> <local-port>:<pod-port> -n <namespace>
# ログのリアルタイム監視
kubectl logs -f <pod-name> -n <namespace>
まとめ
Kubernetes環境でのトラブルシューティングは、まず現状を正確に把握することが重要ですので、このチートシートを参考に、段階的に問題を切り分けていきます。
トラブルシューティングの基本手順:
-
現状確認:
kubectl getでリソースの状態を確認 -
詳細調査:
kubectl describeで詳細情報を取得 -
ログ確認:
kubectl logsでアプリケーションログを確認 -
イベント確認:
kubectl get eventsでクラスターイベントを確認 - 段階的対処: 問題を特定して適切な対処を実施