Kubernetes Persistent Volumes, PVCs and dynamic provisioning explained

Pods are ephemeral. When a pod is deleted and recreated, any data written to its local filesystem is gone. PersistentVolumes solve this by providing storage that exists independently of the pod lifecycle. A pod can be deleted, rescheduled to a different node, and reconnected to the same storage when it comes back up.

Core concepts

PersistentVolume (PV)

A PersistentVolume is a storage resource provisioned in the cluster. It is an abstraction of the underlying storage backend, whether that is a local disk, an NFS share, a cloud block device, or any other storage system. PVs are cluster-scoped objects, not tied to any namespace.

PersistentVolumeClaim (PVC)

A PersistentVolumeClaim is a request for storage made by a user or workload. The user specifies how much storage they need, which access mode they require, and optionally which StorageClass to use. Kubernetes matches the PVC to an available PV that satisfies those requirements and binds them together.

The binding lifecycle

The control plane continuously watches for unbound PVCs and tries to find a matching PV. Once a match is found, the PVC moves to Bound status and the PV is reserved exclusively for that PVC. The PVC and PV have their own lifecycle separate from any pod. Deleting a pod does not delete the PVC or PV.

Access modes

Not all storage backends support all access modes. Check your storage provider's documentation.

Reclaim policies

The Recycle policy is deprecated and should not be used.

Static vs dynamic provisioning

Static provisioning: an admin creates PVs manually before any PVC exists. The PVC binds to a matching manually created PV.

Dynamic provisioning: a StorageClass with a provisioner automatically creates a PV whenever a PVC requests one. The developer only specifies what they need. The cluster handles the rest.

Static provisioning: working example

Create the PersistentVolume

Before running this on a node, create the directory and an index.html file:

1mkdir -p /mnt/data
2echo "hello" > /mnt/data/index.html

1apiVersion: v1
2kind: PersistentVolume
3metadata:
4  name: demo-pv
5spec:
6  storageClassName: manual
7  capacity:
8    storage: 3Gi
9  accessModes:
10  - ReadWriteOnce
11  hostPath:
12    path: /mnt/data
13  persistentVolumeReclaimPolicy: Retain

1kubectl create -f pv.yaml

Create the PersistentVolumeClaim

1apiVersion: v1
2kind: PersistentVolumeClaim
3metadata:
4  name: demo-pvclaim
5spec:
6  storageClassName: manual
7  accessModes:
8  - ReadWriteOnce
9  resources:
10    requests:
11      storage: 3Gi

1kubectl create -f pvc.yaml

Verify both are bound:

1kubectl get pv,pvc

Expected output:

1NAME                       CAPACITY   ACCESS MODES   RECLAIM POLICY   STATUS   STORAGECLASS
2persistentvolume/demo-pv   3Gi        RWO            Retain           Bound    manual
3
4NAME                              STATUS   VOLUME    CAPACITY   ACCESS MODES   STORAGECLASS
5persistentvolumeclaim/demo-pvclaim   Bound    demo-pv   3Gi        RWO            manual

Create a pod that uses the PVC

1apiVersion: v1
2kind: Pod
3metadata:
4  name: task-pv-pod
5spec:
6  volumes:
7  - name: pv-volume
8    persistentVolumeClaim:
9      claimName: demo-pvclaim
10  containers:
11  - name: nginx
12    image: nginx
13    volumeMounts:
14    - mountPath: /usr/share/nginx/html
15      name: pv-volume
16  nodeName: <node-where-data-exists>

1kubectl create -f pod.yaml
2kubectl get pods

Exec into the pod and verify the data:

1kubectl exec -it task-pv-pod -- sh
2cd /usr/share/nginx/html
3cat index.html

Expected output:

1hello

1curl localhost

Expected output:

1hello

Exit and delete the pod:

1kubectl delete pod task-pv-pod

Verify the PV and PVC still exist after the pod is deleted:

1kubectl get pv,pvc

Both remain. Because the reclaim policy is Retain, even deleting the PVC will not delete the PV or the data on disk. These must be removed manually.

Dynamic provisioning: working example

Dynamic provisioning requires a StorageClass with a provisioner. This example uses local-path-provisioner from Rancher, which works on any cluster including Minikube and kubeadm setups.

Install local-path-provisioner

Check the latest release on GitHub and replace the version number in the command below:

1kubectl apply -f https://raw.githubusercontent.com/rancher/local-path-provisioner/v0.0.26/deploy/local-path-storage.yaml

This creates the namespace, service account, roles, deployment, and StorageClass automatically.

Verify the StorageClass exists:

1kubectl get sc

Expected output:

1NAME         PROVISIONER             RECLAIMPOLICY   VOLUMEBINDINGMODE
2local-path   rancher.io/local-path   Delete          WaitForFirstConsumer

Create a StatefulSet with volumeClaimTemplates

The volumeClaimTemplates section tells Kubernetes to automatically create a PVC for each replica. The StorageClass then automatically creates a matching PV.

1apiVersion: apps/v1
2kind: StatefulSet
3metadata:
4  name: local-test
5spec:
6  replicas: 3
7  selector:
8    matchLabels:
9      app: local-test
10  template:
11    metadata:
12      labels:
13        app: local-test
14    spec:
15      containers:
16      - name: busybox
17        image: busybox
18        command: ["sh", "-c", "while true; do sleep 3600; done"]
19        volumeMounts:
20        - mountPath: /usr/test-pod
21          name: local-vol
22  volumeClaimTemplates:
23  - metadata:
24      name: local-vol
25    spec:
26      accessModes: ["ReadWriteOnce"]
27      storageClassName: local-path
28      resources:
29        requests:
30          storage: 128Mi

1kubectl create -f statefulset.yaml

Watch the PVCs and PVs being created automatically:

1kubectl get pv,pvc

Expected output once all three replicas are running:

1NAME                                                        CAPACITY   STATUS   STORAGECLASS
2persistentvolume/pvc-abc123-local-test-0                   128Mi      Bound    local-path
3persistentvolume/pvc-def456-local-test-1                   128Mi      Bound    local-path
4persistentvolume/pvc-ghi789-local-test-2                   128Mi      Bound    local-path
5
6NAME                                             STATUS   VOLUME                     STORAGECLASS
7persistentvolumeclaim/local-vol-local-test-0    Bound    pvc-abc123-local-test-0    local-path
8persistentvolumeclaim/local-vol-local-test-1    Bound    pvc-def456-local-test-1    local-path
9persistentvolumeclaim/local-vol-local-test-2    Bound    pvc-ghi789-local-test-2    local-path

Exec into a pod and create a file:

1kubectl exec -it local-test-0 -- sh
2cd /usr/test-pod
3touch test
4exit

Check where the pod is running:

1kubectl get pods -o wide

On that node, the file will be at /opt/local-path-provisioner/. The directory name matches the PVC name.

Demonstrate the Delete reclaim policy

Scale down to 2 replicas:

1kubectl edit statefulset local-test

Change replicas: 3 to replicas: 2. The pod is deleted but the PVC and PV remain:

1kubectl get pv,pvc

Now delete the PVC manually:

1kubectl delete persistentvolumeclaim/local-vol-local-test-2

Because the reclaim policy is Delete, the PV is deleted automatically along with the data on disk.

Static vs dynamic: when to use each

For most workloads, dynamic provisioning is the right choice. It removes the operational burden of pre-provisioning storage and scales automatically with your workloads.

For NFS-backed storage that is accessible from multiple nodes, see the NFS PersistentVolume guide.

For high-performance node-local storage, see the local volumes guide.