A persistentVolumeClaim volume lets a pod use persistent storage by naming a PersistentVolumeClaim (PVC). Create the claim separately, then reference it in the pod’s `spec.volumes`. The pod does not refer directly to a PersistentVolume (PV): the claim is bound to one, and the pod’s container mounts the volume at a chosen path. section 10.1.1 section 10.2.2
The claim and the pod volume definition have different jobs:
- The PVC requests a minimum capacity and an access mode. It can name a StorageClass or use the cluster’s default. Kubernetes binds it to a matching PV or provisions a new one. section 10.1.1 section 10.2.1
- The pod’s `persistentVolumeClaim` definition needs a `claimName` matching the PVC’s name. Its optional `readOnly` field forces all mounts of that volume to be read-only. section 10.2.2
- A container uses `volumeMounts` to choose where the volume appears in its filesystem. The PVC’s lifecycle is typically separate from the pod’s, so replacing a pod need not mean replacing its claim. section 10.2.2 section 10.1.1
Listing 10.3 A pod using a persistentVolumeClaim volume
apiVersion: v1
kind: Pod
metadata:
name: quiz
spec:
volumes:
- name: quiz-data
persistentVolumeClaim: #1
claimName: quiz-data #1
containers:
- name: quiz-api
image: luksa/quiz-api:0.1
ports:
- name: http
containerPort: 8080
- name: mongo
image: mongo
volumeMounts: #2
- name: quiz-data #2
mountPath: /data/db #2
See the two references in one pod manifest: `claimName: quiz-data` selects the PVC, while the MongoDB container mounts the named pod volume at `/data/db`. section 10.2.2
Check the binding
After creating the pod, run `kubectl get pvc quiz-data` and `kubectl get pv`. In the worked example, both resources show `Bound`; the PVC reports a 1Gi volume and `ReadWriteOncePod` access. Whether binding waits for a pod depends on the StorageClass’s volume binding mode. section 10.2.2 section 10.2.5
This volume type can also reference a claim for a pre-provisioned, node-local PV. In a StatefulSet, each replica instead receives its own PVC from a template and remains associated with that claim when its pod is recreated. Neither the pod volume definition nor its `claimName` specifies how the underlying storage is provided. section 10.3.2 section 16.1.2 section 10.1.1
