
The allowVolumeExpansion field on a StorageClass lets supported PVCs request more capacity in place. Stateful containers are common in production: CNCF's 2020 survey found 55% of respondents running them. This guide covers the workflow: validate the StorageClass and CSI driver, raise the PVC request, monitor the resize, and verify the result.
Key Takeaways
allowVolumeExpansion: truepermits growth but never resizes automatically.- Edit the PVC's
spec.resources.requests.storage, never the PV capacity. - Support depends on the CSI driver, backend, filesystem, quotas, and version.
- Expansion is one-way. Shrinking means migrating to a new volume.
What Is allowVolumeExpansion in Kubernetes?
Kubernetes storage vocabulary
A volume is a directory of data accessible to the containers in a Pod. Persistent storage involves three objects:
- PVC: the application's claim for storage
- PV: the provisioned storage that satisfies the claim
- StorageClass: the definition of how storage gets created
allowVolumeExpansion is a top-level StorageClass field, alongside provisioner, not inside parameters. It is an opt-in.
The scope and limits of the setting
Setting it to true does not resize anything. A user or controller must still submit a larger spec.resources.requests.storage, and the provisioner must support expansion.
The field does not allow:
- Shrinking volumes
- Filesystem changes
- Performance tuning
Related Kubernetes storage features
Capacity is separate from attributes like IOPS or throughput. Those belong to VolumeAttributesClass, which went GA in v1.34.
Use current CSI provisioners (ebs.csi.aws.com, disk.csi.azure.com, pd.csi.storage.gke.io), not in-tree values from older docs. The in-tree AWS and Azure plugins were removed in v1.27, and the GCE plugin in v1.28.
How Kubernetes Handles PVC Expansion
The expansion request
You raise the PVC's spec.resources.requests.storage. The new value must exceed the current one. Kubernetes validates the request, and the CSI external-resizer sidecar calls ControllerExpandVolume against the backend.
Storage backend and PV updates
Once the backend grows the volume, the PV capacity and PVC status update. Provider limits, quotas, volume state, and rate limits can delay or reject the operation. On AWS, EBS allows up to four modifications per rolling 24 hours, and earlier modifications must be completed.
Node-side and filesystem expansion
Growing the block device is only half the job. The kubelet invokes the CSI node plugin's NodeExpandVolume, which typically resizes the filesystem. Until that finishes, the PVC may show FileSystemResizePending.
The resizer message says it is waiting for a Pod (re)start. That does not mean a restart is always required. In-use expansion is stable since v1.24 and often completes without recreating the Pod.

Filesystem and block volume modes
| Mode | What happens |
|---|---|
Filesystem (default) |
Mounted as a directory. XFS, Ext3, and Ext4 support expansion. |
Block |
Raw device. Do not assume a filesystem resize. |
Confirm that your filesystem and driver support online expansion before relying on it.
Availability expectations
Support varies by provider, driver, filesystem, and mount state. On AKS, online expansion works up to 4 TiB. Standard HDD, Standard SSD, and Premium SSD beyond that require detaching the disk and scaling the workload to zero. Premium SSD v2 and Ultra Disk expand online beyond 4 TiB.

Don't promise zero downtime universally. Test in a non-production cluster first.
Prerequisites and StorageClass Configuration
Inspect the current StorageClass
Find the PVC's class, then inspect it:
kubectl get pvc <name> -o yaml
kubectl get storageclass <class> -o yaml
Confirm each of the following:
allowVolumeExpansion: true- Correct CSI
provisioner - Expected
volumeBindingMode - Provider-specific parameters
Confirm CSI and platform support
Check current Kubernetes, managed-cluster, and driver documentation rather than trusting version claims in old posts. These components must all support expansion:
- Controller-side resizer
- Node plugin
- IAM permissions
- Backend quotas
Provisioners differ by platform. EKS Auto Mode uses ebs.csi.eks.amazonaws.com and creates no StorageClass automatically, while regular EKS uses ebs.csi.aws.com.
Check how the PVC was provisioned
Standard workflows assume a dynamically provisioned PVC whose class opted in. Static PVs may have extra restrictions. Changing the default StorageClass does not touch bound claims, because retroactive default assignment applies only to unbound PVCs with an unset storageClassName.
Create or review an expandable StorageClass
apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
name: expandable
provisioner: <current-csi-provisioner>
allowVolumeExpansion: true
volumeBindingMode: WaitForFirstConsumer
Warning: Don't copy an AWS, Azure, or Google Cloud provisioner value without checking current provider docs. Creating a new class does not migrate existing data.
Prepare for the operation
- Confirm the application actually needs the capacity
- Check namespace ResourceQuotas and cloud quotas
- Verify a recent backup or snapshot
- Test the driver and filesystem combination outside production
- Record the change through GitOps or your change process
ResourceQuota limits apply to requested capacity, and violating requests get a 403 Forbidden.
How to Expand a PVC Step by Step
1. Identify the PVC and record its state
kubectl get pvc <pvc> -o yaml
kubectl get pv <pv> -o yaml
kubectl describe pvc <pvc>
Record these details before you change anything:
- StorageClass and bound PV
- Requested storage and current capacity
- Volume mode and events
- Every workload using the PVC
2. Increase the PVC storage request
kubectl patch pvc <pvc> --type=merge \
-p '{"spec":{"resources":{"requests":{"storage":"<larger-size>"}}}}'
You can also change the manifest declaratively or through GitOps. Never edit the PV to match the new size. If PV and PVC capacities already match, Kubernetes may conclude no resize is needed.
3. Monitor the resize operation
kubectl get pvc <pvc> -w
kubectl describe pvc <pvc>
Watch for the Resizing condition and the VolumeResizing event. A VolumeResizeFailed event signals rejection, for example when a driver supports only offline expansion and the volume is in use. The resizer retries with exponential backoff, so slow is not always stuck.

