Kubernetes Storage: Volume, PersistentVolume, PersistentVolumeClaim, and StorageClass

ARTIFICIAL INTELLIGENCE

Storage in Kubernetes: Volume, PersistentVolume, PersistentVolumeClaim and StorageClass

Why storage matters in the container world

Containers are born stateless: if a Pod is removed or rescheduled on another node, its ephemeral filesystem disappears. However, many real applications need persistent data: databases, queues, CMSs, logging systems, analytics platforms. Kubernetes addresses this need with a layered storage model that separates the lifecycle of data from that of Pods and allows you to abstract the underlying technologies, from local disk to cloud storage, up to NFS or distributed solutions like Ceph or Portworx.

Understanding how the key concepts interact is essential for designing a reliable and scalable cluster. In the following paragraphs you’ll see how Volume, PersistentVolume, PersistentVolumeClaim and StorageClass work, how they tie together, and which choices to make in production.

Volume: the mount unit for Pods

A Volume is the resource that a container mounts as part of its filesystem. Unlike a container’s ephemeral storage, the lifetime of a Volume is at least that of the Pod. There are different types with specific behaviors.

Ephemeral volumes

These volumes live and die with the Pod. They’re ideal for cache, scratch space, or config.

– emptyDir: temporary directory shared among containers in the same Pod, deleted when the Pod ends.

– configMap and secret: mount configurations and secrets as files.

– downwardAPI: exposes Pod metadata to the filesystem.

– CSI ephemeral: volumes provided by CSI drivers in ephemeral mode.

Pod-level persistent volumes

A type like hostPath links a node directory to the Pod; it’s useful for tests or single-node environments, but discouraged in production because it ties the app to the node and introduces security risks. For real persistence and portability, move to the next layer: cluster-scoped persistent resources.

PersistentVolume: the cluster storage resource

A PersistentVolume (PV) represents storage space in the cluster, provided by a backend system (cloud disk, SAN, NAS, distributed file systems, etc.). It’s a cluster resource, managed by administrators or created dynamically via a driver.

Key characteristics

– Capacity: available size (e.g., 20Gi).

– AccessModes: how Pods can access it.

• ReadWriteOnce (RWO): read/write access from a single node.

• ReadOnlyMany (ROX): multiple nodes in read-only.

• ReadWriteMany (RWX): multiple nodes in read/write, typical of NFS or shared filesystems.

– ReclaimPolicy: what happens to the PV when its claim is released.

• Retain: data remains, manual cleanup.

• Delete: the backend destroys the volume.

• Recycle: deprecated.

– VolumeMode: Filesystem (default) or Block (block pass-through).

– NodeAffinity and topology: constraints to stay close to workloads or in specific zones.

Lifecycle

PVs have states such as Available, Bound, Released, Failed. When a compatible claim appears, Kubernetes attempts binding. With dynamic provisioning, the driver creates the physical volume on the backend that will become a PV.

PersistentVolumeClaim: the application’s storage request

A PersistentVolumeClaim (PVC) is the “request” made by users or applications. It specifies size, access modes, and optionally the desired storage class. Kubernetes looks for a PV that satisfies the request or, if configured, creates one dynamically.

How binding works

– Static: a compatible PV already exists; the PVC binds to it.

– Dynamic: the PVC triggers PV creation through the StorageClass and its CSI driver.

Pods mount the PVC, not the PV directly: this separation makes it possible to replace or migrate volumes while keeping the interface stable for workloads.

StorageClass: quality classes and dynamic provisioning

A StorageClass defines “how” to create volumes: which driver to use (provisioner), parameters (tier, disk type, replication), reclaim policy, expandability, and when to perform binding relative to Pod placement.

Important attributes

– provisioner: the CSI driver (e.g., ebs.csi.aws.com, pd.csi.storage.gke.io, disk.csi.azure.com, nfs.csi.k8s.io).

– parameters: backend-specific details (e.g., type: gp3, fsType: ext4).

– reclaimPolicy: usually Delete or Retain, aligned with the backup strategy.

– allowVolumeExpansion: enables increasing the volume capacity.

– volumeBindingMode: Immediate or WaitForFirstConsumer. The latter avoids creating the volume before knowing which zone the Pod will land in, preventing topology mismatches.

