Persistent storage in Kubernetes: PersistentVolumes, claims and StorageClasses

A container’s own filesystem disappears when the container is replaced. For data that must survive, such as database files and uploads, Kubernetes separates asking for storage from providing it:

• PersistentVolume (PV): a piece of real storage (a cloud disk, an NFS export, a Ceph volume) represented as a cluster object.
• PersistentVolumeClaim (PVC): a request by a user: “10 GiB, read-write, of this class”. Pods reference claims, never PVs directly.
• StorageClass: a recipe that tells a provisioner how to create PVs on demand. With dynamic provisioning you never write PVs by hand.

Step 1: see what storage the cluster offers

kubectl get storageclass
kubectl describe storageclass standard

A class marked (default) carries the annotation storageclass.kubernetes.io/is-default-class: "true" and is used when a claim does not name a class. If no class exists, an administrator has to install a CSI driver or create PVs manually.

Step 2: create a claim

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: data
  namespace: shop
spec:
  accessModes:
  - ReadWriteOnce
  storageClassName: standard
  resources:
    requests:
      storage: 10Gi

kubectl apply -f pvc.yaml
kubectl get pvc -n shop

The claim shows Pending until a matching volume exists and Bound once it is attached to one. With a class that uses volumeBindingMode: WaitForFirstConsumer, it stays Pending until a Pod uses it; that is expected, and it lets the volume be created in the same zone as the Pod.

Step 3: mount it in a Pod

apiVersion: v1
kind: Pod
metadata:
  name: data-test
  namespace: shop
spec:
  containers:
  - name: app
    image: busybox:1.36
    command: ["sh", "-c", "date >> /data/log.txt && sleep 3600"]
    volumeMounts:
    - name: data
      mountPath: /data
  volumes:
  - name: data
    persistentVolumeClaim:
      claimName: data

Delete and recreate the Pod, then run kubectl exec -n shop data-test -- cat /data/log.txt: the earlier lines are still there. For replicated stateful apps, use a StatefulSet with volumeClaimTemplates so that each replica gets its own claim.

Access modes

• ReadWriteOnce (RWO): read-write by a single node. Several Pods on that same node can still share it.
• ReadOnlyMany (ROX): read-only by many nodes.
• ReadWriteMany (RWX): read-write by many nodes; needs shared storage such as NFS or CephFS.
• ReadWriteOncePod (RWOP): read-write by exactly one Pod in the whole cluster; supported only for CSI volumes.

Access modes are used for matching claims to volumes. They do not enforce write protection once the storage is mounted, and a block-storage driver usually supports only RWO.

Reclaim policy: what happens on delete

• Delete: deleting the claim also deletes the PV and the underlying storage. This is the default for dynamically provisioned volumes when the StorageClass does not say otherwise.
• Retain: the PV and its data stay behind for manual cleanup or reuse.
• Recycle: deprecated; use dynamic provisioning instead.

Warning: with the Delete policy, kubectl delete pvc destroys the data. Before deleting, check the policy with kubectl get pv (column RECLAIM POLICY) and back up anything you need. To protect an existing volume, switch it to Retain first:

kubectl patch pv <pv-name> -p '{"spec":{"persistentVolumeReclaimPolicy":"Retain"}}'

Kubernetes also protects claims that are in use: a PVC that a Pod is still using is not removed until that Pod is gone, so a delete may appear to hang with the claim in Terminating.

Growing a volume

If the StorageClass has allowVolumeExpansion: true, edit the claim’s resources.requests.storage to a larger value and apply it. Shrinking is not supported.

Official documentation

• Persistent Volumes
• Storage Classes