Orchestration

Kubernetes Storage Classes: Dynamic Provisioning

August 2, 2026 Kubezilla Team 17 min read

Introduction

In the ephemeral world of containers, managing persistent data can often feel like wrestling an octopus in a phone booth. While pods come and go, the data they generate and rely upon often needs to persist across restarts, rescheduling, and even node failures. This is where Kubernetes Storage Classes, Persistent Volumes (PVs), and Persistent Volume Claims (PVCs) enter the scene, providing a robust and flexible storage abstraction layer. Without a proper storage strategy, stateful applications in Kubernetes would be impractical, leading to data loss and operational nightmares.

Dynamic provisioning, powered by Storage Classes, is a game-changer. Instead of manually pre-provisioning storage volumes for every application—a tedious, error-prone, and unscalable process—Kubernetes can automatically provision storage on demand when a PVC requests it. This not only streamlines operations but also ensures that applications get the right type and amount of storage exactly when they need it, configured according to predefined policies. This guide will demystify Kubernetes Storage Classes and walk you through the process of setting up dynamic storage provisioning, empowering you to manage stateful workloads with confidence.

TL;DR: Kubernetes Storage Classes enable dynamic provisioning of persistent storage. Define a StorageClass, create a PVC referencing it, and Kubernetes automatically provisions a PV from your underlying storage system. This automates storage management for stateful applications.

# List existing StorageClasses
kubectl get storageclass

# Example StorageClass definition (aws-ebs-gp2)
kubectl apply -f - <<EOF
apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: fast-disks
provisioner: ebs.csi.aws.com
parameters:
  type: gp2
  fsType: ext4
reclaimPolicy: Delete
volumeBindingMode: Immediate
EOF

# Example PVC requesting storage from 'fast-disks'
kubectl apply -f - <<EOF
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: my-app-pvc
spec:
  storageClassName: fast-disks
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 10Gi
EOF

# Verify PVC and PV creation
kubectl get pvc my-app-pvc
kubectl get pv

Prerequisites

Before diving into dynamic storage provisioning, ensure you have the following:

  • A running Kubernetes cluster (v1.18+ recommended). This can be a local cluster like Minikube or Kind, or a cloud-managed cluster (EKS, GKE, AKS).
  • kubectl installed and configured to communicate with your cluster. Refer to the official Kubernetes documentation for kubectl installation.
  • Basic understanding of Kubernetes concepts: Pods, Deployments, Persistent Volumes (PVs), and Persistent Volume Claims (PVCs).
  • A Container Storage Interface (CSI) driver installed on your cluster. Most cloud providers automatically install their respective CSI drivers (e.g., AWS EBS CSI driver, GCP Persistent Disk CSI driver, Azure File CSI driver). If you’re running on-premises or a custom setup, you’ll need to install a suitable CSI driver (e.g., Rook-Ceph, Longhorn).
  • Administrator privileges on your Kubernetes cluster to create StorageClass resources.

Step-by-Step Guide to Dynamic Provisioning

Step 1: Understanding Storage Classes

A StorageClass is an API object that defines a “class” of storage. It abstracts away the underlying storage infrastructure, allowing administrators to describe the types of storage available (e.g., “fast SSDs”, “cold HDDs”, “replicated storage”) and their characteristics (provisioner, parameters, reclaim policy). When a developer requests storage via a PersistentVolumeClaim, they don’t need to know the intricate details of the storage system; they simply reference a StorageClass, and Kubernetes handles the rest. This abstraction is key to enabling dynamic provisioning.

Each StorageClass specifies a provisioner, which determines what volume plugin is used for provisioning PVs. For cloud environments, this is typically the cloud provider’s CSI driver (e.g., ebs.csi.aws.com for AWS EBS). It also includes parameters that are specific to the provisioner, such as disk type, IOPS, or replication factor. The reclaimPolicy dictates what happens to the underlying storage volume when the PVC is deleted (Delete or Retain), and volumeBindingMode controls when PVs are provisioned and bound to PVCs.

