Kubernetes Persistent Volumes Explained

Kubernetes persistent volumes (PVs) are cluster-wide storage resources that exist independently of any pod, providing a way for applications to retain data across pod restarts, rescheduling, and deletions. They are the fundamental mechanism for stateful workloads in Kubernetes, abstracting the details of underlying storage systems from the applications that consume them.

Background: Why Stateful Apps Need Persistent Volumes

Kubernetes was originally designed with stateless applications in mind—pods are ephemeral, can be killed and recreated at any time, and their filesystems are wiped when they die. This works fine for web servers or API backends that can lose all local state, but fails for databases, file stores, and message queues that must retain data. Before persistent volumes, developers had to use hostPath volumes (which tie a pod to a specific node) or external storage mounted via plugins, both of which were brittle and hard to manage at scale. Persistent volumes solve this by decoupling storage from the pod lifecycle, allowing data to survive even if the entire cluster is torn down and rebuilt.

How Kubernetes Persistent Volumes Work

The core concepts are the PersistentVolume (PV), the PersistentVolumeClaim (PVC), and the StorageClass. A PV is a piece of storage in the cluster, provisioned by an administrator or dynamically by a StorageClass. A PVC is a request for storage by a user, specifying size, access mode, and optionally a storage class. The Kubernetes control plane binds a PVC to a PV that satisfies its requirements, and then a pod can mount that PVC as a volume. The lifecycle is:

• Provisioning: A PV is created either statically (admin pre-creates it) or dynamically (a StorageClass creates it on demand when a PVC is submitted).
• Binding: The control plane finds a PV that matches the PVC’s requested size and access mode, and binds them. The binding is one-to-one; a PV can only be bound to one PVC at a time.
• Using: A pod references the PVC in its volume section, and Kubernetes mounts the underlying storage into the container’s filesystem.
• Reclaiming: When a PVC is deleted, the PV enters a reclaim policy phase: Retain (data is kept for manual recovery), Delete (storage is deleted automatically), or Recycle (deprecated, but historically erased data and made the PV available again).

PersistentVolumeClaims: How Applications Request Storage

A PVC is a Kubernetes API object that represents a request for storage. It specifies the desired size (e.g., 10Gi), an access mode (ReadWriteOnce, ReadOnlyMany, ReadWriteMany), and optionally a StorageClass name. The access modes define how many nodes can mount the volume simultaneously: ReadWriteOnce (RWO) allows a single node to read/write, ReadOnlyMany (ROX) allows multiple nodes to read, and ReadWriteMany (RWX) allows multiple nodes to read/write. Not all storage backends support all modes; for example, AWS EBS supports only RWO, while NFS supports RWX. When a PVC is created, Kubernetes attempts to bind it to a PV. If no matching PV exists and a StorageClass is specified, the dynamic provisioner creates a new PV on the fly. The PVC then remains bound to that PV until the PVC is deleted, even if the pod using it is removed.

StorageClasses: Dynamic Provisioning

StorageClasses allow cluster administrators to define different tiers of storage (e.g., fast SSD, slow HDD, network-backed) and let users request them by name. A StorageClass contains a provisioner (the plugin that creates the actual storage, such as kubernetes.io/aws-ebs, nfs.csi.k8s.io, or a cloud-specific CSI driver), parameters for that provisioner (like type: gp3 for AWS), and a reclaim policy. When a PVC specifies a StorageClass, the provisioner automatically creates the underlying storage (e.g., an EBS volume or an NFS share) and a PV to represent it. This is the most common way to use persistent volumes in cloud environments, because it eliminates the need for an administrator to manually create storage ahead of time. A default StorageClass can be marked with the annotation storageclass.kubernetes.io/is-default-class: “true”, so that PVCs without an explicit class use it.

Using Persistent Volumes in Pods

To use a PVC in a pod, you reference it in the pod’s volumes section and then mount it into a container. Here’s a simple example:

apiVersion: v1
kind: Pod
metadata:
  name: my-pod
