Pending Pods and PVCs: separate scheduling from storage

Before you start

Kubernetes clusters using PersistentVolumeClaims; Bash examples. StorageClass and CSI behavior must be checked for the installed driver and Kubernetes version. Documentation-reviewed on 2026-09-07.

Commands are examples, not actions run by this page. Replace the sample names and paths. Run related blocks in the same shell. Read the explanations before copying. Logs and configuration can contain private data; keep credentials and unredacted evidence out of public posts.

Validation: documentation-reviewed guidance, not a tested live-cluster repair.

Replace the namespace, Pod, and claim with real incident targets. Cluster-wide StorageClass and node information may require a platform owner. These instructions inspect state; they do not create storage, detach volumes, or authorize deleting a claim.

1. Locate the blocked stage

Distinguish an unscheduled Pod from a scheduled Pod waiting for image preparation or volume mounting. Read conditions and recent events rather than interpreting the Pending label alone. A Bound claim proves binding, not that the filesystem was mounted successfully or that the application can use it.

Inspect · Inspect the Pod and the claim it actually references

HELP_NS='REPLACE_NAMESPACE'
HELP_POD='REPLACE_POD'
HELP_PVC='REPLACE_REFERENCED_PVC'
kubectl config current-context
kubectl -n "$HELP_NS" get pod "$HELP_POD" -o wide
kubectl -n "$HELP_NS" get pod "$HELP_POD" -o jsonpath='{.spec.nodeName}{"\n"}{.status.conditions}{"\n"}{range .spec.volumes[*]}{.name}{"\t"}{.persistentVolumeClaim.claimName}{"\n"}{end}'
kubectl -n "$HELP_NS" describe pod "$HELP_POD"
kubectl -n "$HELP_NS" get pvc "$HELP_PVC"
kubectl -n "$HELP_NS" describe pvc "$HELP_PVC"

Use a claim from the actual Pod, not a similarly named claim elsewhere. Preserve event timestamps and the Pod UID in the incident record.

Inspect · Read the referenced storage policy

HELP_STORAGE_CLASS='REPLACE_WITH_ACTUAL_STORAGECLASS'
kubectl get storageclass "$HELP_STORAGE_CLASS" -o yaml

Inspect provisioner, binding mode, allowed topology, and reclaim policy. If no class is assigned, stop and inspect that condition instead of inventing a class name. Provider parameters can reveal internal infrastructure details.

2. Diagnose the constraint before relaxing it

Scheduling depends on declared requests and placement rules, not simply the CPU percentage currently visible on a node. PVC matching also considers more than free gigabytes. Read the requested class, access modes, volume mode, capacity, and any selector together with the actual driver events.

Choose the next step from evidence
What you observe	What it suggests	Next step
FailedScheduling identifies insufficient resources, an untolerated taint, or incompatible affinity.	The scheduler cannot find an eligible node under the requested constraints.	Have the workload and platform owners compare requests with allocatable capacity and intended placement. Correct a mistaken constraint or provide suitable capacity; do not remove isolation rules merely to make the Pod fit.
A Pending claim uses WaitForFirstConsumer and events await a consumer.	Delayed binding may be working as designed to honor topology.	Investigate the consuming Pod's scheduling constraints. Do not force-bind the claim. Using spec.nodeName bypasses the scheduler and can block this binding workflow.
Claim events report provisioning failure or a missing provisioner.	The storage driver, provider access, quota, or requested storage parameters need attention.	Escalate the exact event and class to the storage owner. Repair the approved provisioner or quota path; a new empty claim does not recover existing data.
The claim is Bound, but Pod events show attach or mount failure.	Binding succeeded; a later storage stage failed.	Review the driver-specific node, topology, attachment, and mount evidence. Do not force-detach a volume that another workload may still be writing.

3. Protect the data while correcting the deployment

Approve the smallest change that addresses the documented constraint. Changing an immutable claim field may require a planned migration rather than an in-place edit; confirm backups, restore procedure, data ownership, and driver capabilities first. StorageClass changes do not retroactively redesign already provisioned volumes.

Record the original workload and storage configuration. Roll back a placement or request change through its controller when compatible. For storage changes, rollback may require restoring data, not simply restoring YAML. Under a Delete reclaim policy, removing a claim can ultimately remove its backing storage, making casual recreation especially dangerous.

Verify the fix

Observe Pod scheduling, claim binding, successful attach/mount events, and readiness as separate milestones.
Have the application owner verify expected existing data and normal application behavior without introducing a destructive write test.
Check for recurring provisioning or mount errors. Confirm the approved placement remains correct rather than celebrating a Pod scheduled onto an unintended node.

Record the evidence, approved change, result, and rollback plan so the next administrator can follow your reasoning.

Avoid these shortcuts

Do not delete PVCs/PVs, remove protection finalizers, or force-detach storage as a generic fix.
Do not set spec.nodeName to bypass scheduling for WaitForFirstConsumer.
Do not promise that Bound, Running, or a restored manifest proves application data is intact.

Primary sources and version checks

Check the documentation for your installed release. Provider, runtime, CNI, storage-driver, and distribution details can differ.