> ## Documentation Index
> Fetch the complete documentation index at: https://notes.kodekloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Persistent Storage Concepts Volumes Claims and Provisioners

> Explains Kubernetes persistent storage concepts including StorageClasses, PersistentVolumes, PersistentVolumeClaims, access modes, dynamic provisioning, reclaim policies, and guidance for choosing and troubleshooting storage for different workloads

Earlier we covered compute: how to architect the platform, size resources, isolate tenants, and govern usage. Now we shift to the second pillar of platform engineering: storage.

In this lesson you'll learn:

* How PersistentVolumeClaims (PVCs), PersistentVolumes (PVs), and StorageClasses relate.
* How Kubernetes provisions storage for workloads.
* The three access modes and which backends support them.
* How to match workload requirements to the right storage configuration.

Start with a problem

A startup ran PostgreSQL on Kubernetes without persistent volumes. During a routine cluster upgrade the node hosting PostgreSQL was drained. The pod restarted on a different node with an empty filesystem and six hours of customer transaction data were gone.

The postmortem had one finding in bold: pod storage is ephemeral by design, and we failed to configure persistent volumes.

This concept surprises people new to containers: when a pod is removed (crashes, evicted, or rescheduled), any data stored inside the container filesystem is lost. For example, a pod that had written 500 MB will restart as a fresh instance with 0 MB; the container-local writable layer is ephemeral and is removed with the container.