A class can be marked as default so that PVCs without storageClassName use it automatically.

Example: end-to-end dynamic provisioning

Below is a typical flow that uses a “fast” class to create a PVC and mount it in a Pod.

StorageClass

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: fast
  annotations:
    storageclass.kubernetes.io/is-default-class: "true"
provisioner: ebs.csi.aws.com
parameters:
  type: gp3
  fsType: ext4
reclaimPolicy: Delete
allowVolumeExpansion: true
volumeBindingMode: WaitForFirstConsumer

PersistentVolumeClaim

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: data-claim
spec:
  accessModes:
  - ReadWriteOnce
  storageClassName: fast
  resources:
    requests:
      storage: 20Gi

Pod mounting the PVC

apiVersion: v1
kind: Pod
metadata:
  name: web
spec:
  containers:
  - name: nginx
    image: nginx:stable
    volumeMounts:
    - name: data
      mountPath: /var/www/data
  volumes:
  - name: data
    persistentVolumeClaim:
      claimName: data-claim

Example: static provisioning with NFS

In some scenarios you want to pre-create shared volumes. Here is an RWX PV on NFS and a claim that uses it.

apiVersion: v1
kind: PersistentVolume
metadata:
  name: nfs-pv
spec:
  capacity:
    storage: 100Gi
  accessModes:
  - ReadWriteMany
  persistentVolumeReclaimPolicy: Retain
  nfs:
    server: 10.0.0.10
    path: /export/data
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: nfs-claim
spec:
  accessModes:
  - ReadWriteMany
  resources:
    requests:
      storage: 50Gi
  storageClassName: ""

Operations and troubleshooting

To troubleshoot binding or provisioning issues, check the status of claims and related events.

kubectl get sc
kubectl get pvc
kubectl describe pvc data-claim
kubectl get pv
kubectl describe pv <nome-pv>

Common causes of PVCs stuck in Pending:

– No default StorageClass and PVC without storageClassName.

– AccessModes not compatible with the backend (e.g., RWX on a driver that supports only RWO).

– Topology/zones not aligned; use WaitForFirstConsumer.

– Cloud account quotas or limits exhausted.

Security and policy

Storage involves sensitive data: apply appropriate controls.

– Encryption: leverage the provider’s encryption at rest and, where possible, encryption in transit (for NFS/TLS or distributed solutions).

– Application access: use securityContext (fsGroup, runAsUser) to ensure correct permissions on the mounted filesystem.

– Segregation: separate namespaces and apply ResourceQuota to limit the overall PVC capacity.

– ReclaimPolicy: align Retain/Delete with the backup plan and secure data destruction.

Architectural choices and best practices

– Choose the right AccessMode: RWO for single-writer databases; RWX for shared workloads, preferring native backends for RWX (NFS, CephFS, EFS).

– Avoid hostPath in production: it compromises portability and security.

– Use WaitForFirstConsumer: reduces zone errors and improves allocation.

– Enable allowVolumeExpansion and define resize processes, paying attention to file systems that require remount.

– Monitor: collect metrics on IOPS/latency, provisioning errors, space saturation.

– Snapshots and backups: integrate VolumeSnapshot (if supported by the CSI) and a tested recovery strategy.

When to use what: a mental map

– Only need temporary space in the Pod? emptyDir is enough.

– Want to inject config or secrets? Mount configMap and secret.

– Need to persist data beyond the life of the Pod? Define a PVC and rely on the StorageClass for dynamic provisioning.

– Need sharing across multiple replicas? Choose RWX with a suitable backend (NFS, CephFS, EFS), or redesign for sharding/event sourcing if sharing the same path isn’t strictly necessary.

Conclusion

Kubernetes’ storage model neatly separates responsibilities: Pods mount Volumes through PVCs; the cluster provides capacity through PVs; classes describe how and where to create volumes. With the right choices on AccessModes, policies, topology, and security, you can go from a simple test cluster to a reliable infrastructure for production stateful workloads.

Take action

Want to design or optimize your cluster’s storage, choose the ideal StorageClass, and secure your data? Contact us for an assessment session: we’ll analyze your workloads, define service classes, and build an operational plan with best practices, automation, and end-to-end monitoring.

Se vuoi farmi qualche richiesta o contattarmi per un aiuto riempi il seguente form

    Comments