Use kubectl describe to inspect a Kubernetes resource when status alone does not explain a failure. Its output exposes configuration, container state, failure reasons, and events. section 8.1.1 section 8.2.2
Apply the command to operational troubleshooting tasks:
- Run kubectl describe po <pod> after kubectl logs returns nothing because the container has not started. section 8.1.1
- Inspect container state, termination messages, exit codes, restart counts, readiness, and pod events. section 8.1.1
- Run kubectl describe node <node> to review node conditions, events, and allocated CPU and memory requests. section 8.2.2
- Investigate control-plane pods when scheduling or reconciliation fails; combine describe with logs for the scheduler and other components. section 8.2
Diagnosing a pod that will not start
Create the failing pod with kubectl run brick --image busybox --command 'while true; do echo "$(date)"; sleep 5; done'. After kubectl logs brick returns no output, run kubectl describe po brick. The output identifies RunContainerError, reports that the requested process cannot be found in PATH, and records related events. section 8.1.1
Diagnosing a scheduler failure
After scaling prod-app from one to three replicas, two pods remain Pending. Inspect the kube-scheduler pod with kubectl -n kube-system logs and kubectl describe; an invalid scheduler argument explains why new replicas are not assigned. section 8.2
root@kind-control-plane:/# kubectl describe po brick
Name: brick
Namespace: db08328
Command:
while true; do echo "$(date)"; sleep 5; done
State: Waiting
Reason: RunContainerError
Last State: Terminated
Reason: StartError
Message: failed to create containerd task: failed to create shim
task: OCI runtime create failed: runc create failed: unable to start
container process: exec: "while true; do echo \"$(date)\"; sleep 5;
done": executable file not found in $PATH: unknown
Exit Code: 128
Started: Thu, 01 Jan 1970 00:00:00 +0000
Finished: Wed, 07 Dec 2022 01:15:04 +0000
Ready: False
Restart Count: 2
Events:
Type Reason Age From Message
---- ------ ---- ---- -------
Normal Scheduled 19s default-scheduler Successfully
assigned db08328/brick to kind-control-plane
Normal Pulled 18s kubelet Successfully
pulled image "busybox" in 494.040497ms
Normal Pulled 17s kubelet Successfully
pulled image "busybox" in 494.479219ms
Normal Pulling 5s (x3 over 19s) kubelet Pulling image
"busybox"
Normal Created 4s (x3 over 18s) kubelet Created
container brick
Warning Failed 4s (x3 over 18s) kubelet Error: failed to
create containerd task: failed to create shim task: OCI runtime create
failed: runc create failed: unable to start container process: exec:
"while true; do echo \"$(date)\"; sleep 5; done": executable file not
found in $PATH: unknown
Normal Pulled 4s kubelet Successfully
pulled image "busybox" in 509.215883ms
Warning BackOff 3s (x3 over 17s) kubelet Back-off
restarting failed container
Use the abbreviated pod description to locate the resource state, termination reason, diagnostic message, exit code, and event history in one output. section 8.1.1
