Persistent Volumes (PV)

Persistent Volumes (PV)

Containers in Kubernetes are stateless by design — when a pod is deleted, any data written inside the container is gone. PersistentVolumes (PV) provide storage that outlives pods. A PV is a cluster-level storage resource provisioned by an administrator (or automatically via StorageClass). It abstracts the underlying storage system (NFS, local disk, AWS EBS, GCE PD) behind a uniform Kubernetes API. Applications claim storage via PersistentVolumeClaims (PVC), which bind to available PVs.

The storage problem in Kubernetes

Without PersistentVolumes:
  Pod (database) → writes data to /var/lib/mysql (container layer)
  Pod crashes, rescheduled on different node
  → New pod starts with empty /var/lib/mysql  ← ALL DATA LOST

With PersistentVolumes:
  PV (NFS/EBS/local disk) → mounted into pod at /var/lib/mysql
  Pod crashes, rescheduled on different node
  → New pod mounts the SAME PV  ← Data survives

  PersistentVolume (PV)         ← Cluster-level storage resource
      |
      | bound to
      v
  PersistentVolumeClaim (PVC)   ← Namespace-level storage request
      |
      | mounted into
      v
  Pod spec: volumeMounts

PV concepts and access modes

Creating a PersistentVolume

nano local-pv.yaml

local-pv.yaml — uses a local host directory

apiVersion: v1
kind: PersistentVolume
metadata:
  name: local-pv-01
spec:
  capacity:
    storage: 10Gi
  accessModes:
    - ReadWriteOnce
  persistentVolumeReclaimPolicy: Retain   # Keep data after PVC deleted
  storageClassName: local-storage
  local:
    path: /mnt/data/pv01              # Directory on the worker node
  nodeAffinity:                         # Local PVs must specify which node
    required:
      nodeSelectorTerms:
        - matchExpressions:
            - key: kubernetes.io/hostname
              operator: In
              values:
                - k8s-worker-01

# Create the directory on the worker node first:
sudo mkdir -p /mnt/data/pv01

# Apply the PV manifest:
kubectl apply -f local-pv.yaml

# Check PV status:
kubectl get pv

kubectl get pv output

NAME           CAPACITY   ACCESS MODES   RECLAIM POLICY   STATUS      CLAIM   STORAGECLASS    AGE
local-pv-01    10Gi       RWO            Retain           Available           local-storage   30s
# STATUS = Available means no PVC has claimed it yet

StorageClasses and dynamic provisioning

# StorageClasses provision PVs automatically when a PVC requests them
# No need to pre-create PVs manually

# List available StorageClasses:
kubectl get storageclass

StorageClasses on a cloud cluster

NAME                 PROVISIONER             RECLAIMPOLICY   VOLUMEBINDINGMODE      AGE
standard (default)   kubernetes.io/gce-pd    Delete          Immediate              45d
standard-rwo         pd.csi.storage.gke.io   Delete          WaitForFirstConsumer   45d

# On k3s, use the built-in local-path StorageClass:
kubectl get storageclass
# NAME                   PROVISIONER
# local-path (default)   rancher.io/local-path

# When a PVC requests storage from "local-path", k3s
# automatically creates a directory on the node and a PV for it

Conclusion

The persistentVolumeReclaimPolicy is critical: Retain keeps data on the PV after the PVC is deleted (you must manually reclaim it), while Delete removes the underlying storage when the PVC is deleted. For databases, always use Retain to prevent accidental data loss when someone deletes a PVC. On cloud clusters, use the default StorageClass with dynamic provisioning — the cloud controller automatically provisions and attaches the right disk type for your PVC.