Let’s examine some default StorageClasses you might find in a cloud-managed Kubernetes cluster.

kubectl get storageclass

NAME            PROVISIONER                     RECLAIMPOLICY   VOLUMEBINDINGMODE   ALLOWVOLUMEEXPANSION   AGE
gp2 (default)   kubernetes.io/aws-ebs           Delete          Immediate           true                   2d
standard        kubernetes.io/gce-pd            Delete          Immediate           true                   3d
azurefile       kubernetes.io/azure-file        Delete          Immediate           true                   1d

(Output will vary based on your cloud provider and cluster configuration)

From the output, you can see different storage classes, each tied to a specific provisioner. For instance, gp2 uses the AWS EBS provisioner, while standard uses the GCP Persistent Disk provisioner. The (default) annotation indicates which StorageClass will be used if a PVC doesn’t explicitly request one.

Step 2: Defining a Custom Storage Class

While default StorageClasses are convenient, defining your own allows for fine-grained control over storage characteristics. You might want to specify a different disk type, file system, or replication settings based on your application’s needs. For example, a database might require high-IOPS SSDs, while a logging service can settle for cost-effective HDDs.

For this guide, we’ll create a StorageClass that provisions AWS EBS gp3 volumes, which offer better performance and cost control than gp2. If you’re not on AWS, you can adapt the provisioner and parameters to your environment’s CSI driver (e.g., pd.csi.storage.gke.io for GCP, disk.csi.azure.com for Azure). Remember to ensure the appropriate CSI driver is installed for your chosen provisioner. For more advanced storage solutions like Ceph, consider projects like Rook, which provides a CSI driver for dynamic provisioning.

# storageclass-gp3.yaml
apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: gp3-fast-storage
provisioner: ebs.csi.aws.com # Change this to your CSI driver if not AWS
parameters:
  type: gp3
  fsType: ext4 # Common filesystem for Linux
  iopsPerGb: "30" # GP3 specific: IOPS per GB (default is 30)
  throughput: "125" # GP3 specific: Throughput in MiB/s (default is 125)
reclaimPolicy: Delete # Deletes the underlying PV when PVC is deleted
volumeBindingMode: Immediate # Provision and bind PV immediately
allowVolumeExpansion: true # Allow PVCs to be resized

Apply this StorageClass to your cluster:

kubectl apply -f storageclass-gp3.yaml

storageclass.storage.k8s.io/gp3-fast-storage created

Verify that your new StorageClass has been created:

kubectl get storageclass gp3-fast-storage

NAME               PROVISIONER            RECLAIMPOLICY   VOLUMEBINDINGMODE   ALLOWVOLUMEEXPANSION   AGE
gp3-fast-storage   ebs.csi.aws.com        Delete          Immediate           true                   2s

You now have a custom StorageClass named `gp3-fast-storage` that applications can request.

Step 3: Creating a Persistent Volume Claim (PVC)

A Persistent Volume Claim (PVC) is a request for storage by a user. It’s similar to a Pod requesting CPU and memory resources. PVCs are namespace-scoped resources and specify the desired size, access mode (e.g., ReadWriteOnce, ReadOnlyMany), and optionally, the StorageClass to use. When a PVC is created, Kubernetes looks for a matching PV. With dynamic provisioning, if no existing PV matches, the StorageClass’s provisioner is invoked to create a new PV for the PVC.

Let’s create a PVC that requests 5Gi of storage using our newly defined `gp3-fast-storage` StorageClass.

# pvc-gp3.yaml
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: my-app-data-pvc
spec:
  storageClassName: gp3-fast-storage # Reference our custom StorageClass
  accessModes:
    - ReadWriteOnce # Can be mounted as read-write by a single node
  resources:
    requests:
      storage: 5Gi # Request 5 Gigabytes of storage

Apply the PVC:

kubectl apply -f pvc-gp3.yaml

persistentvolumeclaim/my-app-data-pvc created

