Chapter 10: Persisting data with PersistentVolumes

Introduction

This chapter introduction previews persistent storage topics, including PersistentVolumes, provisioning, snapshots, and node-local versus network-attached storage.

10.1 Introducing persistent storage in Kubernetes

The section explains how Kubernetes lets applications request persistent storage without specifying the cluster’s storage technology or a particular volume.

• Storage requests without infrastructure details: Explain why an application typically specifies the properties it needs from persistent storage rather than a particular volume, and how the cluster meets that request.
  Why it matters: This separation lets applications request storage without depending on a cluster’s particular storage setup.

Key terms: persistent storage, volume, provisions

10.1.1 Introducing PersistentVolumeClaims and PersistentVolumes

This section explains how PersistentVolumes, PersistentVolumeClaims, and StorageClasses connect pods to persistent storage, including how pods mount and share a claimed volume.

• Volume claims and ownership: Explain the relationship between a PersistentVolume, a PersistentVolumeClaim, and a pod, and why the claim lets a user retain the volume when a pod is deleted.
  Why it matters: This distinction explains why replacing a pod need not mean giving up its storage.
• Storage classes and portability: Describe what a StorageClass specifies and how choosing a consistently named class in a claim can make claim manifests portable across clusters.
  Why it matters: A claim can request a kind of storage without embedding details of each cluster’s infrastructure.
• CSI driver storage roles: Describe the roles of a CSI driver’s controller and per-node component in providing PersistentVolume storage.
  Why it matters: CSI drivers explain how Kubernetes can work with different underlying storage systems.
• Claim-based pod volume mounting: Trace how a pod's persistentVolumeClaim volume definition leads to underlying storage being mounted in its container without putting infrastructure details in the pod definition.
  Why it matters: It shows how an application pod uses persistent storage without carrying storage-system connection details.
• Shared claims across pods: Explain how multiple pods can use one claimed volume and what determines whether those pods can run on different nodes.
  Why it matters: Sharing a claim does not by itself guarantee that pods can use its volume from different nodes.

Key terms: PersistentVolume, PersistentVolumeClaim, StorageClass, provisioner, CSI driver, controller component, per-node component, persistentVolumeClaim volume type, storage technology

10.1.2 Dynamic vs. static provisioning of PersistentVolumes

This section contrasts on-demand and administrator-prepared PersistentVolumes, explaining how claims obtain them and what happens as pods and claims come and go.

• Dynamic volume provisioning: Explain how a PersistentVolumeClaim triggers creation of a PersistentVolume and its underlying storage when dynamic provisioning is configured, and describe what usually happens when the claim is deleted.
  Why it matters: It explains why users can request persistent storage without an administrator preparing each volume in advance.
• Static volume claiming: Trace how an administrator-prepared volume is claimed and bound, then describe what remains for the administrator after the claim is deleted.
  Why it matters: It distinguishes claiming existing storage from creating storage on demand, especially at cleanup time.
• Claim and pod lifetimes: Describe how pods use a claimed PersistentVolume and why ending the pods does not itself end the claim or volume.
  Why it matters: It prevents confusing a pod's lifetime with the lifetime of the storage it uses.

Key terms: dynamic provisioning, CSI driver, CSIDriver resource, StorageClass, PersistentVolumeClaim, PersistentVolume, static provisioning, bound, released, pod

10.2 Dynamically provisioning a PersistentVolume

The section explains why the quiz Pod needs persistent storage and identifies a PersistentVolumeClaim as the first step toward using a dynamically provisioned PersistentVolume.

• Persistent storage for quiz responses: Explain why the quiz Pod’s emptyDir volume is unsuitable for storing responses and state what must be created first to use a dynamically provisioned PersistentVolume.
  Why it matters: The quiz needs storage that keeps responses when its Pod is replaced.

Key terms: emptyDir volume, PersistentVolumeClaim, dynamically provisioned PersistentVolume

10.2.1 Creating a PersistentVolumeClaim

Shows how to define a PersistentVolumeClaim’s storage requirements, create it from a manifest, and interpret its initial status.

