Debug Kubernetes Storage: troubleshooting commands
13 commands in 3 groups: PV and PVC State, Mount Verification, Provisioner Debug. Click or tap any command to copy it. Official documentation: kubernetes.io.
Open in the interactive cheat sheet search, stars and every other section
PV and PVC State
Find PVCs stuck Pending/Lost and trace how PVs map to claims and StorageClasses.
kubectl get pods -o jsonpath='{range .items[*]}{.metadata.name}{":"}{.spec.volumes[*].persistentVolumeClaim.claimName}{"\n"}{end}'
Map every pod to the PVCs it mounts
kubectl get pv -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.status.phase}{"\t"}{.spec.claimRef.name}{"\n"}{end}'
Tab-separated mapping PV → phase → claim
kubectl get storageclass -o jsonpath='{.items[?(@.metadata.annotations.storageclass\.kubernetes\.io/is-default-class=="true")].metadata.name}'
Find the default StorageClass name
kubectl get pvc -A | grep -v Bound
Find non-Bound PVCs across the cluster
Mount Verification
Verify a volume is actually mounted inside the container with the right size, contents and write permission.
kubectl exec -it <pod> -- cat /proc/mounts
Full mount table inside the container
kubectl exec -it <pod> -- mount | grep <vol>
Verify a specific volume is mounted
kubectl exec -it <pod> -- stat <mount-path>
Inode and ownership details for a path
kubectl exec <pod> -- sh -c "touch <mount-path>/.write-test && rm <mount-path>/.write-test"
Verify write permission to a mounted volume
kubectl exec -it <pod> -- df -h
Disk space on all mounts to spot full volumes
kubectl exec -it <pod> -- ls -la <mount-path>
List mount path contents and permissions
Provisioner Debug
Look at CSI driver pods and provisioning events when PVCs do not get bound.
kubectl get events --field-selector=reason=ProvisioningFailed -A
Provisioning failure events across all namespaces
kubectl get pods -n kube-system -l app=csi
CSI driver pods (label selector varies by CSI implementation)
kubectl logs -n kube-system <csi-pod> -c csi-provisioner --tail=100
Provisioner sidecar logs (NotFound, Quota, Auth errors)