Verify the PVC and the dynamically provisioned PV:

kubectl get pvc my-app-data-pvc

NAME                STATUS   VOLUME                                     CAPACITY   ACCESS MODES   STORAGECLASS       AGE
my-app-data-pvc     Bound    pvc-f8e9b4c0-a1b2-4d3e-8f0c-1a2b3c4d5e6f   5Gi        RWO            gp3-fast-storage   10s

kubectl get pv

NAME                                       CAPACITY   ACCESS MODES   RECLAIM POLICY   STATUS   CLAIM                       STORAGECLASS       REASON   AGE
pvc-f8e9b4c0-a1b2-4d3e-8f0c-1a2b3c4d5e6f   5Gi        RWO            Delete           Bound    default/my-app-data-pvc     gp3-fast-storage            15s

Notice that the PVC `my-app-data-pvc` is now in a `Bound` state, and a corresponding Persistent Volume (PV) with a unique name has been automatically created and bound to it. This PV represents the actual 5Gi EBS `gp3` volume provisioned in AWS. This entire process was handled by Kubernetes and the CSI driver, thanks to the StorageClass.

Step 4: Using the PVC in a Pod/Deployment

Now that we have a PVC, we can use it to provide persistent storage to our applications running in Pods or Deployments. The Pod simply references the PVC by name in its `volumes` section, and Kubernetes takes care of mounting the underlying storage.

Let’s create a simple Nginx Deployment that uses our `my-app-data-pvc` to store its web content.

# nginx-deployment-with-pvc.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-data-app
spec:
  replicas: 1
  selector:
    matchLabels:
      app: nginx-data
  template:
    metadata:
      labels:
        app: nginx-data
    spec:
      containers:
      - name: nginx
        image: nginx:latest
        ports:
        - containerPort: 80
        volumeMounts:
        - name: nginx-persistent-storage
          mountPath: /usr/share/nginx/html # Nginx serves content from here
      volumes:
      - name: nginx-persistent-storage
        persistentVolumeClaim:
          claimName: my-app-data-pvc # Reference our PVC

Apply the Deployment:

kubectl apply -f nginx-deployment-with-pvc.yaml

deployment.apps/nginx-data-app created

Verify the Pod is running and the PVC is mounted:

kubectl get pod -l app=nginx-data

NAME                               READY   STATUS    RESTARTS   AGE
nginx-data-app-7c7f7d7c7c-abcde    1/1     Running   0          15s

Inspect the Pod’s description to confirm the volume mount:

kubectl describe pod -l app=nginx-data | grep -A 5 "Volumes:"

Volumes:
  nginx-persistent-storage:
    Type:       PersistentVolumeClaim (a reference to a PersistentVolumeClaim in the same namespace)
    ClaimName:  my-app-data-pvc
    ReadOnly:   false
  kube-api-access-abcde:
    Type:                    Projected (a volume that contains injected data from multiple sources)
    TokenExpirationSeconds:  3607
    ConfigMapName:           <nil>
    SecretName:              <nil>

You can further test by exec’ing into the Pod and writing some data to the mounted path.

POD_NAME=$(kubectl get pod -l app=nginx-data -o jsonpath='{.items[0].metadata.name}')
kubectl exec -it $POD_NAME -- sh -c 'echo "Hello from Kubezilla!" > /usr/share/nginx/html/index.html'

Now, if you expose your Nginx service (e.g., via a LoadBalancer or NodePort) and access it, you should see “Hello from Kubezilla!”. Even if the Pod restarts or is rescheduled to a different node, the data will persist because it’s stored on the underlying EBS volume. This resilience is crucial for stateful applications. For more advanced networking and traffic management for your services, consider exploring the Kubernetes Gateway API.

Production Considerations