• Storage class selection: Explain that a claim can omit storageClassName when the cluster has a default StorageClass, or specify a StorageClass explicitly. Describe what happens if the named class does not exist.
  Why it matters: The class choice determines whether the claim can use the cluster’s default storage or requests a particular option.
• Minimum storage request: Explain what resources.requests.storage requires and how its value affects dynamically provisioned volumes versus selection of pre-provisioned volumes.
  Why it matters: A storage request expresses the capacity the application needs without requiring the claim to identify a particular volume.
• Requested access mode: Explain why a claim specifies an access mode and why the quiz claim requests ReadWriteOncePod.
  Why it matters: The requested access mode must fit how the application intends to use the volume.
• Filesystem or block requirement: Distinguish filesystem storage from a raw block device and state what omitting volumeMode means for the quiz claim.
  Why it matters: Leaving volumeMode out still makes a specific request: filesystem storage.
• Claim creation and status: Describe how to create and inspect the claim, interpret Bound and Pending with or without a displayed StorageClass, and explain why a valid claim may initially remain Pending.
  Why it matters: A Pending claim is not always an error; the status and class help you tell what to check next.

Key terms: PersistentVolumeClaim, StorageClass, storageClassName, default StorageClass, Pending, resources.requests.storage, minimum size, dynamic provisioning, static provisioning, access mode

10.2.2 Using PersistentVolumeClaims

This section shows how a pod uses a PersistentVolumeClaim and why the claimed storage remains available after the pod is deleted and recreated.

• Pod claim reference: Describe how a pod uses a PersistentVolumeClaim to access a PersistentVolume, and what happens to the claim when the pod is created.
  Why it matters: The pod refers to a claim rather than specifying the underlying storage volume directly.
• Pod deletion and claim lifetime: Explain what happens to the storage attachment, PersistentVolumeClaim, and bound PersistentVolume when a pod using the claim is deleted.
  Why it matters: Removing a pod does not remove the claim it used, so another pod can use that claim.
• Storage reuse by replacement pods: Explain how a new pod can access files left by an earlier pod through the same PersistentVolumeClaim.
  Why it matters: A replacement pod can continue using data written by its predecessor.

Key terms: PersistentVolumeClaim, PersistentVolume, persistentVolumeClaim volume, claimName, Bound, detached, ephemeral, quiz Pod

10.2.3 Deleting a PersistentVolumeClaim and PersistentVolume

The section explains what happens to a PersistentVolume after its claim is deleted and how its reclaim policy affects whether the volume and data are deleted.

• Released volume and reclaim policy: Explain why deleting a PersistentVolumeClaim releases its associated PersistentVolume without necessarily making it Available, and how the volume’s reclaim policy determines what happens next.
  Why it matters: Deleting a claim does not by itself tell you whether its volume can be reused or its data will survive.
• Changing a volume reclaim policy: Describe how changing a PersistentVolume’s reclaim policy can protect data before claim deletion, and what happens if a released volume is changed from Retain to Delete.
  Why it matters: The timing and direction of a policy change can determine whether the stored data survives.

Key terms: PersistentVolumeClaim, PersistentVolume, Released, Available, reclaim policy, Delete, persistentVolumeReclaimPolicy, reclaimPolicy, Retain, underlying storage

10.2.4 Understanding access modes

This section explains how four PersistentVolume access modes limit which pods or nodes can use a volume, and how to populate and mount a dynamically provisioned read-only volume.

• ReadWriteOncePod pod exclusivity: Explain that ReadWriteOncePod permits one pod at a time to read and write a claimed volume, so a second pod using the same claim remains Pending.
  Why it matters: This explains why a second pod cannot start using the same claim.
• ReadWriteOnce node attachment: Distinguish ReadWriteOnce from ReadWriteOncePod: multiple pods on one node can read and write the volume, but a pod on another node cannot attach it while the first node has it attached read-write.
  Why it matters: A pod’s placement determines whether it can use a ReadWriteOnce volume that other pods are already using.
• ReadWriteMany cross-node sharing: Explain that ReadWriteMany allows pods on different nodes to read and write the same volume concurrently, provided the storage technology supports this mode.
  Why it matters: This is the mode to look for when pods on different nodes must share writable storage.
