1. はじめに
Kubernetes の運用・保守していると Pod が正常に立ち上がらない問題に遭遇します。
立ち上がらない理由は、多くあると思いますが、初動確認手順は、おおよそ似通っているため、調査手順をまとめてみました。
不具合が起こった時、焦ってしまいますが、ある程度手順を決めておくと冷静に対処できると思います。
1.1. 検証環境について
本記事の動作確認には、ローカル環境で手軽に Kubernetes クラスターを構築できる kind (Kubernetes IN Docker) を使用しています。
2. 全体の調査フロー
- 異常な Pod を特定する
kubectl get pod -Aで稼働していない Pod の特定を行う。- Pending, CrashLoopBackOff, ImagePullBackOff など
- describe でイベントを確認する
- kubectl describe pod
-n
- kubectl describe pod
- logsでコンテナの中を確認
- kubectl logs
-n
- kubectl logs
- 依存リソースも確認
3. 異常な Pod を特定する
- kubectl get pod -A で全名前空間の Pod を一覧する。
- 異常なステータスの Pod を特定する。ここでは、
error-image-podのImagePullBackOffの状態であることがわかります。
- 異常なステータスの Pod を特定する。ここでは、
kubectl get pod -A
NAMESPACE NAME READY STATUS RESTARTS AGE
default error-image-pod 0/1 ImagePullBackOff 0 20s
kube-system coredns-7d764666f9-54bl2 1/1 Running 0 3m40s
kube-system coredns-7d764666f9-kn66c 1/1 Running 0 3m40s
kube-system etcd-kind-control-plane 1/1 Running 0 3m46s
kube-system kindnet-q75q4 1/1 Running 0 3m40s
kube-system kube-apiserver-kind-control-plane 1/1 Running 0 3m46s
kube-system kube-controller-manager-kind-control-plane 1/1 Running 0 3m45s
kube-system kube-proxy-tw269 1/1 Running 0 3m40s
kube-system kube-scheduler-kind-control-plane 1/1 Running 0 3m46s
4. describe でイベントを確認する
kubectl describe pod で pod のイベント詳細を確認する。
ここでは、Events の項目に docker.io/library/nginx:999.999": docker.io/library/nginx:999.999: not found が出力されているので、
存在していないイメージを取得しようとしていることがわかる。
kubectl describe pod error-image-pod -n default
Name: error-image-pod
Namespace: default
Priority: 0
Service Account: default
Node: kind-control-plane/172.19.0.2
Start Time: Sun, 29 Mar 2026 14:53:21 +0900
Labels: <none>
Annotations: <none>
Status: Pending
********* 途中省略 *********
Events:
Type Reason Age From Message
---- ------ ---- ---- -------
Normal Scheduled 6m50s default-scheduler Successfully assigned default/error-image-pod to kind-control-plane
Normal Pulling 3m56s (x5 over 6m50s) kubelet Pulling image "nginx:999.999"
Warning Failed 3m55s (x5 over 6m48s) kubelet Failed to pull image "nginx:999.999": rpc error: code = NotFound desc = failed to pull and unpack image "docker.io/library/nginx:999.999": failed to resolve reference "docker.io/library/nginx:999.999": docker.io/library/nginx:999.999: not found
Warning Failed 3m55s (x5 over 6m48s) kubelet Error: ErrImagePull
Normal BackOff 98s (x21 over 6m48s) kubelet Back-off pulling image "nginx:999.999"
Warning Failed 98s (x21 over 6m48s) kubelet Error: ImagePullBackOff
5. logsでコンテナの中を確認
今回のケースでは、3. describe でイベントを確認する で原因がわかりましたが、念の為、Pod 内のログを確認してみます。
やはり、image のpull に失敗しているようです。
kubectl logs error-image-pod -n default
Error from server (BadRequest): container "nginx" in pod "error-image-pod" is waiting to start: trying and failing to pull image
6. 不具合箇所の修正を行う
6.1. マニュフェストを修正
存在する image のバージョンを指定する。
cat <<EOF | kubectl apply -f -
apiVersion: v1
kind: Pod
metadata:
name: error-image-pod
spec:
containers:
- name: nginx
image: nginx:latest ★ 最新のイメージを指定
EOF
pod/error-image-pod configured
6.2. Pod のステータスを確認
error-image-pod のポッドが Ready になっている。
kubectl get pod -A
NAMESPACE NAME READY STATUS RESTARTS AGE
default error-image-pod 1/1 Running 0 19m
kube-system coredns-7d764666f9-54bl2 1/1 Running 0 23m
7. よくあるエラー例
エラーの一例をまとめました。
| ステータス | 意味 | 主な原因 |
|---|---|---|
| Pending | スケジュール待ち | ノードのリソース（CPU/メモリ）不足、NodeSelector の不一致 |
| CrashLoopBackOff | 起動直後の異常終了 | アプリのバグ、環境変数の設定ミス |
| OOMKilled | メモリ不足による強制終了 | メモリ不足による強制終了,コンテナのメモリ制限 |
8. まとめ
-
Kubernetes の Pod が立ち上がらない時の調査は、以下の 3 ステップを基本にします。
-
kubectl get pod: まずは「何が起きているか（Status）」を確認する。
-
kubectl describe: K8s システム側（イメージ取得、リソース割り当て等）のイベントを確認する。
-
kubectl logs: アプリケーション内部のエラーが出力されていないか確認する。
今回は kind を使い、意図的にイメージタグを間違えることで ImagePullBackOff を再現しました。他にも、リソース不足（Pending）や、起動スクリプトのミス（CrashLoopBackOff）など、さまざまなパターンがあります。
トラブルが起きた際に「どこを見ればいいか」が決まっているだけで、心理的な余裕が生まれます。ぜひこの調査フローを手癖にしてみてください。