How to Diagnose and Fix Common Kubernetes Pod Issues

Pod troubleshooting

1. Pod stuck in Pending

Run kubectl describe pod ${POD_NAME} to see why the scheduler did not place the pod. Common reasons:

Resource shortage : CPU or memory requests exceed the capacity of the cluster. Delete unused pods, lower requests, or add nodes.

Use of hostPort : Binding a pod to a specific host port limits the number of pods to the number of nodes. Prefer a Service for exposure unless a hostPort is strictly required.

2. Pod in Waiting state

The pod is scheduled but cannot start, most often because the container image cannot be pulled. Verify:

The image name is correct.

The image exists in the referenced registry.

Manually pull the image with docker pull <image> to test connectivity.

3. Pod crashing or unhealthy

Inspect container logs: kubectl logs ${POD_NAME} ${CONTAINER_NAME} If the container has already terminated, view the previous instance’s log:

kubectl logs --previous ${POD_NAME} ${CONTAINER_NAME}

For deeper inspection, execute a command inside the container:

kubectl exec ${POD_NAME} -c ${CONTAINER_NAME} -- ${CMD} ${ARG1} ${ARG2} ... ${ARGN}

When a pod contains a single container, the -c ${CONTAINER_NAME} flag can be omitted.

4. Pod reports Running but does not behave as expected

Often a typo or misplaced field in the pod manifest is silently ignored. Re‑create the pod with validation to surface such errors: kubectl create --validate -f mypod.yaml For example, misspelling command as commnd yields an "unknown field" error. If no error appears, compare the pod object returned by the API server with the original YAML:

kubectl get pod mypod -o yaml > mypod-on-apiserver.yaml

Differences indicate fields that were ignored or altered during creation.

Controller troubleshooting

ReplicationControllers are simple; they either create pods or they do not. Use the following command to view events and diagnose failures:

kubectl describe rc ${CONTROLLER_NAME}

Service troubleshooting

First verify that the Service has associated endpoints: kubectl get endpoints ${SERVICE_NAME} Ensure the number of endpoint IPs matches the expected pod replica count. If endpoints are missing, list pods that match the Service’s selector and confirm they expose the correct containerPort:

kubectl get pods --selector=name=nginx,type=frontend

A mismatch between the Service’s containerPort and the pod’s exposed port prevents endpoint creation.

Network troubleshooting

If a client can connect to a Service but the connection is immediately closed, check the following:

Are the pods healthy? Review restart counts and use the pod‑debug steps above.

Can you reach the pod directly? Retrieve the pod’s IP and attempt a direct connection.

Is the application listening on the port declared in containerPort? Kubernetes does not perform port translation; the container must expose the same port the application uses.