spec:
  containers:
  - name: app
    image: nginx
    volumeMounts:
    - name: data
      mountPath: /data
  volumes:
  - name: data
    persistentVolumeClaim:
      claimName: my-pvc

When the pod starts, Kubernetes resolves the PVC to its bound PV and mounts the underlying storage at /data. The pod can then read and write files there, and those files persist even if the pod is deleted and recreated. Note that the PVC must exist in the same namespace as the pod. Also, if the PVC is not bound (e.g., no PV available and no dynamic provisioning), the pod will remain in Pending state until the binding succeeds.

Common Issues and Best Practices

• Stuck in Pending: A PVC that stays Pending usually means no PV matches its requirements and no StorageClass can provision it. Check the PVC events with kubectl describe pvc to see the error.
• Access mode mismatch: If you request RWX but your storage backend only supports RWO, the binding will fail. Choose a backend that supports the mode your application needs.
• Reclaim policy confusion: If you delete a PVC with a Retain policy, the PV remains but is released; you must manually delete it or reuse it. With Delete, the underlying storage is automatically removed—be careful with production data.
• Volume expansion: Not all StorageClasses support online expansion. If you need to grow a volume, check the allowVolumeExpansion field in the StorageClass.
• Node affinity: Some PVs (like local volumes) are tied to a specific node. If the node goes down, the data is inaccessible. Use node affinity or a network-backed storage for high availability.

Persistent Volumes vs. Other Storage Options

Persistent volumes are the right choice when you need durable, cluster-wide storage that outlives pods. For temporary scratch space, you can use emptyDir, which is deleted when the pod is removed. For configuration files, you can use ConfigMaps and Secrets, which are mounted as read-only volumes but are not persistent in the PV sense. hostPath volumes are a simple way to access a node’s filesystem, but they are not portable across nodes and are generally discouraged for production. For stateful applications like databases, a StatefulSet combined with a PVC template (volumeClaimTemplates) is the recommended pattern, as it creates a unique PVC for each replica and ensures stable network identities.

Frequently Asked Questions

What is the difference between a PV and a PVC?

A PersistentVolume (PV) is the actual storage resource in the cluster, like a 10Gi EBS volume or an NFS share. A PersistentVolumeClaim (PVC) is a request for that storage, specifying size and access mode. The PV is the supply, the PVC is the demand; Kubernetes matches them together.

Can I share a persistent volume across multiple pods?

Yes, if the underlying storage supports ReadWriteMany (RWX) or ReadOnlyMany (ROX). For example, NFS and CephFS support RWX, allowing multiple pods on different nodes to access the same volume concurrently. However, you must ensure the application itself can handle concurrent access to the same files (e.g., file locking).

What happens to my data when I delete a pod that uses a PVC?

The PVC and the PV remain intact. The pod’s deletion does not affect the persistent volume. The data is still there, and you can create a new pod that references the same PVC to access it again. Only when you delete the PVC does the reclaim policy take effect.

How do I increase the size of a persistent volume?

If the StorageClass has allowVolumeExpansion set to true, you can edit the PVC’s spec.resources.requests.storage to a larger size and apply it. Kubernetes will expand the underlying volume. For many cloud providers, this can be done online without downtime, but it depends on the storage driver.

Why is my PVC stuck in Pending state?

This usually means no PV matches your PVC’s size and access mode, and no StorageClass is available to dynamically provision one. Check the events with kubectl describe pvc to see the exact error. Common causes include: no StorageClass specified and no default exists, the StorageClass name is misspelled, or the cloud provider quota is exhausted.

Can I use a local disk on a node as a persistent volume?

Yes, Kubernetes supports local persistent volumes (using the local volume plugin or CSI drivers). These are useful for high-performance applications that need low latency, but they are tied to a specific node. If the node fails, the data may be lost unless you have replication at the application level. For production, network-backed storage is often safer.

Related

• Amps to kW Calculator: Convert Electrical Power
• Deer Water Heater Calculator: Estimate Tank Size
• Electric Water Heater Calculator: What It Can Estimate