• ReadOnlyMany volume initialization: Explain why a dynamically provisioned ReadOnlyMany volume needs prepopulated data, and describe cloning data from another PersistentVolumeClaim with dataSourceRef and mounting the resulting volume read-only.
  Why it matters: Cloning existing data makes a newly created read-only volume useful to reader pods.

Key terms: ReadWriteOncePod, PersistentVolumeClaim, Pending, ReadWriteOnce, ContainerCreating, read-write mode, ReadWriteMany, StorageClasses, ReadOnlyMany, dataSourceRef

10.2.5 Understanding StorageClasses

Explains how StorageClasses determine the storage provisioned for a PersistentVolumeClaim and when its volume is bound.

• StorageClass selection for claims: Explain that a PersistentVolumeClaim’s storageClassName selects a class of persistent storage, and that available classes depend on the cluster.
  Why it matters: The class a claim selects determines which storage option it requests.
• Provisioner and class parameters: Describe how a StorageClass identifies a provisioner and supplies parameters for provisioning a volume, including how classes using the same provisioner can produce different storage.
  Why it matters: A class does more than name storage: it directs how that storage is provisioned.
• Volume binding timing: Distinguish the Immediate and WaitForFirstConsumer volume binding modes by when a PersistentVolume is bound to a claim.
  Why it matters: Binding mode explains why a claim’s volume may not be bound as soon as the claim is created.

Key terms: storageClassName, StorageClass, PersistentVolumeClaim, default, provisioner, parameters, PersistentVolume, volumeBindingMode, Immediate, WaitForFirstConsumer

10.2.6 About CSI drivers

This section explains why storage support lives in CSI drivers, what their components do, and how to identify installed drivers in a cluster.

• Out-of-tree storage support: Explain why Kubernetes moved support for many storage technologies into CSI drivers: new technologies can be supported without changing core Kubernetes code or APIs.
  Why it matters: It explains how Kubernetes can gain storage support without incorporating every storage implementation into its core.
• Controller and node agent roles: Distinguish the CSI driver's controller from its per-node component in managing PersistentVolumes and making storage available when a pod uses one.
  Why it matters: The distinction separates cluster-level volume management from the work needed on a node where a pod runs.
• Installed CSI driver identification: Describe how installed CSI drivers are represented and identified in a cluster, including their connection to StorageClasses.
  Why it matters: It gives you a way to see which drivers a cluster provides and recognize their StorageClass references.

Key terms: CSI drivers, out-of-tree, controller, per-node component, node-level agent, PersistentVolumes, StorageClass, CSIDriver resource, kubectl get, provisioner field

10.3 Statically provisioning a PersistentVolume

Introduces static provisioning as creating storage and its PersistentVolume object before a claim needs it.

• Static PersistentVolume provisioning: Explain that static provisioning starts with pre-provisioned storage represented by a PersistentVolume object; when a user creates a PersistentVolumeClaim, Kubernetes finds an appropriate existing volume. Distinguish this order from dynamic provisioning.
  Why it matters: The order of creation is the key distinction between static and dynamic provisioning.

Key terms: static provisioning, PersistentVolume, PersistentVolumeClaim, dynamic provisioning

10.3.1 Creating a node-local PersistentVolume

This section explains why node-local PersistentVolumes are useful and how an administrator represents local storage with a StorageClass and a pre-provisioned PersistentVolume.

• Local volumes versus hostPath: Explain how a local PersistentVolume addresses the scheduling and security problems of using a hostPath volume for node-local data.
  Why it matters: Local volumes let applications use node-attached storage without treating a host path as interchangeable across nodes.
• Local storage class settings: Describe the StorageClass settings used to represent manually provisioned, locally attached storage and why claim binding is delayed.
  Why it matters: These settings represent local storage without automatic provisioning or prematurely binding a claim.
• Local PersistentVolume definition: Describe how the administrator defines and verifies a pre-provisioned local PersistentVolume.
  Why it matters: The object makes an administrator-supplied disk discoverable as storage that users can later claim.

Key terms: hostPath volume, local PersistentVolume, node-local PersistentVolume, StorageClass, kubernetes.io/no-provisioner, volumeBindingMode, WaitForFirstConsumer, PersistentVolume, local volume, node affinity

