Appearance

Volumes and persistent claims

Separate container filesystems, Pod-scoped volumes, persistent claims and storage access semantics.

What you will understand

  • Predict which data survives a container restart or Pod replacement
  • Trace PVC-to-PV binding and mounting
  • Explain access modes without treating them as database locks

Builds on: Ingress, Gateway API, and TLS

Mental model: name the lifetime of every file

A container’s writable filesystem belongs to that container instance. Kubernetes restarts a container from its image, so application changes to that writable layer should be treated as disposable. A volume mounts storage at a path inside one or more containers. Its lifetime depends on its type. emptyDir is created for a Pod and can survive container restarts in that Pod, but deletion or replacement of the Pod removes that Pod-scoped storage. The replacement’s identical Deployment labels do not make it the same Pod.

Persistent storage separates application placement from a longer-lived storage resource. A PersistentVolumeClaim, or PVC, is a namespaced request for storage characteristics and capacity. A PersistentVolume, or PV, is a cluster-scoped representation of a storage resource. Binding associates a suitable PV with a claim; the workload refers to the claim rather than embedding the provider’s disk identity. The underlying data then follows storage and reclaim lifecycle rules rather than the container’s writable-layer lifetime.

Three files, three lifetimes

Compare a container writable layer, emptyDir and PVC data during restart and Pod replacement.

Storage viewStep 1 of 4
Write at explicit pathsThe same process can write to its own filesystem, a Pod-scoped emptyDir and a claim-backed mounted path.. Container, Instance can restart, active. Writable layer, Fresh for a restarted container, idle. emptyDir, Belongs to this Pod, idle. PVC app-data, Names a bound persistent volume, idle. PV data, Underlying storage lifecycle, idleContainer: Instance can restart
ContainerInstance can restartIn focus
Writable layer: Fresh for a restarted container
Writable layerFresh for a restarted containerContext
emptyDir: Belongs to this Pod
emptyDirBelongs to this PodContext
PVC app-data: Names a bound persistent volume
PVC app-dataNames a bound persistent volumeContext
PV data: Underlying storage lifecycle
PV dataUnderlying storage lifecycleContext
ContainerInstance can restartIn focus
Writable layerFresh for a restarted containerContext
emptyDirBelongs to this PodContext
PVC app-dataNames a bound persistent volumeContext
PV dataUnderlying storage lifecycleContext
Animation controls
Speed
0.5×
1×
2×
Explore a scenario
Normal behavior
Claim is deleted with Delete policy
Write at explicit paths

The same process can write to its own filesystem, a Pod-scoped emptyDir and a claim-backed mounted path.

Read the complete visual sequence
  1. Write at explicit paths

    The same process can write to its own filesystem, a Pod-scoped emptyDir and a claim-backed mounted path.

  2. Restart the container

    A new container filesystem starts from the image. The Pod is the same, so its emptyDir and PVC mounts remain available.

  3. Replace the Pod

    A replacement has a new Pod identity and new emptyDir. It can refer to the same PVC to recover persistent data.

  4. Inspect the backing resource

    Claim-backed persistence depends on the real storage provider and policy; a local node directory does not imply cross-node durability.

Claim is deleted with Delete policy

Deleting the storage request can lead to deletion of its underlying data.

  1. Workload removed

    Removing the workload alone can leave the independently created PVC and its data intact.

  2. Claim released

    Deleting the claim enters the PV reclamation lifecycle after applicable protection conditions clear.

  3. Delete policy reclaims storage

    The provisioner can delete the backing storage. Recreating a claim with the old name does not recover the old bytes.

About this model

Storage implementation remains available; the scene does not claim backup or node-loss recovery.

Try the mechanism with your own inputs
A matching volume can bindCapacity, storage class, and availability match. Actual binding also considers access modes, topology, volume mode, and provisioning policy.. PVC, 1 Gi · fast, active. PV volume-a, 3 Gi · fast · available, readyPVC: 1 Gi · fast
PVC1 Gi · fastIn focus
PV volume-a: 3 Gi · fast · available
PV volume-a3 Gi · fast · availableReady
PVC1 Gi · fastIn focus
PV volume-a3 Gi · fast · availableReady
A matching volume can bind

Capacity, storage class, and availability match. Actual binding also considers access modes, topology, volume mode, and provisioning policy.

spec:
  storageClassName: fast
  resources:
    requests:
      storage: 1Gi

Walkthrough: a claim is a contract, not a directory copied between Pods

This claim requests a filesystem volume from the cluster’s default StorageClass. The second fragment belongs under a Pod’s spec and shows how it mounts that claim. The module lab’s complete workload uses the name m09 for both its Pod and claim; adapt those names together when extending it into this separate app-data and writer example.

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: app-data
spec:
  accessModes: [ReadWriteOnce]
  resources:
    requests:
      storage: 1Gi
---
# Fragment: a Pod spec mounting the claim in one container.
containers:
  - name: writer
    image: busybox:1.36
    command: ["sh", "-c", "echo marker >> /data/visits; sleep 3600"]
    volumeMounts:
      - name: data
        mountPath: /data
volumes:
  - name: data
    persistentVolumeClaim:
      claimName: app-data

