Lesson 6 of 8 in Kubernetes

Storage: volumes, PersistentVolumes and claims

Core12 min

A PersistentVolumeClaim is a request for storage that a Pod mounts. Kubernetes binds it to a PersistentVolume, often created on demand by a StorageClass, so the data outlives any single Pod.

Draft. This lesson is written and waiting for a person to run every command and review it. It is safe to learn from, but check the official documentation for anything you depend on.

Read these first: Pods: the smallest thing Kubernetes runs, Containers with Docker

The problem this solves

A container's own filesystem disappears when the container is replaced, and Pods are replaced all the time. Anything the app saved there is lost. A database or an upload folder needs storage that stays.

Kubernetes separates the person who needs storage from the person who supplies it. The app asks for a size and an access mode with a claim. The cluster finds or creates a matching volume and attaches it to wherever the Pod runs.

How it works

From a Pod's request to real storage
From a Pod's request to real storageA Pod mounts a claim, the claim binds to a PersistentVolume, and a StorageClass can create that volume on demand.1 mounts theclaim2 binds to3 creates on demandPodmounts /dataPVCrequest: 1GiPersistentVolumethe actual storageStorageClasshow to create volumes
  • Runs code
  • Control
  • Data

A Pod mounts a claim, the claim binds to a PersistentVolume, and a StorageClass can create that volume on demand.

  1. Pod to PVC: 1 mounts the claim
  2. PVC to PersistentVolume: 2 binds to
  3. StorageClass to PersistentVolume: 3 creates on demand

Read the diagram left to right. The Pod does not know where its disk lives. It names a claim, the PVC. The claim states how much space it wants and how it will be used, for example one node at a time with ReadWriteOnce.

A PersistentVolume is the real piece of storage. An administrator can create one by hand, but most clusters use dynamic provisioning. A StorageClass names a provisioner, and when a claim arrives, the provisioner creates a matching volume and binds it.

Some classes use WaitForFirstConsumer, which delays creating the volume until a Pod uses the claim, so the volume lands near the Pod. A claim that shows Pending is then normal until a Pod appears. When the claim is deleted, the volume's reclaim policy decides its fate. With the common Delete policy, the data is deleted too.

Try it yourself

kind ships with a default StorageClass that stores volumes on the node's disk. That is fine for learning and not for production.

  1. 1
    See the available StorageClass
    kubectl get storageclass

    Look for the one marked (default). A claim without a storageClassName uses it.

  2. 2
    Create a claim and a Pod that uses it
    cat > pvc.yaml <<'EOF'
    apiVersion: v1
    kind: PersistentVolumeClaim
    metadata:
      name: data-claim
    spec:
      accessModes: ["ReadWriteOnce"]
      resources:
        requests:
          storage: 1Gi
    ---
    apiVersion: v1
    kind: Pod
    metadata:
      name: pvc-demo
    spec:
      containers:
        - name: app
          image: busybox:1.36
          command: ["sh", "-c", "echo started $(date) >> /data/log.txt; sleep 3600"]
          volumeMounts:
            - name: store
              mountPath: /data
      volumes:
        - name: store
          persistentVolumeClaim:
            claimName: data-claim
    EOF
    kubectl apply -f pvc.yaml
    kubectl wait --for=condition=Ready pod/pvc-demo --timeout=90s
    kubectl get pvc,pv

    The claim can show Pending for a moment before the Pod starts, then Bound.

  3. 3
    Replace the Pod and keep the data
    kubectl delete pod pvc-demo
    kubectl apply -f pvc.yaml
    kubectl wait --for=condition=Ready pod/pvc-demo --timeout=90s
    kubectl exec pvc-demo -- cat /data/log.txt

    You should see two started lines. The first Pod is gone, but its file survived on the volume.

  4. 4
    Clean up
    kubectl delete -f pvc.yaml
    rm pvc.yaml

    Deleting the claim also deletes the volume with the default reclaim policy, so the data is gone.

What breaks, and where to look

  • The Pod stays Pending with the event: pod has unbound immediate PersistentVolumeClaims.

    WHY IT HAPPENS
    The claim could not bind. Common reasons are a storageClassName that does not exist, no default StorageClass in the cluster, or no free volume large enough.
    CHECK FIRST
    Run kubectl describe pvc <claim-name> and read its Events, then kubectl get storageclass to compare names.
  • The claim is Pending and kubectl describe pvc says it is waiting for a first consumer to be created before binding.

    WHY IT HAPPENS
    The StorageClass uses WaitForFirstConsumer. Nothing is wrong yet: the volume is created only after a Pod uses the claim.
    CHECK FIRST
    Create the Pod that mounts the claim, then run kubectl get pvc again. If it is still Pending, read the Pod's events with kubectl describe pod <pod-name>.
  • Files vanish whenever the Pod is replaced.

    WHY IT HAPPENS
    The data is on a container filesystem or an emptyDir volume, which lives only as long as the Pod. Only a PVC-backed volume outlives it.
    CHECK FIRST
    Run kubectl get pod <pod-name> -o yaml and look at volumes. Use a persistentVolumeClaim entry for data that must stay.

When not to use this

  • Running a database in Kubernetes is hard to do well: backups, upgrades and failover are on you. For learning it is fine. For real data, consider a managed database.
  • Local-disk volumes tie data to one node. If that node is lost, so is the data. Production clusters use network or cloud storage with backups.

Check yourself

What does a Pod name in its volumes section to get persistent storage?

A PersistentVolumeClaim, by claimName. The claim is bound to a PersistentVolume that holds the data.

What does a StorageClass do?

It describes how to create storage on demand, so a new claim gets a matching PersistentVolume without an administrator creating it first.

Why might a new claim sit at Pending without being a problem?

With WaitForFirstConsumer, the volume is created only once a Pod that uses the claim is scheduled.

Lesson 75 of 92 in the DevOps path

Search

Search cheat sheets and projects