10.3.2 Claiming a pre-provisioned PersistentVolume

This section shows how a pod claims a pre-provisioned local PersistentVolume and explains how the same approach applies to other pre-provisioned volume types.

• Local volume claim binding: Trace how creating a PersistentVolumeClaim and then its pod binds a pre-provisioned local PersistentVolume, places the pod on a node that can access it, and mounts the volume.
  Why it matters: It explains why a local-volume claim may remain unbound until a pod uses it, and why that pod runs on a particular node.
• Other pre-provisioned volume types: Explain how the claim-and-pod approach can also be used with a pre-provisioned network-attached PersistentVolume, and what changes from the local-volume example.
  Why it matters: It shows that claiming a pre-provisioned volume is not specific to node-local storage.

Key terms: PersistentVolumeClaim, PersistentVolume, local StorageClass, WaitForFirstConsumer, scheduler, pre-provisioned PersistentVolume, network-attached PersistentVolume, csi field, StorageClass

10.3.3 Releasing and recycling a manually provisioned PersistentVolume

This section explains what happens when a statically provisioned PersistentVolume is released, made reusable, or deleted while still in use.

• Released volume and claim status: Explain why deleting a claim for a retained PersistentVolume leaves the volume Released rather than Available, and why a new claim and its pod remain Pending.
  Why it matters: A Released volume is not automatically ready for another claim, even when the new claim requests the same storage.
• Reusing retained volume storage: Describe how to make the Released PersistentVolume available again and what happens to its stored data when the pre-provisioned PersistentVolume object is deleted and recreated.
  Why it matters: Making the volume reusable changes its Kubernetes binding state, not necessarily the data on the disk.
• Deletion protection during use: Trace what happens when a bound PersistentVolume is deleted and then its claim is deleted while a pod still uses it.
  Why it matters: A deletion request can be underway while Kubernetes preserves storage that a running pod still needs.
• Underlying storage cleanup: Distinguish deleting a statically provisioned PersistentVolume object from deleting its underlying storage, and describe the cleanup implication.
  Why it matters: Removing the Kubernetes object alone may leave a disk behind and still generating charges.

Key terms: persistentVolumeReclaimPolicy, Retain, Released, Available, Pending, PersistentVolume object, claimRef, Bound, PersistentVolume, PersistentVolumeClaim

10.4 Managing PersistentVolumes

This section introduces upcoming topics for managing PersistentVolumes: resizing, snapshots, and restoring from a snapshot.

10.4.1 Resizing PersistentVolumeClaims

This section shows how to request a larger volume through an existing PersistentVolumeClaim and diagnose why the new capacity may not appear until its pod is recreated.

• Claim fields and storage classes: Distinguish changing a claim’s requested storage size from changing its StorageClass: the size request can be modified after binding, but storageClassName cannot.
  Why it matters: It helps you tell which storage changes can be made to an existing claim.
• Larger volume request: Describe how to request more space on an existing PersistentVolumeClaim and the conditions on that request.
  Why it matters: These are the steps and limits for asking Kubernetes to grow storage without replacing the claim.
• Resize status and pod recreation: Explain how to check whether the volume has actually grown, diagnose a pending resize, and complete the resize in the example.
  Why it matters: An updated request is not proof that the bound volume has grown.

Key terms: PersistentVolumeClaim, storageClassName, spec.resources.requests, spec.resources.requests.storage, ALLOWVOLUMEEXPANSION, kubectl apply, StorageClass, kubectl get pvc, CAPACITY, kubectl describe

10.4.2 Creating a snapshot of a PersistentVolumeClaim

Explains how to request a CSI-backed snapshot of a PersistentVolumeClaim and interpret the snapshot resources and status.

• VolumeSnapshotClass configuration: Explain that a VolumeSnapshotClass specifies the CSI driver and optional parameters used to create snapshots, and that a class is created before requesting the example snapshot.
  Why it matters: The class tells the CSI driver how to create the requested snapshot.
• Snapshot request and readiness: Describe how a VolumeSnapshot requests a snapshot using a PersistentVolumeClaim as its source, and how its displayed status changes when creation completes.
  Why it matters: The request and its readiness status tell you whether a snapshot is available to use.