The PVC must be in the Pod’s namespace. A claim can remain Pending when no suitable PV or provisioner exists; later lessons follow dynamic provisioning. The Pod can also wait after binding while the driver attaches or mounts the volume. Do not treat Bound as proof that filesystem permissions, attachment and application startup all succeeded. Read both PVC events and Pod events to find the current boundary.

Access modes describe supported mounting and access arrangements. ReadWriteOnce means read-write access from one node; multiple Pods on that same node may still access it. ReadOnlyMany and ReadWriteMany depend on provider support and requested behavior. These modes help match claims to volumes; they do not by themselves enforce read-only filesystem permissions after mounting. Set the mount read-only setting and underlying permissions when that protection is required. ReadWriteOncePod constrains a supported CSI volume to one Pod across the cluster, including read access. None of these is a general application transaction protocol. A storage system allowing multiple writers does not coordinate database leadership, protect file format consistency or implement distributed locks for your application.

One node is not one application writer

Explain ReadWriteOnce, ReadWriteOncePod and reclaim policy without promising application locking.

Storage viewStep 1 of 4
Request an access arrangementReadWriteOnce asks for read-write mounting on one node and must be supported by the volume.. Pod A, Writer on Node 1, idle. Pod B, Another writer on Node 1, idle. Node 1, One mounting node, idle. PVC, ReadWriteOnce, active. PV, Reclaim policy Retain or Delete, activePod A: Writer on Node 1
Pod AWriter on Node 1Context
Pod B: Another writer on Node 1
Pod BAnother writer on Node 1Context
Node 1: One mounting node
Node 1One mounting nodeContext
PVC: ReadWriteOnce
PVCReadWriteOnceIn focus
PV: Reclaim policy Retain or Delete
PVReclaim policy Retain or DeleteIn focus
Pod AWriter on Node 1Context
Pod BAnother writer on Node 1Context
Node 1One mounting nodeContext
PVCReadWriteOnceIn focus
PVReclaim policy Retain or DeleteIn focus
Animation controls
Speed
0.5×
1×
2×
Explore a scenario
Normal behavior
Application assumes RWO is a lock
Request an access arrangement

ReadWriteOnce asks for read-write mounting on one node and must be supported by the volume.

Read the complete visual sequence
  1. Request an access arrangement

    ReadWriteOnce asks for read-write mounting on one node and must be supported by the volume.

  2. Mount on the first node

    The driver attaches or mounts according to its implementation and the Pod uses the claim.

  3. Same-node second Pod may mount

    ReadWriteOnce does not itself mean one Pod. Both same-node writers can need application-level coordination.

  4. Separate access from reclamation

    Access modes concern use; reclaim policy concerns what happens after claim release. Neither is a database transaction lock.

Application assumes RWO is a lock

Two same-node processes concurrently modify an unsafe data format.

  1. Both mounts succeed

    The access arrangement is compatible with the one-node mode.

  2. Concurrent writes conflict

    The storage mode has not supplied application leader election or transactional coordination.

  3. Choose the right boundary

    Use a supported single-Pod mode when appropriate and implement application consistency; retain backups independently.

About this model

Driver supports the illustrated access mode; application consistency is outside mount admission.

Practice: replace the Pod without deleting the claim

kubectl get pvc app-data
kubectl describe pvc app-data
kubectl get pv
kubectl exec writer -- cat /data/visits
# Follow the lab instructions to delete and recreate only the writer Pod.
kubectl get pod writer -o wide
kubectl describe pod writer

Create a marker in the mounted directory, replace the Pod, and read the marker from the replacement. Compare that to a file written outside the mounted path and to a separate emptyDir example. Keep the PVC intact during this comparison. If a local host-path provisioner backs the claim, surviving a Pod replacement on the same worker does not prove the volume can follow a Pod to another worker or survive loss of the host machine.

A PV’s reclaim policy governs what happens after its claim is released. Delete generally asks the provisioner to remove the underlying storage as part of reclamation. Retain leaves the resource for explicit administrator recovery and reuse procedures. Deleting a Deployment does not normally delete an independently managed PVC, but deleting a PVC can start a destructive storage lifecycle depending on policy and protection finalizers. Record claim, PV, storage class and reclaim policy before any cleanup involving persistent data.

Pitfalls: persistent does not mean backed up

Persistent storage can retain an accidental deletion, corrupted data or an application bug just as reliably as useful data. Storage availability, durability and recovery are different properties. A hostPath volume exposes a particular node’s filesystem and carries security and locality risks; it is not a portable general-purpose replacement for a storage system. Filesystem ownership can also block startup despite a healthy bound claim. Investigate permissions before broadening a container to privileged mode.

Check your understanding

Two Pods are on the same node and both mount a ReadWriteOnce claim. Has Kubernetes promised only one writer?

No. ReadWriteOnce constrains read-write access to one node, not necessarily one Pod. Provider behavior and mounting details matter, and the application still needs correct coordination. For a supported CSI volume, ReadWriteOncePod is the relevant single-Pod access mode, but it still does not replace application-level consistency and recovery design.

Use the storage lab to compare Pod-scoped and claim-backed data. Next, follow the StorageClass and driver that turn an unbound request into actual storage.

Primary documentation

Go to the source

Reviewed 2026-10-27 · Kubernetes 1.37 · Related local exercise

Search the book

Search loads when you open it.