BiteSizedChunks.comLearn one small thing at a time.
Course contentsShow
← Docker, Kubernetes & CI/CD
Lesson 262 of 8024. Kubernetes Architecture and Core ObjectsFree lesson

Troubleshooting Pod Scheduling Failures

You will diagnose common scheduling issues by inspecting event logs and pod status conditions to resolve pending or crash-looping workloads.

In this lesson, you will learn how to identify why a Pod is stuck in the Pending state and how to resolve common scheduling roadblocks using native Kubernetes tools.

The Mystery of the 'Pending' Pod

When you deploy a Pod, the Kubernetes Scheduler attempts to place it on a node that meets all its requirements. If the Pod remains in Pending indefinitely, it means the Scheduler cannot find a suitable home for it. To find out why, we don't guess—we inspect the cluster's internal reporting.

Inspecting the Evidence

The first step in troubleshooting is to look at the Pod’s status and events. Run the following command:

kubectl describe pod <pod-name>

Scroll down to the Events section at the bottom of the output. This is where the Scheduler explains its failure. You will often see messages like:

  • 0/3 nodes are available: 3 Insufficient cpu. (Resource exhaustion)
  • 0/3 nodes are available: 3 node(s) didn't match pod anti-affinity rules. (Constraint conflict)
  • 0/3 nodes are available: 3 node(s) had taint "key=value:NoSchedule". (Taint mismatch)

Diagnosing and Resolving

Once you have the event log, you know exactly what is wrong.

  1. Insufficient Resources: If the error mentions CPU or memory, your Pod is requesting more resources than any single node has available. Check your requests in your Pod definition (Lesson 21) or consider scaling your cluster.
  2. Taints and Tolerations: If the error is about taints, it means your Pod is trying to land on a node that is "off-limits" to general workloads. You must either remove the taint from the node or add a toleration to your Pod spec to match the taint.
  3. Affinity/Anti-Affinity: If the error involves affinity, the Pod is likely trying to be placed according to rules that simply cannot be satisfied by the current cluster topology (Lesson 23).

By checking the describe output, you move from guesswork to a clear understanding of the reconciliation gap between your requested state and the cluster's actual capacity.

Key Takeaway: When a Pod stays in 'Pending', the 'kubectl describe' command is your primary diagnostic tool, as the 'Events' section explicitly explains why the Scheduler could not place the workload.