Writing sample submitted for a Kubernetes reference document
The team asked prospective writers to document several kubectl options that would help diagnose common deployment issues. The piece was meant to be part of a set of Troubleshooting articles. Code samples come from a minikube cluster deployed on my Linux laptop, run and verified before writing rather than assumed from documentation alone.
Following the team's style guide, I used title case for headings and linked out to mainstream Kubernetes documentation rather than restating it.
Pod Inspection and Troubleshooting with kubectl
Use the Kubernetes command line tool, kubectl, to review the status of pods in your deployment. You can also use it to review log files from within a pod, to inspect containers within a pod, and to debug failing pods.
Pod Status Reviews
Get a list of available pods and their status in a specific namespace:
kubectl get pods --namespace taz-k8s-spectrocloud-demo
You can omit namespace if there's only a default namespace, and it's the namespace you want to review; otherwise, you must specify namespace.
NAME READY STATUS RESTARTS AGE
taz-tea-pod1-b84749c76-vdlgs 1/1 Running 0 3h1m
taz-tea-pod2-5d6f76cc69-qttbc 1/1 Running 0 3h1m
taz-tea-pod3-7cc59c58f8-2ngf2 1/1 Running 0 3h1m
taz-tea-pod4-85d6d79f5f-d2mnz 1/1 Running 0 3h1m
If you see that any of your pods does not have a STATUS of Running, such as NotReady or Pending, use other kubectl options to gather more information about or troubleshoot issues with a specific pod.
Detailed Pod Reviews
Display details about a pod by specifying <pod_name> and namespace:
kubectl describe pod taz-tea-pod1-b84749c76-4thbp --namespace taz-k8s-spectrocloud-demo
Name: taz-tea-pod1-b84749c76-4thbp
Namespace: taz-k8s-spectrocloud-demo
Priority: 0
Service Account: default
Node: minikube/192.168.58.2
Start Time: Wed, 22 Apr 2026 20:12:28 -0400
Labels: app=taz-tea-pod1
pod-template-hash=b84749c76
Annotations: <none>
Status: Running
IP: 10.244.0.11
IPs:
IP: 10.244.0.11
Controlled By: ReplicaSet/taz-tea-pod1-b84749c76
Containers:
nginx:
Container ID: docker://28deca529263e910251400cc9933b2362cb140f016eb8cef26c0789b74637f29
Image: nginx:latest
Image ID: docker-pullable://nginx@sha256:6e23479198b998e5e25921dff8455837c7636a67111a04a635cf1bb363d199dc
Port: <none>
Host Port: <none>
State: Running
Started: Wed, 22 Apr 2026 20:12:29 -0400
Ready: True
Restart Count: 0
Environment: <none>
Mounts:
/var/run/secrets/kubernetes.io/serviceaccount from kube-api-access-zsgbq (ro)
Conditions:
Type Status
PodReadyToStartContainers True
Initialized True
Ready True
ContainersReady True
PodScheduled True
Volumes:
kube-api-access-zsgbq:
Type: Projected (a volume that contains injected data from multiple sources)
TokenExpirationSeconds: 3607
ConfigMapName: kube-root-ca.crt
Optional: false
DownwardAPI: true
QoS Class: BestEffort
Node-Selectors: <none>
Tolerations: node.kubernetes.io/not-ready:NoExecute op=Exists for 300s
node.kubernetes.io/unreachable:NoExecute op=Exists for 300s
Events:
Type Reason Age From Message
---- ------ ---- ---- -------
Normal Scheduled 35s default-scheduler Successfully assigned taz-k8s-spectrocloud-demo/taz-tea-pod1-b84749c76-4thbp to minikube
Normal Pulling 34s kubelet Pulling image "nginx:latest"
Normal Pulled 34s kubelet Successfully pulled image "nginx:latest" in 392ms (392ms including waiting). Image size: 160939956 bytes.
Normal Created 34s kubelet Created container: nginx
Normal Started 34s kubelet Started container nginx
Review the pod's status, container state, and events to troubleshoot issues.
Log Reviews
Review the logs generated by a pod for details related to an event or for informational purposes.
Display the logs by specifying <pod_name> and namespace:
kubectl logs taz-tea-pod1-b84749c76-vdlgs --namespace taz-k8s-spectrocloud-demo
Review the output in your terminal or copy it to a text file for easier searching.
Container Inspections
Use the kubectl exec option to run diagnostic tools inside the container running in a specific pod. Inspect files and directories inside the container by specifying <pod_name> and namespace:
kubectl exec taz-tea-pod1-b84749c76-vdlgs --namespace taz-k8s-spectrocloud-demo -- ls -la /etc/nginx/
Defaulted container "nginx" out of: nginx, debugger-vtp28 (ephem)
total 48
drwxr-xr-x 1 root root 4096 Apr 22 01:22 .
drwxr-xr-x 1 root root 4096 Apr 22 15:17 ..
drwxr-xr-x 1 root root 4096 Apr 22 15:17 conf.d
-rw-r--r-- 1 root root 1007 Apr 7 11:37 fastcgi_params
-rw-r--r-- 1 root root 5349 Apr 7 11:37 mime.types
lrwxrwxrwx 1 root root 22 Apr 7 11:51 modules -> /usr/lib/nginx/modules
-rw-r--r-- 1 root root 644 Apr 7 11:51 nginx.conf
-rw-r--r-- 1 root root 636 Apr 7 11:37 scgi_params
-rw-r--r-- 1 root root 664 Apr 7 11:37 uwsgi_params
Review the output to verify that the required files and directories are present with the expected permissions.
The kubectl exec option supports many flags for different use cases. For additional command options, see the kubectl exec reference.
Crashed Pod Debugging
When a pod crashes repeatedly, use the kubectl debug <pod_name> option to create an ephemeral debug container and inspect the pod's filesystem and environment.
After you debug a pod, the ephemeral container remains in the pod description, even after it terminates. Kubernetes maintains a record of it in the pod description for inspection and logging purposes. It doesn't affect the running pod. To remove the ephemeral container from the description, delete the pod; when the deployment recreates it, the new pod description no longer mentions the ephemeral container, so subsequent logs no longer include it.
For more information, see Debugging with an ephemeral debug container.