When deploying dynamic storage provisioning in a production environment, several factors need careful consideration to ensure reliability, performance, and cost-effectiveness.

  • CSI Driver Stability and Updates: Ensure your CSI driver is stable, actively maintained, and kept up-to-date. Outdated or buggy drivers can lead to storage issues, data corruption, or downtime. Always check the official documentation for your specific CSI driver (e.g., CSI External Provisioner).
  • Reclaim Policy: The `reclaimPolicy` of your StorageClass is critical.
    • `Delete`: Automatically deletes the underlying physical storage volume when the PVC is deleted. This is convenient for temporary storage but can lead to data loss if not managed carefully.
    • `Retain`: Retains the underlying physical storage volume even after the PVC is deleted. This prevents accidental data loss but requires manual cleanup of unused PVs. Choose `Retain` for critical data where manual intervention is preferred for deletion.
  • Volume Binding Mode:
    • `Immediate`: Provisions and binds a PV as soon as the PVC is created. This is the default and works well for most cases.
    • `WaitForFirstConsumer`: Delays PV provisioning until a Pod is actually scheduled that uses the PVC. This is useful for topologies where storage needs to be provisioned in a specific availability zone or node, ensuring the PV is created in the correct location for the Pod. This is particularly important for cloud providers that have zonal storage.
  • Volume Expansion: Set `allowVolumeExpansion: true` in your StorageClass if you anticipate needing to increase the size of your volumes without downtime. Not all CSI drivers support this, so verify compatibility.
  • Backup and Disaster Recovery: Dynamic provisioning handles volume creation, but not backups. Implement a robust backup strategy for your persistent data. Tools like Velero can help with backing up and restoring Kubernetes resources, including PVs.
  • Monitoring: Monitor your storage usage, IOPS, and latency. Cloud providers offer metrics for their storage services, and Kubernetes itself provides basic metrics. Integrating with eBPF Observability tools like Hubble can give deeper insights into network and storage performance at a granular level.
  • Cost Management: Different StorageClasses can have vastly different costs. Monitor your cloud storage bills and ensure applications are using the most cost-effective storage type for their needs. Tools like Karpenter can help optimize node costs, but storage costs are also a significant factor.
  • Security: Ensure that your storage volumes are encrypted at rest and in transit. Most cloud providers offer encryption options for their block storage. Also, consider Kubernetes Network Policies to restrict traffic to your stateful applications, adding another layer of security. For supply chain security, integrating solutions like Sigstore and Kyverno can help ensure the integrity of your container images.
  • Access Modes: Understand the implications of different access modes (ReadWriteOnce, ReadOnlyMany, ReadWriteMany). Most block storage (like EBS) only supports ReadWriteOnce, meaning it can only be mounted by one node at a time. File storage (like NFS, Azure Files, EFS) often supports ReadWriteMany, allowing multiple nodes to access the same volume concurrently.

Troubleshooting

