Kubernetes - pod has unbound immediate PersistentVolumeClaims
The mentioned error can be caused for multiple reasons - below are few options which I encountered.
Example 1
The persistentvolume-controller
has failed to find a PV
with a capacity size which is equal or higher then the value that was specified in the PVC
.
So if we take this example:
# PVC
resources:
requests:
storage: 3Gi
# PV
capacity:
storage: 10Gi
So:
If PV capacity >= PVC capacity
then PVC should be bound to PV.
if Not then we'll get the unbound immediate PersistentVolumeClaims
error in the pod level and no volume plugin matched name
when describing the PVC.
Example 2
The number of PVC is higher then the PV.
For example if only one PV is created (or the others were deleted):
$ kubectl get pv
NAME CAPACITY ACCESS MODES RECLAIM POLICY STATUS CLAIM STORAGECLASS REASON AGE
mongo-local-pv 50Gi RWO Retain Bound default/mongo-persistent-storage-mongo-0 local-storage 106m
We could see that some workloads (Pods or Stateful sets) will be stuck on pending:
$ kubectl get pods
NAME READY STATUS RESTARTS AGE
mongo-0 2/2 Running 0 3m38s
mongo-1 0/2 Pending 0 3m23s
$ kubectl get pvc
NAME STATUS VOLUME CAPACITY ACCESS MODES STORAGECLASS AGE
mongo-persistent-storage-mongo-0 Bound mongo-local-pv 50Gi RWO local-storage 80m
mongo-persistent-storage-mongo-1 Pending local-storage 45m
We'll get the mentioned error on the pending resources.
Example 3
If the scheduler failed to match a node to the PV.
When using local volumes the nodeAffinity
of the PV is required and should be a value of an existing node in the cluster:
apiVersion: v1
kind: PersistentVolume
metadata:
name: local-mongo-pv
.
.
nodeAffinity:
required:
nodeSelectorTerms:
- matchExpressions:
- key: kubernetes.io/hostname
operator: In
values:
- node-which-doesnt-exists # <----- Will lead to the error
Example 4
Old PV
s with the same name and different configuration were already exist on the cluster and the new PVC
is created according to them.
When working with local volume the administrator must perform manually clean up and set up the local volume again each time for reuse.
(*) This local static provisioner was created to help with the PV lifecycle.
PersistentVolumeClaims
will remain unbound indefinitely if a matching PersistentVolume
does not exist. The PersistentVolume
is matched with accessModes
and capacity
. In this case capacity
the PV is 10Gi
whereas PVC has capacity
of 3Gi
.
The capacity
in the PV needs to same as in the claim i.e 3Gi
to fix the unbound immediate PersistentVolumeClaims
issue.