kubectl Debugging Cheat Sheet

When something breaks in Kubernetes, the answer is usually in a handful of commands. Start with the Pod's status, then events, then logs.

First look

kubectl get pods -n shop -o wide          # status, restarts, node
kubectl describe pod api-7d9f-x2k -n shop # events at the bottom are gold
kubectl get events -n shop --sort-by=.lastTimestamp | tail -20

Read the status

CrashLoopBackOff - the container starts and exits repeatedly.

kubectl logs api-7d9f-x2k -n shop --previous   # logs from the crashed attempt

Common causes: missing environment variables, failing database connection at startup, wrong command, or a liveness probe killing a slow-starting app.

ImagePullBackOff / ErrImagePull - wrong image name or tag, or missing registry credentials (imagePullSecrets).

Pending - the scheduler can't place the Pod. describe shows why: not enough CPU/memory for the requests, node selectors or taints that don't match, or an unbound PersistentVolumeClaim.

OOMKilled - exceeded its memory limit:

kubectl get pod api-7d9f-x2k -n shop -o jsonpath='{.status.containerStatuses[0].lastState.terminated.reason}'

Service not reachable?

kubectl get endpointslices -n shop -l kubernetes.io/service-name=api   # empty = no ready Pods match
kubectl get pods -n shop -l app=api --show-labels                     # do labels match the selector?
kubectl port-forward svc/api 8080:80 -n shop                          # test the Service directly

Get inside

kubectl exec -it deploy/api -n shop -- sh
# Minimal image without a shell? Attach an ephemeral debug container:
kubectl debug -it api-7d9f-x2k -n shop --image=busybox --target=api
# Run a throwaway pod with network tools:
kubectl run tmp --rm -it --image=nicolaka/netshoot -n shop -- bash

Rollouts

kubectl rollout status deploy/api -n shop
kubectl rollout history deploy/api -n shop
kubectl rollout undo deploy/api -n shop