4. Verify the backend and mounted storage
Wait for PVC status.capacity to show the new size, not just the request. Then check inside the Pod:
kubectl exec -it <pod> -- df -h <mount-path>
For Block volumes, use the workload's or OS's block-device tools instead.
5. Handle any required Pod restart safely
Restart only if the PVC reports a filesystem resize condition that doesn't clear, or your driver docs require it. When a restart is required:
- Use a controlled rollout
- Respect PodDisruptionBudgets (direct Pod deletion bypasses them)
- Watch health checks and re-verify afterward
StatefulSets need extra care. GKE documentation states that editing volumeClaimTemplates directly returns an error. The workaround is to expand each PVC, then delete the StatefulSet with --cascade=orphan and reapply the updated template.
Troubleshooting and Operational Best Practices
Diagnose rejected or stalled expansion requests
| Symptom | Likely cause |
|---|---|
| Request rejected | allowVolumeExpansion disabled or legacy provisioner |
| 403 on patch | ResourceQuota exceeded |
| No progress | Provider limit, rate limit, or CSI controller error |
| Invalid size error | New value not larger than current |
Work through diagnostics in this order before patching again:
- PVC events
- CSI controller and node-plugin logs
- StorageClass inspection
- Provider-side volume status
Resolve filesystem resize conditions
FileSystemResizePending means node-side work is still outstanding. Confirm the backend resize finished, then check the Pod and mount state. If the driver supports only offline filesystem expansion, a controlled restart or remount may be needed.
Don't edit PV capacity or resubmit requests repeatedly. That hides the real failure. Since v1.34, RecoverVolumeExpansionFailure is GA: a corrected request may be smaller than the failed target but must stay above status.capacity.
Operate expansion safely at enterprise scale
- Keep backups current before any resize
- Alert on PVC utilization before it fills
- Maintain tested runbooks per driver and filesystem
- Route changes through GitOps
- Document that reducing a PVC later means migrating to a new volume
For enterprises managing many block volumes across AWS, Azure, and Google Cloud, one-off PVC edits don't scale.
Lucidity offers an optional layer for visibility and autonomous optimization. Lumen shows every disk with tiering and idle-disk recommendations, and AutoScaler expands and shrinks disks with zero downtime. StorageClass and CSI compatibility remain prerequisites for the Kubernetes side.
Frequently Asked Questions
What is a volume in Kubernetes?
A volume is a directory of data accessible to a Pod's containers. Persistent storage comes from a PV, which a PVC claims.
What does allowVolumeExpansion do in Kubernetes?
It lets supported PVCs of that StorageClass request more capacity. It triggers nothing by itself.
Can Kubernetes shrink a PVC?
No. Expansion is one-way. To reduce capacity, provision a smaller volume and migrate the data.
Does expanding a PVC cause downtime or restart a pod?
It depends on the CSI driver, provider, disk type, filesystem, and mount state. Many expansions are online, while others need a controlled restart.
Why is my PVC stuck in FileSystemResizePending?
Node-side filesystem expansion hasn't finished. Check Pod and mount state, events, and whether your driver supports online resizing.
How can I verify that a PVC expansion completed?
Confirm PVC status.capacity and PV capacity, review events and conditions, then run df -h in the Pod (or a block-device check for Block volumes).