Encountering a pod that stubbornly stays in the Pending state can be frustrating, especially when you’re in the middle of a deployment. This state means that the pod has been accepted by the Kubernetes cluster but cannot be scheduled onto a node. The reasons for this can vary, including insufficient resources, scheduling constraints, or issues with Persistent Volumes. Understanding how to systematically diagnose and resolve these issues is crucial for maintaining the smooth operation of your Kubernetes environment.
Thank me by sharing on Twitter 🙏
Understanding the Pod Lifecycle
Before diving into the troubleshooting steps, it’s important to understand a bit about the pod lifecycle in Kubernetes. A pod represents a single instance of a running process in your cluster. When you create a pod, Kubernetes will attempt to find a node that can accommodate it based on the specified requirements. If it can’t, the pod will remain in a Pending state until the conditions are met.
Checking Pod Status
The first step in diagnosing a pending pod is to check its status. This can be done using the kubectl describe pod command, which provides detailed information about the pod, including any events that might have occurred.
kubectl describe pod <pod-name>Example
kubectl describe pod my-pending-podThis command will output a lot of information, but the key section to look at is the events at the bottom. These events often provide clues about why the pod is pending.
Checking Node Status
Next, ensure that your nodes are ready and have sufficient resources. Nodes in your Kubernetes cluster must be in a Ready state to schedule pods.
uni SD Card Reader, High-Speed USB C to Micro SD Card Adapter USB 3.0 Dual Slots, Memory Card Reader for SD/Micro SD/SDHC/SDXC/MMC, Compatible with MacBook Pro/Air, Chromebook, Android Galaxy
$9.99 (as of January 22, 2025 11:32 GMT +00:00 - More infoProduct prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on [relevant Amazon Site(s), as applicable] at the time of purchase will apply to the purchase of this product.)
4Pack [Apple MFi Certified] Charger Lightning to USB Charging Cable Cord Compatible iPhone 14/13/12/11 Pro/11/XS MAX/XR/8/7/6s Plus,iPad Pro/Air/Mini,iPod Touch
$8.49 (as of January 22, 2025 11:32 GMT +00:00 - More infoProduct prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on [relevant Amazon Site(s), as applicable] at the time of purchase will apply to the purchase of this product.)
The Legend of Zelda™: Tears of the Kingdom – The Complete Official Guide: Collector's Edition
$26.85 (as of January 22, 2025 11:32 GMT +00:00 - More infoProduct prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on [relevant Amazon Site(s), as applicable] at the time of purchase will apply to the purchase of this product.)kubectl get nodesExample
kubectl get nodesThe output should list all nodes and their statuses. If any nodes are not in the Ready state, this could be why your pod is pending. You can get more details about a specific node with:
kubectl describe node <node-name>Example
kubectl describe node node-1This will provide detailed information about the node, including any conditions that might be affecting its readiness.
Resource Requests and Limits
Another common reason for pods staying pending is insufficient resources on any node to satisfy the pod’s resource requests. When you create a pod, you can specify resource requests and limits for CPU and memory. Kubernetes uses these values to determine where to place the pod.
kubectl describe pod <pod-name>Look for the Requests and Limits section under Containers. If the requested resources are too high, Kubernetes might not be able to find a suitable node.
Example
apiVersion: v1
kind: Pod
metadata:
name: my-pending-pod
spec:
containers:
- name: my-container
image: my-image
resources:
requests:
memory: "64Mi"
cpu: "250m"
limits:
memory: "128Mi"
cpu: "500m"Adjusting these values to be more in line with what your cluster can provide might resolve the issue.
Scheduling Constraints
Scheduling constraints like node selectors, taints, tolerations, and affinity/anti-affinity rules can also prevent a pod from being scheduled.
Node Selectors
Node selectors are a simple way to constrain a pod to only be scheduled on nodes with specific labels.
apiVersion: v1
kind: Pod
metadata:
name: my-pending-pod
spec:
containers:
- name: my-container
image: my-image
nodeSelector:
disktype: ssdTaints and Tolerations
Taints and tolerations work together to ensure that pods are not scheduled onto inappropriate nodes.
apiVersion: v1
kind: Pod
metadata:
name: my-pending-pod
spec:
containers:
- name: my-container
image: my-image
tolerations:
- key: "key1"
operator: "Equal"
value: "value1"
effect: "NoSchedule"Affinity and Anti-Affinity
Affinity and anti-affinity rules provide more expressive ways to influence pod placement.
apiVersion: v1
kind: Pod
metadata:
name: my-pending-pod
spec:
affinity:
nodeAffinity:
requiredDuringSchedulingIgnoredDuringExecution:
nodeSelectorTerms:
- matchExpressions:
- key: kubernetes.io/e2e-az-name
operator: In
values:
- e2e-az1
- e2e-az2
containers:
- name: my-container
image: my-imageChecking Cluster Resource Quotas
Namespaces in Kubernetes can have resource quotas to limit the amount of resources that can be consumed. If these quotas are exceeded, new pods cannot be scheduled.
kubectl get resourcequotas --all-namespacesExample
kubectl get resourcequotas -n my-namespace
kubectl describe resourcequota <quota-name> -n my-namespacePersistent Volume Claims
If your pod uses Persistent Volumes (PVs), ensure that the Persistent Volume Claims (PVCs) are correctly bound.
kubectl get pvc
kubectl describe pvc <pvc-name>Example
kubectl get pvc my-pvc
kubectl describe pvc my-pvcThis will show if the PVC is bound to a PV. If not, the pod will remain pending until the PVC is successfully bound.
Network Policies
Network policies might prevent pods from communicating with each other or with external services. These policies define how groups of pods are allowed to communicate with each other and other network endpoints.
kubectl get networkpolicyExample
kubectl get networkpolicy -n my-namespace
kubectl describe networkpolicy <policy-name> -n my-namespaceReviewing and adjusting these policies can help in ensuring that the pods can communicate as expected.
Pod Disruption Budgets
Pod Disruption Budgets (PDBs) ensure that a certain number or percentage of pods remain available during voluntary disruptions. If there are strict PDBs, they might prevent the scheduling of new pods.
kubectl get pdbExample
kubectl get pdb -n my-namespace
kubectl describe pdb <pdb-name> -n my-namespaceAdjusting the PDB settings can sometimes resolve the pending issue.
Checking Kubernetes Scheduler Logs
Finally, checking the logs of the Kubernetes scheduler can provide insights into why the pod is not being scheduled.
kubectl logs -n kube-system <scheduler-pod-name>Example
kubectl logs -n kube-system kube-scheduler-my-nodeThe scheduler logs can contain valuable information about scheduling decisions and errors.
Conclusion
Diagnosing why a pod remains in a Pending state in Kubernetes involves a systematic approach to identify and resolve resource constraints, scheduling issues, and configuration errors. By following the steps outlined above, you can pinpoint the cause and take corrective actions to ensure that your pods are successfully scheduled and running. Kubernetes is a powerful platform, and understanding how to troubleshoot common issues is essential for maintaining the health and performance of your applications.
