Kubernetes local volumes: When and how to use them

Local volumes give pods direct access to node-local storage while remaining fully managed by Kubernetes. Unlike hostPath volumes, local volumes participate in the scheduler's topology awareness — Kubernetes knows which nodes have local volumes available and schedules pods accordingly.

When to use local volumes

Use a local volume when your workload needs the performance of directly attached storage and cannot tolerate the latency of network-backed storage. The most common use case is databases with high IOPS requirements such as etcd, Cassandra, or PostgreSQL, where network storage introduces unacceptable latency.

If your workload does not need node-local performance, use dynamic provisioning with a PVC and StorageClass instead. It is portable, scales automatically, and is easier to operate.

How this demo works

This demo uses hostPath as the underlying storage path for simplicity. In production, local volumes should be backed by dedicated block devices or separate disk partitions, not the host's general filesystem. Using the root filesystem as local volume backing in production can exhaust disk space and destabilise the node.

The demo creates: a StorageClass with no-provisioner, a manually created PV pointing to /opt/data on the node, a PVC that requests storage from that StorageClass, and a pod that mounts the PVC.

Step 1: Create the StorageClass

Local volumes do not support dynamic provisioning. The StorageClass is created with provisioner: kubernetes.io/no-provisioner and volumeBindingMode: WaitForFirstConsumer. The WaitForFirstConsumer mode delays PVC binding until a pod that uses it is scheduled, which allows the scheduler to factor in node constraints before committing the PVC to a specific PV.

1apiVersion: storage.k8s.io/v1
2kind: StorageClass
3metadata:
4  name: local-storage
5provisioner: kubernetes.io/no-provisioner
6volumeBindingMode: WaitForFirstConsumer

1kubectl create -f sc.yaml

Verify:

1kubectl get sc

Expected output:

1NAME            PROVISIONER                    VOLUMEBINDINGMODE
2local-storage   kubernetes.io/no-provisioner   WaitForFirstConsumer

Step 2: Create the PersistentVolume

1apiVersion: v1
2kind: PersistentVolume
3metadata:
4  name: demo-pv
5spec:
6  storageClassName: local-storage
7  capacity:
8    storage: 1Gi
9  accessModes:
10  - ReadWriteOnce
11  hostPath:
12    path: /opt/data
13  persistentVolumeReclaimPolicy: Retain
14  nodeAffinity:
15    required:
16      nodeSelectorTerms:
17      - matchExpressions:
18        - key: kubernetes.io/hostname
19          operator: In
20          values:
21          - <your-node-name>

Replace <your-node-name> with the name of the node where /opt/data exists. Run kubectl get nodes to find your node name.

1kubectl create -f pv.yaml

Step 3: Create the PersistentVolumeClaim

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

1kubectl create -f pvc.yaml

Check the PV and PVC status immediately after creation:

1kubectl get pv,pvc

Expected output at this point:

1NAME                      CAPACITY   ACCESS MODES   STATUS      STORAGECLASS
2persistentvolume/demo-pv  1Gi        RWO            Available   local-storage
3
4NAME                               STATUS    STORAGECLASS
5persistentvolumeclaim/demo-pvclaim Pending   local-storage

The PVC stays in Pending status because WaitForFirstConsumer delays binding until a pod is scheduled. This is expected and correct behaviour.

Step 4: 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

1kubectl create -f pod.yaml

Now check the PV and PVC status again:

1kubectl get pv,pvc

Expected output after the pod is scheduled:

1NAME                      CAPACITY   ACCESS MODES   STATUS   STORAGECLASS
2persistentvolume/demo-pv  1Gi        RWO            Bound    local-storage
3
4NAME                               STATUS   VOLUME    CAPACITY   STORAGECLASS
5persistentvolumeclaim/demo-pvclaim Bound    demo-pv   1Gi        local-storage

Both are now Bound. The binding happened when the scheduler assigned the pod to a node.

Check which node the pod is running on:

1kubectl get pods -o wide

Step 5: Write data and verify it on the node

Exec into the pod:

1kubectl exec -it task-pv-pod -- sh

Create a file:

1cd /usr/share/nginx/html
2echo "hello" >> index.html
3curl localhost

Expected output:

1hello

Exit the pod. On the node where the pod is running, the file is now visible at /opt/data/index.html.

Step 6: Verify data persists after pod deletion

Delete the pod:

1kubectl delete pod task-pv-pod --force --grace-period=0

Check the PV and PVC:

1kubectl get pv,pvc

Expected output:

1NAME                      STATUS   STORAGECLASS
2persistentvolume/demo-pv  Bound    local-storage
3
4NAME                               STATUS   STORAGECLASS
5persistentvolumeclaim/demo-pvclaim Bound    local-storage

Both remain. The data on disk is still at /opt/data/index.html on the node. The pod is gone but the storage objects and their data are independent of it.

Delete the PVC:

1kubectl delete persistentvolumeclaim/demo-pvclaim

Check the PV:

1kubectl get pv

Expected output:

1NAME       CAPACITY   ACCESS MODES   RECLAIM POLICY   STATUS
2demo-pv    1Gi        RWO            Retain           Released

Because the reclaim policy is Retain, the PV moves to Released status rather than being deleted. The data on disk is preserved. To reuse the PV it must be manually reclaimed.