Expanding persistent volumes | Storage

Expand persistent volumes to increase storage capacity as your application data grows. You can resize volumes without recreating volumes or disrupting running workloads.

Enabling volume expansion support
Expanding CSI volumes
Expanding FlexVolume with a supported driver
Expanding local volumes
Expanding persistent volume claims (PVCs) with a file system
Recovering from failure when expanding volumes
Viewing the status of volume resize
Additional resources

Enabling volume expansion support

To enable volume expansion, the StorageClass object must have the allowVolumeExpansion field set to true. This prerequisite configuration allows persistent volume claims (PVCs) to be expanded after creation as your storage needs grow.

Procedure

Edit the StorageClass object and add the allowVolumeExpansion attribute by running the following command:
```
$ oc edit storageclass <storage_class_name>
```
Enter the name of storage class in <storage_class_name>.

The following example shows adding this line at the bottom of the storage class configuration.
Example storage class YAML file with allowVolumeExpansion field set to true
```
apiVersion: storage.k8s.io/v1
kind: StorageClass
...
parameters:
  type: gp2
reclaimPolicy: Delete
allowVolumeExpansion: true
```
- parameters.allowVolumeExpansion: Setting this field to true allows persistent volume claims (PVCs) to be expanded after creation.

Expanding CSI volumes

You can use the Container Storage Interface (CSI) to expand storage volumes after they have already been created.

Shrinking persistent volumes (PVs) is not supported.

Prerequisites

The underlying CSI driver supports resize.

For information about which CSI drivers support resizing, see under the Additional resources section "CSI drivers supported by OKD".
Dynamic provisioning is used.
The controlling StorageClass object has allowVolumeExpansion set to true.

For more information, see section Enabling volume expansion support.

Procedure

For the persistent volume claim (PVC), set .spec.resources.requests.storage to the desired new size.

Verification

To confirm that the resize is finished, look at the status.conditions field of the PVC . OKD adds the Resizing condition to the PVC during expansion, which is removed after expansion completes.

Expanding FlexVolume with a supported driver

To expand your FlexVolume storage capacity and meet growing data needs, update the storage request in your persistent volume claim (PVC). This increases capacity for existing volumes without recreating them.

Similar to other volume types, FlexVolume volumes can also be expanded when in use by a pod.

Because OKD does not support installation of FlexVolume plugins on control plane nodes, it does not support control plane expansion of FlexVolume.

Prerequisites

The underlying volume driver supports resize.

For information about which CSI drivers support resizing, see under the Additional resources section "CSI drivers supported by OKD".
The driver is set with the RequiresFSResize capability to true. The FlexVolume can then be expanded after restarting the pod.
Dynamic provisioning is used.
The controlling StorageClass object has allowVolumeExpansion set to true.

For more information, see section Enabling volume expansion support.

Procedure

To use resizing in the FlexVolume plugin, you must implement the ExpandableVolumePlugin interface using these methods:
- RequiresFSResize
  
  If true, updates the capacity directly. If false, calls the ExpandFS method to finish the filesystem resize.
- ExpandFS
  
  If true, calls ExpandFS to resize filesystem after physical volume expansion is done. The volume driver can also perform physical volume resize together with filesystem resize.

Expanding local volumes

To expand your Local Storage Operator (LSO) storage capacity and meet growing data needs, update the storage request in your persistent volume (PV) and persistent volume claim (PVC). This increases capacity for existing volumes without recreating them.

Procedure

Expand the underlying devices. Ensure that appropriate capacity is available on these devices.
Update the corresponding PV objects to match the new device sizes by editing the .spec.capacity field of the PV.
For the storage class that is used for binding the PVC to PV, set the allowVolumeExpansion field to true.
For the PVC, set .spec.resources.requests.storage to match the new size.

Result

Kubelet should automatically expand the underlying file system on the volume, if necessary, and update the status field of the PVC to reflect the new size.

Expanding persistent volume claims (PVCs) with a file system

To expand your storage capacity and meet growing data needs, you can resize existing volumes without recreating them.

Expanding persistent volume claims (PVCs) based on volume types that need file system resizing, such as Google Cloud Platform (GCP) persistent disk (PD), AWS Elastic Block Storage (EBS), and Cinder, is a two-step process. First, expand the volume objects in the cloud provider. Second, expand the file system on the node.

Expanding the file system on the node only happens when a new pod is started with the volume.

Prerequisites

The controlling storage class has the allowVolumeExpansion field set to true.

For more information, see section Enabling volume expansion support.

Procedure

Edit the PVC and request a new size by editing spec.resources.requests. For example, the following expands the ebs PVC to 8 Gi:

Example PVC YAML file

kind: PersistentVolumeClaim
apiVersion: v1
metadata:
  name: ebs
spec:
  storageClass: "storageClassWithFlagSet"
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 8Gi

Where updating spec.resources.requests to a larger amount expands the PVC.

Verification

After the cloud provider object has finished resizing, the PVC is set to FileSystemResizePending.

Check the condition by running the following command:
```
$ oc describe pvc <pvc_name>
```

Next steps

When the cloud provider object has finished resizing, the PersistentVolume object reflects the newly requested size in PersistentVolume.Spec.Capacity. You can now create or recreate a new pod from the PVC to finish the file system resizing. After the pod is running, the newly requested size is available and the FileSystemResizePending condition is removed from the PVC.

Recovering from failure when expanding volumes

If a resize request fails or remains in a pending state, you can try again by entering a different resize value in .spec.resources.requests.storage for the persistent volume claim (PVC). The new value must be larger than the original volume size.

If entering another smaller resize value in .spec.resources.requests.storage for the PVC does not work, use the following procedure to recover.

Procedure

Mark the persistent volume (PV) that is bound to the PVC with the Retain reclaim policy. Change the persistentVolumeReclaimPolicy field to Retain.
Delete the PVC.
Manually edit the PV and delete the claimRef entry from the PV specification to ensure that the newly created PVC can bind to the PV marked Retain. This marks the PV as Available.
Recreate the PVC in a smaller size, or a size that can be allocated by the underlying storage provider.
Set the volumeName field of the PVC to the name of the PV. This binds the PVC to the provisioned PV only.
Restore the reclaim policy on the PV.

Viewing the status of volume resize

The volume resize status shows the progress of persistent volume claim (PVC) expansion operations. By checking this status you can confirm that volume expansions are progressing correctly and troubleshoot stuck or failed resizes.

You can view the status of volume resizing with the pvc.Status.AllocatedResourceStatus field. If a user changes the size of their PVCs, the pvc.Status.AllocatedResourceStatus field allows resource quota to be tracked accurately.

The possible values for pvc.Status.AllocatedResourceStatus are:

ControllerResizeInProgress: Controller resize attempt is in progress.
ControllerResizeFailed: Controller resize attempt failed.
NodeResizeInProgress: Node resize attempt is in progress.
NodeResizeFailed: Node resize attempt failed.

For a typical block volume, the field transitions between ControllerResizeInProgress, NodeResizePending, NodeResizeInProgress, and then nil/empty when the volume expansion finishes.

Additional resources

CSI drivers supported by OKD