Here are some common issues you might encounter with dynamic storage provisioning and their solutions:

  1. PVC stuck in ‘Pending’ state:

    Explanation: This is the most common issue. It means Kubernetes couldn’t provision a PV for your PVC.

    Solution:

    • Check StorageClass: Ensure the `storageClassName` in your PVC matches an existing StorageClass exactly (case-sensitive). Run `kubectl get storageclass`.
    • Check CSI Driver: Verify that the provisioner specified in the StorageClass (e.g., `ebs.csi.aws.com`) is correctly installed and running in your cluster. Check the logs of the CSI driver pods (usually in the `kube-system` namespace or a dedicated CSI namespace).
    • Events: Use `kubectl describe pvc <pvc-name>` to check the Events section. It often provides specific error messages from the provisioner. Look for messages like “no PersistentVolume available for this claim” or errors related to the cloud provider API.
    • Cloud Provider Limits: You might have hit a quota limit for volumes in your cloud provider account. Check your cloud provider’s console for any service limits.
    • Permissions: The Kubernetes service account used by the CSI driver might lack the necessary IAM permissions to create volumes in your cloud provider.
  2. Pod stuck in ‘ContainerCreating’ or ‘Pending’ due to volume issues:

    Explanation: The Pod can’t start because it can’t mount the PV associated with the PVC.

    Solution:

    • Check PVC Status: First, ensure the PVC is `Bound`. If it’s `Pending`, refer to the previous troubleshooting step.
    • Pod Events: Run `kubectl describe pod <pod-name>` and check the Events section. Look for messages like “FailedAttachVolume”, “FailedMount”, or “Volume not found”.
    • Node Connectivity: Ensure the node where the Pod is scheduled has network connectivity to the storage backend and that the CSI node driver is running correctly on that node.
    • Filesystem issues: Sometimes, the filesystem on the volume might be corrupted or incompatible. The CSI driver usually handles formatting, but custom scenarios might break this.
  3. Volume Expansion Fails:

    Explanation: You tried to resize a PVC, but the underlying volume didn’t expand.

    Solution:

    • `allowVolumeExpansion`: Ensure `allowVolumeExpansion: true` is set in the StorageClass.
    • CSI Driver Support: Verify that your specific CSI driver and its version support online volume expansion. Not all do.
    • Filesystem Resizing: The filesystem on the volume also needs to be expanded. Most CSI drivers handle this automatically, but in some cases, you might need to manually resize the filesystem inside the Pod after the volume has expanded.
    • PVC Status: After modifying the PVC, check its status with `kubectl describe pvc <pvc-name>`. It might show an `FileSystemResizePending` condition. The Pod using the PVC might need to be restarted for the filesystem resize to take effect.
  4. Data Loss after PVC Deletion:

    Explanation: You deleted a PVC and the data on the underlying volume disappeared.

    Solution:

    • Reclaim Policy: This is almost always due to the StorageClass having a `reclaimPolicy: Delete`. If you need to retain data after PVC deletion, change the StorageClass’s `reclaimPolicy` to `Retain`. Be aware that this means you’ll need to manually delete the underlying volume.
    • Backup Strategy: Always have a robust backup strategy in place, regardless of the reclaim policy.
  5. Cannot delete PVC/PV (stuck in ‘Terminating’):

    Explanation: The PVC or PV is stuck in a `Terminating` state and won’t go away.

    Solution:

    • Finalizers: This usually happens if the underlying volume or resource in the cloud provider couldn’t be deleted by the CSI driver. Check the PV’s `finalizers` (`kubectl get pv <pv-name> -o yaml`). If it has finalizers like `external-provisioner.volume.kubernetes.io/finalizer`, it means the CSI controller is trying to delete the cloud resource.
    • CSI Driver Logs: Check the logs of your CSI driver pods for errors related to volume deletion.
    • Cloud Provider Console: Manually check your cloud provider’s console to see if the volume still exists. If it does, there might be a lock or an issue preventing its deletion.
    • Manual Finalizer Removal (Last Resort): If all else fails and you’ve confirmed the underlying volume is gone (or you’ve manually deleted it), you can cautiously remove the finalizer from the PV. WARNING: Only do this if you are absolutely sure the underlying resource is gone or you accept the risk of orphan resources. 
      kubectl edit pv <pv-name> # Remove finalizers field

FAQ Section

Q1: What is the difference between a Persistent Volume (PV) and a Persistent Volume Claim (PVC)?

A1: A Persistent Volume (PV) is a cluster-wide resource that represents a piece of storage in the cluster. It’s like a physical hard drive. A Persistent Volume Claim (PVC) is a request for storage by a user, similar to a Pod requesting CPU/memory. It’s like a request for a specific amount and type of storage. A PVC consumes a PV.

Q2: Can I resize a Persistent Volume Claim (PVC) after it has been created?

A2: Yes, if the StorageClass has `allowVolumeExpansion: true` and the underlying CSI driver supports it. You can edit the PVC to request a larger size, and Kubernetes will attempt to expand the underlying volume and its filesystem. Note that shrinking volumes is generally not supported.

Q3: What happens if I delete a Pod that is using a PVC? Does the data get deleted?