• Snapshot request and content: Distinguish the namespaced VolumeSnapshot request from the cluster-scoped VolumeSnapshotContent representing the actual snapshot, including their one-to-one association.
  Why it matters: Keeping the request separate from the snapshot content clarifies which resource users create and which represents the resulting snapshot.

Key terms: VolumeSnapshotClass, CSI driver, deletionPolicy, VolumeSnapshot, PersistentVolumeClaim, READYTOUSE, RESTORESIZE, VolumeSnapshotContent, namespaced, cluster scoped

10.4.3 Restoring a PersistentVolume from a snapshot

This section shows how to create a PersistentVolumeClaim from a VolumeSnapshot and when a pod is needed to start restoration.

• Snapshot as claim data source: Explain how to create a PersistentVolumeClaim from a snapshot by specifying the VolumeSnapshot as its data source, including the required apiGroup in dataSourceRef.
  Why it matters: The claim must identify both the snapshot and its API group to use it as the restoration source.
• Restoration start conditions: Describe which StorageClass is used when the new claim omits storageClassName and when a pod is needed to start restoration.
  Why it matters: A claim may not start restoring immediately if the default StorageClass waits for a pod.

Key terms: PersistentVolumeClaim, VolumeSnapshot, dataSourceRef, apiGroup, snapshot.storage.k8s.io, storageClassName, default StorageClass, WaitForFirstConsumer, volume binding policy

10.5 Creating ephemeral PersistentVolumes for individual pods

Introduces ephemeral PersistentVolumes by contrasting them with the chapter’s usual expectation of storage independent of any particular pod.

• PersistentVolume lifetime expectations: Explain that the chapter’s usual focus is storage whose life cycle is independent of the pods using it, and why an ephemeral PersistentVolume sounds unexpected.
  Why it matters: This contrast explains why the chapter treats ephemeral PersistentVolumes as an exception worth introducing.

Key terms: PersistentVolume, persistent storage, ephemeral PersistentVolume

10.5.1 Introducing the ephemeral volume type

This subsection shows how an ephemeral volume creates a pod-specific PersistentVolumeClaim, mounts its bound PersistentVolume, and is cleaned up with the pod.

• Ephemeral volume claim creation: Explain how an ephemeral volume’s volumeClaimTemplate causes Kubernetes to create a PersistentVolumeClaim for the pod, and describe how the resulting PersistentVolume becomes available to the container.
  Why it matters: It explains why the pod can use a PersistentVolume without referencing a separately created claim in its manifest.
• Pod-linked volume cleanup: Explain what happens to the ephemeral volume’s PersistentVolumeClaim when its pod is deleted, and why the example’s PersistentVolume is deleted too.
  Why it matters: It distinguishes a pod-scoped claim from storage whose claim remains after the pod is removed.

Key terms: ephemeral volume, volumeClaimTemplate, PersistentVolumeClaim, PersistentVolume, ephemeral PersistentVolumeClaim, life cycle, retain policy, Delete

10.5.2 Understanding the benefits of using an ephemeral volume

This section explains why a pod might use an ephemeral volume instead of an emptyDir volume for temporary data.

• Temporary data and pod access: Describe how an ephemeral volume resembles an emptyDir volume: it gives a pod exclusive access to a directory for scratch data that is typically discarded after the pod finishes.
  Why it matters: This common purpose makes the differences between the two volume types meaningful.
• Ephemeral volume advantages: Explain why an ephemeral volume can be useful despite requiring a volumeClaimTemplate and additional PersistentVolumeClaim and PersistentVolume objects: its normal PersistentVolume can be local or network attached, supports features such as snapshots and initialization from different data sources, and can have a fixed size the pod cannot exceed and can later resize.
  Why it matters: These capabilities explain when the extra volume objects may be worth using instead of emptyDir.

Key terms: ephemeral volume, emptyDir volume, scratch data, volumeClaimTemplate, PersistentVolumeClaim, PersistentVolume, snapshots

10.6 Summary

Summarizes how Kubernetes provisions, uses, and manages PersistentVolumes, including local and ephemeral volumes.