Pod stuck in Pending state in Kubernetes - Commands & Configuration

Introduction

Sometimes, a Kubernetes pod does not start running and stays in Pending state. This means Kubernetes is trying to find a place to run the pod but cannot. This problem stops your app from working.

When you deploy a new pod and it never starts running.

When your pod is waiting but not showing any errors.

When you want to check why Kubernetes cannot schedule your pod.

When your cluster resources are full and new pods cannot start.

When you suspect configuration issues like missing node selectors or insufficient resources.

Commands

Check the status of all pods in the current namespace to see which pods are Pending.

Terminal

kubectl get pods

Expected Output

NAME           READY   STATUS    RESTARTS   AGE

example-pod    0/1     Pending   0          2m

Get detailed information about the pod, including events that explain why it is Pending.

Terminal

kubectl describe pod example-pod

Expected Output

Name:           example-pod

Namespace:      default

Status:         Pending

...

Events:

  Type     Reason            Age   From               Message

  ----     ------            ----  ----               -------

  Warning  FailedScheduling  1m    default-scheduler  0/3 nodes are available: 3 Insufficient cpu.

Check the status and resources of all nodes to see if they can run new pods.

Terminal

kubectl get nodes

Expected Output

NAME           STATUS   ROLES    AGE   VERSION

node-1         Ready    <none>   10d   v1.26.0

node-2         Ready    <none>   10d   v1.26.0

node-3         Ready    <none>   10d   v1.26.0

Look at the resources and conditions of a specific node to find if it has enough CPU and memory.

Terminal

kubectl describe node node-1

Expected Output

Name:               node-1

...

Allocated resources:

  (Total limits may be over 100 percent, i.e., overcommitted.)

  CPU Requests  400m

  CPU Limits    0

  Memory Requests  512Mi

  Memory Limits    0

Conditions:

  Type             Status

  ----             ------

  Ready            True

Key Concept

If a pod is stuck in Pending, check pod events and node resources to find why Kubernetes cannot schedule it.

Common Mistakes

Ignoring pod events and only looking at pod status.

Pod status 'Pending' alone does not explain the cause; events show detailed reasons like resource shortages.

Always run 'kubectl describe pod' to see events explaining the Pending state.

Assuming nodes have enough resources without checking.

Nodes may be full or have resource limits preventing new pods from running.

Check node resources and conditions with 'kubectl describe node' to confirm availability.

Not verifying node selectors or affinity rules in pod specs.

Pods may request to run only on specific nodes that do not exist or are full.

Review pod spec for node selectors or affinity and ensure matching nodes are available.

Summary

Use 'kubectl get pods' to identify pods stuck in Pending state.

Use 'kubectl describe pod <pod-name>' to see detailed events explaining why the pod is Pending.

Check node status and resources with 'kubectl get nodes' and 'kubectl describe node <node-name>' to find resource shortages or conditions blocking scheduling.