A3: No, deleting a Pod does NOT delete the PVC or the underlying PV/data. The PVC and PV are independent resources. The data will persist and can be re-attached to a new Pod referencing the same PVC. The data is only deleted if the PVC itself is deleted, and the StorageClass has a `reclaimPolicy` of `Delete`.

Q4: How do I choose the right `reclaimPolicy` for my StorageClass?

A4: Choose `Delete` for temporary, non-critical data where you want automatic cleanup. Choose `Retain` for critical data that you never want to be automatically deleted, even if the PVC is removed. `Retain` requires manual cleanup of the underlying PV and cloud volume, but prevents accidental data loss. For highly sensitive data, consider integrating with Sigstore and Kyverno for policy enforcement.

Q5: Can multiple Pods share the same Persistent Volume?

A5: It depends on the `accessModes` specified in the PVC and supported by the StorageClass/CSI driver.

  • `ReadWriteOnce` (RWO): The volume can be mounted as read-write by a single node. Most block storage (e.g., AWS EBS, GCP PD) supports this.
  • `ReadOnlyMany` (ROX): The volume can be mounted as read-only by many nodes.
  • `ReadWriteMany` (RWX): The volume can be mounted as read-write by many nodes. This is typically supported by network file systems (e.g., NFS, AWS EFS, Azure Files).

For shared storage needs, ensure your StorageClass and CSI driver support `ReadWriteMany` access mode.

Cleanup Commands

To clean up the resources created in this guide:

1. Delete the Deployment:

kubectl delete deployment nginx-data-app

2. Delete the Persistent Volume Claim (PVC). This will also trigger the deletion of the associated Persistent Volume (PV) and the underlying cloud volume, because our `gp3-fast-storage` StorageClass has `reclaimPolicy: Delete`.

kubectl delete pvc my-app-data-pvc

3. Delete the custom StorageClass:

kubectl delete storageclass gp3-fast-storage

Verify all resources are gone:

kubectl get deployment,pvc,pv,storageclass

You should no longer see `nginx-data-app`, `my-app-data-pvc`, the dynamically created PV, or `gp3-fast-storage`.

Next Steps / Further Reading

Congratulations! You’ve successfully implemented dynamic storage provisioning in Kubernetes. This is a fundamental skill for running stateful applications. Here are some areas to explore next:

  • StatefulSets: For managing stateful applications with stable network identities and ordered deployments/scaling, Kubernetes StatefulSets are essential. They are designed to work seamlessly with PVCs for persistent storage.
  • Shared Storage (RWX): Explore CSI drivers that support `ReadWriteMany` access mode, such as AWS EFS CSI driver, Azure Files CSI driver, or CephFS via Rook, for scenarios where multiple pods need concurrent read-write access to the same volume.
  • Local Persistent Volumes: For performance-critical applications, consider Local Persistent Volumes, which use local storage on a node. This requires careful management as the PV is tied to a specific node.
  • Snapshot and Restore: Learn about Volume Snapshots, which allow you to create point-in-time backups of your persistent volumes.
  • Advanced Storage Solutions: Dive deeper into open-source storage solutions like Rook (for Ceph) or Longhorn, which offer enterprise-grade storage features directly within your Kubernetes cluster, including replication, snapshots, and disaster recovery.
  • Service Mesh for Stateful Workloads: For complex microservices architectures, a service mesh like Istio Ambient Mesh can provide advanced traffic management, security, and observability for your stateful applications, even those relying on persistent storage.

Conclusion

Dynamic storage provisioning with Kubernetes Storage Classes fundamentally changes how we manage persistent data in containerized environments. By abstracting the underlying storage infrastructure, it empowers developers to self-service their storage needs while giving operators powerful tools to define and control storage policies. This automation reduces operational overhead, improves agility, and ensures that stateful applications can run reliably and efficiently on Kubernetes. As you continue your Kubernetes journey, mastering storage concepts like Storage Classes will be invaluable for building robust, production-ready applications.

Leave a comment