Core Kubernetes · 07

Volumes and Storage

1.Why volumes ?

A crashed or stopped container comes back with a clean filesystem, so the files it wrote are lost. Containers in one Pod also need a place to share files.

  • Every volume survives a container restart.
  • Ephemeral volumes die with the Pod. Persistent ones (a PV used through a PVC) outlive it.
  • Declare in spec.volumes, mount per container with volumeMounts (mountPath, readOnly, subPath). Volumes do not nest.
Pod app sidecar mount emptyDirshared scratch gone when the Pod goes claimName PVC 1 : 1 PVreal storage outlives the Pod

2.Volume types by lifetime

TypeLivesGood forWatch out
emptyDirPodscratch, sharing filesmedium: Memory = tmpfs (RAM). Set sizeLimit.
configMap, secret, downwardAPIPodconfig, secrets, Pod infoRead-only files. subPath mounts update only on a restart.
projectedPodmany sources, one folderSources must be in the Pod's namespace.
ephemeral (generic)Podper-Pod scratch PVCPVC <pod>-<volume> is deleted with the Pod.
csi (inline)Poddriver-specific volumesThe CSIDriver must list the Ephemeral mode.
hostPathnodenode agents, static PodsSecurity risk. Contents differ per node.
persistentVolumeClaimPVdata that has to lastPVC must be in the Pod's namespace.
local (PV only)PVfast disks on one nodeStatic, needs nodeAffinity. Node down = Pod stuck.
Avoid hostPathIt mounts a node path into the Pod and can expose kubelet credentials or the container runtime socket, a way out of the container. Use a local PV for node disks. A hostPath PV without node affinity is for one-node tests.
Good to knowemptyDir is created when the Pod lands on a node and deleted when it leaves. projected merges secret, configMap, downwardAPI, serviceAccountToken, clusterTrustBundle and podCertificate. More in ConfigMaps and Secrets.

3.PV, PVC and StorageClass

  • PV : cluster-scoped, static (admin) or dynamic.
  • PVC : namespaced request: size, modes, class.
  • Binding : 1:1, PV claimRef + PVC volumeName.
  • Pod : uses claimName, PVC in the same namespace.
  • StorageClass : names a provisioner + parameters.
  • Provisioner : makes the PVs, often a CSI driver you install (in-tree cloud types too, v1.25).
  • Kubernetes ships no built-in NFS provisioner.
Access modeMeans
ReadWriteOnce RWOread-write, one node
ReadOnlyMany ROXread-only, many nodes
ReadWriteMany RWXread-write, many nodes (NFS-like)
ReadWriteOncePod RWOPread-write, one Pod

Modes match claims to PVs. RWO keeps an attached or local volume on one node; Pods there share it. RWOP admits one Pod.

4.Reclaim policy

  • Delete : deleting the PVC removes the PV and its storage. Default for dynamic PVs (copied from the class).
  • Retain : PV goes Released, data kept for manual cleanup. Default for hand-made PVs.
  • Recycle : deprecated.
Pending Available Bound new PV claimed DeletedPV + storage Releaseddata kept Failedreclaim broke PVC deleted Retain : clean up,drop claimRef Delete fails A Released PV never binds a new claim by itself.
In short : Every volume outlives a container restart. Ephemeral ones end with the Pod, a PV does not, and a PVC binds 1:1 to a PV that a CSI driver usually creates for it.

1.Dynamic provisioning

With volumeBindingMode: WaitForFirstConsumer :

  1. Admin creates a StorageClass.
  2. User creates a PVC. It is Pending.
  3. User creates a Pod with claimName.
  4. Scheduler picks a node for the Pod.
  5. Driver makes a volume for that node.
  6. Driver creates the PV.
  7. PV and PVC bind. PVC is Bound.
  8. kubelet mounts it into the Pod.
Immediate (default)Steps 5 to 7 follow step 2 at once, blind to where the Pod may run. Static: an admin makes PVs, a matching one binds.
Admin User kube-scheduler StorageClasswaits for a Pod PVCPending PodclaimName CSI driverprovisioner PVclaimRef: PVC kubeleton that node Backendnode's topology 1 2 3 4 class names 5 6 7 8 volume attached to that node

2.StatefulSet claims

  • One PVC per Pod per template: <template>-<sts>-<ordinal>.
  • A moved Pod gets its old PVC back (more).
  • Scale down or delete keeps PVCs, unless persistentVolumeClaimRetentionPolicy says Delete (v1.32).
  • Templates are immutable: resize each PVC.
StatefulSet webtemplate: www creates web-0keeps its PVC web-1gone after scale to 1 mounts www-web-0PVC, own PV www-web-1PVC kept for scale up

3.Commands

CommandWhat it is for
kubectl get pv,pvc -AStatus, claim, class, reclaim policy of all of them
kubectl get scProvisioner, binding mode, expansion, (default)
kubectl get csidriversInstalled CSI drivers (Persistent, Ephemeral)
kubectl describe pvc <name> -n <ns>Events say why it is Pending
kubectl patch pv <pv> -p '{"spec":{"persistentVolumeReclaimPolicy":"Retain"}}'Keep the PV and data before deleting the claim. Back to Delete, local-path cleans it while Released, not once Available
kubectl patch pvc <pvc> -p '{"spec":{"resources":{"requests":{"storage":"20Gi"}}}}'Grow the volume, then follow the PVC events
kubectl patch pv <pv> --type=json -p '[{"op":"remove","path":"/spec/claimRef"}]'Cleaned Released PV back to Available. Remove only /spec/claimRef/uid to keep it for the same claim name
kubectl delete pvc <name> -n <ns>Careful : under Delete the data goes too. In use, it stays Terminating and kubectl waits (--wait=false skips it)

4.Gotchas & good to know

Gotchas
  • WaitForFirstConsumer : Pending until a Pod is scheduled is normal. A nodeName pin keeps it stuck.
  • No storageClassName = default class (even one added later). "" = class-less PVs only.
  • Two default classes: the newest wins. Keep one.
  • Volumes only grow. Never edit a PV's capacity.
Good to know
  • Grow : allowVolumeExpansion: true and a driver that can grow, then raise the PVC request. Failed? Lower it to above the old size (v1.34). FS: XFS, ext3, ext4 (online OK).
  • Snapshots : CSI only, CRDs from your distribution. Restore via PVC dataSource.
  • Databases want an operator, see CloudNativePG.
In short : WaitForFirstConsumer lets the Pod's node pick where the volume lands, StatefulSets keep one PVC per replica, volumes only grow, and Retain guards data you care about.