How to Configure Kubernetes Persistent Volumes

How to Configure Kubernetes Persistent Volumes

Persistent Volumes (PVs) and Persistent Volume Claims (PVCs) provide durable storage for Kubernetes workloads. Unlike ephemeral container storage that disappears when a pod restarts, persistent volumes survive pod rescheduling and even cluster restarts. This guide covers configuring storage for stateful applications on your Breeze cluster.

Storage Concepts

• PersistentVolume (PV) — a piece of storage provisioned by an admin or dynamically by a StorageClass
• PersistentVolumeClaim (PVC) — a request for storage by a pod, which binds to an available PV
• StorageClass — defines how storage is dynamically provisioned (disk type, reclaim policy, etc.)

Creating a StorageClass

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: fast-ssd
provisioner: kubernetes.io/no-provisioner
volumeBindingMode: WaitForFirstConsumer
reclaimPolicy: Retain

For cloud or CSI-based provisioners, the StorageClass enables fully dynamic provisioning where PVs are created automatically when a PVC is submitted.

Manually Creating a PersistentVolume

For local storage on your Breeze nodes:

apiVersion: v1
kind: PersistentVolume
metadata:
  name: local-pv-node1
spec:
  capacity:
    storage: 50Gi
  volumeMode: Filesystem
  accessModes:
  - ReadWriteOnce
  persistentVolumeReclaimPolicy: Retain
  storageClassName: fast-ssd
  local:
    path: /mnt/data
  nodeAffinity:
    required:
      nodeSelectorTerms:
      - matchExpressions:
        - key: kubernetes.io/hostname
          operator: In
          values:
          - breeze-node-01

Creating a PersistentVolumeClaim

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: app-data-pvc
spec:
  accessModes:
  - ReadWriteOnce
  storageClassName: fast-ssd
  resources:
    requests:
      storage: 20Gi

Kubernetes matches this PVC to an available PV with sufficient capacity and a matching StorageClass.

Mounting a PVC in a Pod

apiVersion: v1
kind: Pod
metadata:
  name: app-with-storage
spec:
  containers:
  - name: app
    image: myapp:latest
    volumeMounts:
    - name: data
      mountPath: /app/data
  volumes:
  - name: data
    persistentVolumeClaim:
      claimName: app-data-pvc

Access Modes

• ReadWriteOnce (RWO) — single node can mount the volume read-write
• ReadOnlyMany (ROX) — many nodes can mount read-only
• ReadWriteMany (RWX) — many nodes can mount read-write (requires NFS or similar)

Reclaim Policies

• Retain — PV is kept after PVC deletion (manual cleanup required)
• Delete — PV and underlying storage are deleted when PVC is removed
• Recycle — deprecated; performs a basic scrub (rm -rf /volume/*)

Expanding Volumes

If the StorageClass has allowVolumeExpansion: true, you can resize a PVC:

kubectl patch pvc app-data-pvc -p '{"spec":{"resources":{"requests":{"storage":"50Gi"}}}}'

The expansion happens online for most CSI drivers. On your Breeze cluster, ensure the underlying storage supports dynamic expansion before relying on this feature.

Monitoring Storage

kubectl get pv
kubectl get pvc --all-namespaces
kubectl describe pv local-pv-node1

Keep an eye on PV status (Available, Bound, Released, Failed) to catch storage issues early.