![A diagram titled "Containers Forget Everything" showing three states: an active pod with 500MB of local data, a failure state with a crashed/evicted pod, and a new pod instance that starts empty (0MB). The graphic illustrates that container-local data is lost when a pod crashes and is replaced.](https://mintcdn.com/kodekloud-c4ac6d9a/jFwNGqGMK4QeJs-g/images/Prep-Course-Certified-Cloud-Native-Platform-Engineering-CNPE/Platform-Architecture-and-Infrastructure/Persistent-Storage-Concepts-Volumes-Claims-and-Provisioners/pods-lose-local-data-on-crash.jpg?fit=max\&auto=format\&n=jFwNGqGMK4QeJs-g\&q=85\&s=3609572c596a23016266103ac0bf9635)

This behavior is by design. Containers are intended to be disposable, stateless, and replaceable. The container runtime keeps a writable layer on the node; when the container (or pod) is destroyed that layer is removed.

Stateless workloads—web servers, API gateways, serverless functions—do not usually need persistent data between restarts. Stateful workloads do:

![A slide titled "Containers Forget Everything" with three numbered cards: 01 Databases (PostgreSQL, MySQL), 02 Message Queues (Kafka, RabbitMQ), and 03 File Storage (uploads, logs).](https://mintcdn.com/kodekloud-c4ac6d9a/jFwNGqGMK4QeJs-g/images/Prep-Course-Certified-Cloud-Native-Platform-Engineering-CNPE/Platform-Architecture-and-Infrastructure/Persistent-Storage-Concepts-Volumes-Claims-and-Provisioners/containers-forget-everything-databases-queues-storage.jpg?fit=max\&auto=format\&n=jFwNGqGMK4QeJs-g\&q=85\&s=35662927f68c7c3b53b2a96fd4258850)

* Databases (PostgreSQL, MySQL) store critical business data.
* Message queues buffer messages in transit.
* File storage (user uploads, logs) needs to persist beyond a pod's lifetime.

If you run these without persistent storage, you are one pod restart away from data loss. Pod restarts happen during deployments, maintenance, autoscaling, and failures.

The solution is to attach external storage that outlives the pod. The pod can come and go while the data remains on a separate volume that a future pod can mount. Kubernetes provides a storage stack to accomplish this.

Kubernetes storage stack (what creates what)

The Kubernetes storage stack has three layers. Understanding which actor creates which resource is essential.

![A diagram titled "The Kubernetes Storage Stack" showing a Pod that mounts a volume at /data and uses a PersistentVolumeClaim (PVC). The PVC binds to a PersistentVolume (PV), which is provisioned by a StorageClass (provisioning template).](https://mintcdn.com/kodekloud-c4ac6d9a/jFwNGqGMK4QeJs-g/images/Prep-Course-Certified-Cloud-Native-Platform-Engineering-CNPE/Platform-Architecture-and-Infrastructure/Persistent-Storage-Concepts-Volumes-Claims-and-Provisioners/kubernetes-storage-pvc-pv-diagram.jpg?fit=max\&auto=format\&n=jFwNGqGMK4QeJs-g\&q=85\&s=904701532dd48b55bbd44b5ffdad44f0)

Bottom-up:

1. StorageClass
   * A StorageClass is a provisioning template. It specifies the CSI driver (provisioner) and provider-specific parameters (disk type, IOPS, encryption).
   * The platform team creates and manages StorageClasses. Think of it as the platform's storage menu.

2. PersistentVolume (PV)
   * A PV represents a real volume: a block device, network filesystem, or cloud volume.
   * PVs can be statically created by an admin or dynamically provisioned by a StorageClass when a PVC is requested (dynamic provisioning is common in cloud environments).

3. PersistentVolumeClaim (PVC)
   * A PVC is a developer’s request: it declares size, access mode, and which StorageClass to use.
   * Kubernetes matches a PVC to a PV or uses the StorageClass to dynamically create a PV. A PVC binds one-to-one to a PV; a Pod mounts the PVC and reads/writes data as usual. The data persists independently of the Pod lifecycle.

Analogy: StorageClass is the menu, PVC is your order, PV is the dish served, and the Pod eats it. The dish (data) remains even if the diner (pod) leaves.

Access modes

When you create a PVC you select an access mode. Access modes determine how many nodes can mount a volume and whether mounts are read-only or read-write. Choose an access mode based on your workload and the storage backend.

Use the table below to compare access modes and common backend support:

| Access Mode | What it means | Common backends | Typical use cases |
| - | - | - | - |
| ReadWriteOnce (RWO) | Mounted read-write by a single node at a time. Multiple pods on that same node may share it. | Cloud block storage (AWS EBS, GCE PD, Azure Disk) | Databases, single-replica StatefulSets |
| ReadOnlyMany (ROX) | Mounted read-only by many nodes simultaneously. | NFS, object mounted solutions, some distributed FS | Shared static content, many readers no writers |
| ReadWriteMany (RWX) | Mounted read-write by many nodes simultaneously. | NFS, Amazon EFS, Azure Files, GCP Filestore, GlusterFS | Shared uploads, log aggregation, multi-writer file workloads |

![An infographic titled "Access Modes: Who Can Mount?" comparing three storage access modes. It shows ReadWriteOnce (one node can mount read-write), ReadOnlyMany (many nodes read-only), and ReadWriteMany (many nodes read-write) with recommended use cases and storage types.](https://mintcdn.com/kodekloud-c4ac6d9a/jFwNGqGMK4QeJs-g/images/Prep-Course-Certified-Cloud-Native-Platform-Engineering-CNPE/Platform-Architecture-and-Infrastructure/Persistent-Storage-Concepts-Volumes-Claims-and-Provisioners/access-modes-who-can-mount.jpg?fit=max\&auto=format\&n=jFwNGqGMK4QeJs-g\&q=85\&s=e9f1486c0c87cc502a191b9bc6a5a51f)

Not all storage supports all modes—verify the CSI driver or provider capability. For example, standard cloud block volumes typically only support RWO.

PersistentVolumeClaim example

Below is a typical PVC requesting 10 Gi, using `ReadWriteOnce`. The `storageClassName` must match an existing StorageClass; otherwise the PVC will remain Pending.

```yaml theme={null}
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: postgres-data
spec:
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 10Gi
  storageClassName: fast-ssd
```

What happens when you apply a PVC?

1. Kubernetes looks up the requested StorageClass.
2. The StorageClass's provisioner (CSI driver) creates a volume if dynamic provisioning is enabled.
3. Kubernetes creates a PV object representing the provisioned volume.
4. The PV is bound to the PVC; the PVC status moves from Pending to Bound.

Troubleshooting a PVC stuck in Pending

* Run `kubectl describe pvc <name>` to inspect events.
* Common causes:
  * `storageClassName` typo or StorageClass not found.
  * Insufficient capacity in the backend.
  * Requested access mode not supported by the backend.
  * StorageClass `volumeBindingMode` set to `WaitForFirstConsumer` and no Pod has referenced the PVC yet.

If you leave `storageClassName` empty, Kubernetes will use the cluster’s default StorageClass (if one exists). If no default is configured and you omit the StorageClass, the PVC may remain `Pending`.

StorageClass example

StorageClasses are defined by the platform team and referenced by developers. The `provisioner` identifies the CSI driver; `parameters` are provider-specific; `reclaimPolicy` controls what happens to the backing storage when a PVC is deleted.

```yaml theme={null}
apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: fast-ssd
provisioner: ebs.csi.aws.com
parameters:
  type: gp3
  iops: "3000"
reclaimPolicy: Delete
volumeBindingMode: WaitForFirstConsumer
```

Important fields explained

* `provisioner`: CSI driver used to create volumes.
* `parameters`: Provider-specific tuning (disk type, IOPS, encryption).
* `reclaimPolicy`:
  * `Delete` — underlying storage is destroyed when the PVC is deleted (good for ephemeral workloads like CI caches).
  * `Retain` — underlying data is preserved (recommended for databases and irreplaceable data).
* `volumeBindingMode`:
  * `Immediate` — PV is created as soon as PVC is created.
  * `WaitForFirstConsumer` — PV creation is delayed until a Pod that uses the PVC is scheduled (prevents AZ/zone mismatches in multi-AZ clusters).

Choosing storage for workloads

Answer "What storage should I use?" by evaluating four dimensions: access mode, storage type (block vs file vs object), reclaim policy, and workload characteristics.

Use this quick-reference mapping:

| Workload | Access mode | Storage type | Reclaim policy | Notes |
| - | - | - | - | - |
| Databases | RWO | Fast SSD (block) | `Retain` | Single-writer patterns — ensure backups and HA |
| Shared files | RWX | NFS/EFS/Filesystem CSI | `Delete` or `Retain` | Multi-writer file access; consider performance implications |
| Static public assets | ROX (or object API) | Object store (S3/GCS) or mounted FS | N/A for object | Use object storage for public assets; mount only if necessary |
| Batch jobs / CI | RWO | Cheap disks (HDD or standard block) | `Delete` | Ephemeral data; cost-sensitive |

![A slide titled "Matching Workloads to Storage" showing four colored cards—Database, Shared Files, Static Content, and Batch Jobs—each listing recommended access modes, storage types, reclaim policies, and short usage notes.](https://mintcdn.com/kodekloud-c4ac6d9a/jFwNGqGMK4QeJs-g/images/Prep-Course-Certified-Cloud-Native-Platform-Engineering-CNPE/Platform-Architecture-and-Infrastructure/Persistent-Storage-Concepts-Volumes-Claims-and-Provisioners/matching-workloads-to-storage.jpg?fit=max\&auto=format\&n=jFwNGqGMK4QeJs-g\&q=85\&s=7242d1637e3072b9994bf993d9d8c117)

Practical naming guidance

Name StorageClasses by use case rather than by cloud provider (for example `fast-ssd`, `shared-nfs`, `bulk-hdd`). This helps developers choose the right class without hunting in docs, and it keeps your platform portable across clouds.

Five key takeaways

1. PVCs request storage; PVs provide it. Developers create PVCs; the platform team manages StorageClasses. Clear separation of responsibilities avoids operational mistakes.
2. Access modes determine mounting and sharing behavior. Verify backend capability before selecting an access mode.
3. StorageClasses abstract provider details; name them by use case to preserve portability and reduce cognitive load.
4. Match workload to storage: databases need fast SSDs + `Retain`; shared files need RWX-capable filesystems; batch jobs can use cheaper disks + `Delete`.
5. Storage decisions affect both performance and cost—consider access mode, type, reclaim policy, and backup strategy when designing your platform.

Using `reclaimPolicy: Delete` for critical data (databases, business records) can cause irreversible data loss when PVCs are removed. Use `Retain` for anything you cannot afford to lose and enforce backups.

> **[Watch Video](https://learn.kodekloud.com/user/courses/prep-course-certified-cloud-native-platform-engineer-cnpe/module/989346de-0207-4837-af11-bf456d188972/lesson/d2d5c77a-9d9f-4a6e-9eb5-b6023f7842c4)**


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.