Lesson 6 of 8 in Kubernetes
Storage: volumes, PersistentVolumes and claims
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
- Runs code
- Control
- Data
A Pod mounts a claim, the claim binds to a PersistentVolume, and a StorageClass can create that volume on demand.
- Pod to PVC: 1 mounts the claim
- PVC to PersistentVolume: 2 binds to
- 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.
- 1See the available StorageClass
kubectl get storageclass
Look for the one marked
(default). A claim without astorageClassNameuses it. - 2Create 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,pvThe claim can show
Pendingfor a moment before the Pod starts, thenBound. - 3Replace 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
startedlines. The first Pod is gone, but its file survived on the volume. - 4Clean 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
storageClassNamethat 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, thenkubectl get storageclassto compare names.
The claim is Pending and
kubectl describe pvcsays 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 pvcagain. If it is still Pending, read the Pod's events withkubectl describe pod <pod-name>.
Files vanish whenever the Pod is replaced.
- WHY IT HAPPENS
- The data is on a container filesystem or an
emptyDirvolume, which lives only as long as the Pod. Only a PVC-backed volume outlives it. - CHECK FIRST
- Run
kubectl get pod <pod-name> -o yamland look atvolumes. Use apersistentVolumeClaimentry 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.
Keep going
Lesson 75 of 92 in the DevOps path