Skip to content
Tutorials Center
My learning

Topics

Lesson 29 of 37 ยท Storage and Scaling

Persistent Volumes and Claims in OpenShift

Keep data beyond a pod's life: persistent volumes, persistent volume claims, access modes, reclaim policies, mounting storage and resizing, with runnable binding models.

A container's filesystem disappears with the container. Databases, uploads and queues need storage that survives restarts and moves with the workload. OpenShift provides it through two objects that split responsibilities: the PersistentVolume (PV) is a piece of real storage the cluster can use, and the PersistentVolumeClaim (PVC) is an application's request for storage. Developers write claims; the platform (or admin) supplies the volumes.

All oc commands and YAML are read-only examples; the Python stand-ins model how a claim finds a volume.

Claims

YAML
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: shop-db-data
  namespace: shop
spec:
  accessModes: ["ReadWriteOnce"]
  resources:
    requests:
      storage: 20Gi
  storageClassName: gp3-csi     # omit to use the default class
Terminal
oc apply -f pvc.yaml
oc get pvc

A claim is namespaced; a PV is cluster-wide. When a suitable volume is found (or created dynamically, see storage classes), the claim's status becomes Bound. A claim stays Pending while no volume matches.

Mounting a claim in a pod

YAML
spec:
  containers:
    - name: postgres
      image: registry.example.com/postgres:16
      volumeMounts:
        - name: data
          mountPath: /var/lib/postgresql/data
  volumes:
    - name: data
      persistentVolumeClaim:
        claimName: shop-db-data

From the CLI: oc set volume deployment/shop-db --add --name=data --type=pvc --claim-name=shop-db-data --mount-path=/var/lib/postgresql/data. Remember SCCs: the random UID must be able to write to the volume. OpenShift sets the volume's group through fsGroup taken from the project range, which normally makes it writable.

Access modes

Mode Short Meaning
ReadWriteOnce RWO One node can mount it read-write (many pods on that node)
ReadWriteOncePod RWOP Exactly one pod
ReadOnlyMany ROX Many nodes, read-only
ReadWriteMany RWX Many nodes, read-write (needs shared filesystem such as NFS, CephFS)

Block storage (cloud disks, Ceph RBD) is usually RWO. Shared file storage is required when several replicas write the same files. A Deployment with 3 replicas sharing an RWO claim may leave pods stuck scheduling on different nodes, which is a classic surprise; use a StatefulSet with volumeClaimTemplates for per-pod volumes instead.

Volume modes, reclaim policies and phases

  • Filesystem (default) mounts a formatted file system; Block gives a raw device.
  • Reclaim policy says what happens to the PV when its claim is deleted: Delete removes the volume and its data (typical for dynamic provisioning), Retain keeps it for manual recovery.
  • PV phases: Available, Bound, Released (claim gone, data still there), Failed.
Terminal
oc get pv
oc describe pv pvc-1f2e3d
oc patch pv pvc-1f2e3d -p '{"spec":{"persistentVolumeReclaimPolicy":"Retain"}}'

Set Retain before deleting a claim whose data you may need.

How a claim finds a volume

For pre-created volumes the binder picks the smallest available PV that satisfies the class, access mode and size. The stand-in reproduces that rule.

Python Stand-in: PVC to PV binding

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Note that db asked for 8Gi but received the 10Gi volume: a claim can get more than it requested when binding to existing PVs.

Resizing

If the storage class has allowVolumeExpansion: true, edit the claim and raise the request. You can only grow a volume, never shrink it:

Terminal
oc patch pvc shop-db-data -p '{"spec":{"resources":{"requests":{"storage":"40Gi"}}}}'
oc get pvc shop-db-data -w

Most CSI drivers expand the file system online; some need a pod restart. Watch the claim's conditions for FileSystemResizePending.

Capacity planning model

Python Stand-in: when will the volume fill up?

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

flowchart LR
  Pod["Pod"] --> PVC["PVC (request: 20Gi RWO)"]
  PVC -- "bound" --> PV["PV (20Gi disk)"]
  PV --> Disk[("Cloud disk / Ceph / NFS")]

Pods use claims; claims bind to volumes; volumes map to real storage.

Common problems

  • PVC Pending: no matching PV or default storage class, wrong class name, or unsupported access mode.
  • Pod stuck ContainerCreating with a volume attach error: the disk is still attached to another node (an RWO volume after a node failure).
  • Permission denied on write: image ignores the arbitrary UID; fix directory ownership or use the project's fsGroup.
  • Data lost after delete: reclaim policy was Delete.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Who normally creates a PersistentVolumeClaim?

    Developers request storage with claims; PVs are supplied by admins or dynamic provisioners.
  2. 2. Which access mode allows many nodes to write the same volume?

    RWX needs shared file storage, for example NFS or CephFS.
  3. 3. A PV with reclaim policy Delete loses what when its claim is removed?

    Delete removes the underlying storage along with the PV; use Retain to keep data.
  4. 4. Can you shrink a bound PVC from 40Gi to 20Gi?

    Kubernetes supports expansion only; restore into a smaller new claim instead.

Summary

  • PVs are cluster storage; PVCs are namespaced requests that bind to PVs.
  • Choose the access mode by workload: RWO for databases, RWX for shared files.
  • Reclaim policy decides the fate of data after claim deletion.
  • Claims can grow if the class allows expansion.
  • Diagnose Pending claims and attach errors with oc describe and events.

Next: Storage classes and dynamic provisioning