From e7af36e1c18db2988afd4fd107ff503382facbb2 Mon Sep 17 00:00:00 2001 From: Christian Huffman Date: Mon, 22 Apr 2019 15:43:46 -0400 Subject: [PATCH] BZ-1699212: Included instructions for expanding persistent volumes. --- _topic_map.yml | 2 + ...torage-expanding-add-volume-expansion.adoc | 28 ++++++++++ modules/storage-expanding-filesystem-pvc.adoc | 56 +++++++++++++++++++ .../storage-expanding-recovering-failure.adoc | 26 +++++++++ storage/expanding-persistent-volumes.adoc | 11 ++++ 5 files changed, 123 insertions(+) create mode 100644 modules/storage-expanding-add-volume-expansion.adoc create mode 100644 modules/storage-expanding-filesystem-pvc.adoc create mode 100644 modules/storage-expanding-recovering-failure.adoc create mode 100644 storage/expanding-persistent-volumes.adoc diff --git a/_topic_map.yml b/_topic_map.yml index 948493b773..7af29942e5 100644 --- a/_topic_map.yml +++ b/_topic_map.yml @@ -361,6 +361,8 @@ Topics: File: persistent-storage-csi - Name: Persistent storage using OpenStack Manila File: persistent-storage-manila +- Name: Expanding persistent volumes + File: expanding-persistent-volumes - Name: Dynamic provisioning File: dynamic-provisioning --- diff --git a/modules/storage-expanding-add-volume-expansion.adoc b/modules/storage-expanding-add-volume-expansion.adoc new file mode 100644 index 0000000000..8251cc1484 --- /dev/null +++ b/modules/storage-expanding-add-volume-expansion.adoc @@ -0,0 +1,28 @@ +// Module included in the following assemblies +// +// * storage/expanding-persistent-volumes.adoc + +[id="add-volume-expansion-{context}"] += Enabling volume expansion support + +Before you can expand persistent volumes, the StorageClass must +have the `allowVolumeExpansion` field set to `true`. + +.Procedure + +* Edit the StorageClass and add the `allowVolumeExpansion` attribute. +The following example demonstrates adding this line at the bottom +of the StorageClass's configuration. ++ +[source,yaml] +---- +apiVersion: storage.k8s.io/v1 +kind: StorageClass +... +parameters: + type: gp2 +reclaimPolicy: Delete +allowVolumeExpansion: true <1> +---- +<1> Setting this attribute to `true` allows PVCs to be +expanded after creation. diff --git a/modules/storage-expanding-filesystem-pvc.adoc b/modules/storage-expanding-filesystem-pvc.adoc new file mode 100644 index 0000000000..5ad1d9af02 --- /dev/null +++ b/modules/storage-expanding-filesystem-pvc.adoc @@ -0,0 +1,56 @@ +// Module included in the following assemblies: +// +// * storage/expanding-persistent-volume.adoc + +[id="expanding-pvc-filesystem-{context}"] += Expanding Persistent Volume Claims (PVC) with a file system + +Expanding PVCs based on volume types that need file system resizing, +such as GCE, PD, EBS, and Cinder, is a two-step process. +This process involves expanding volume objects in the cloud provider, and +then expanding the file system on the actual node. + +Expanding the file system on the node only happens when a new pod is started +with the volume. + +.Prerequisites + +* The controlling StorageClass must have `allowVolumeExpansion` set +to `true`. + +.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. ++ +[source,yaml] +---- +kind: PersistentVolumeClaim +apiVersion: v1 +metadata: + name: ebs +spec: + storageClass: "storageClassWithFlagSet" + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 8Gi <1> +---- +<1> Updating `spec.resources.requests` to a larger amount will expand +the PVC. + +. Once the cloud provider object has finished resizing, the PVC is set to +`FileSystemResizePending`. The following command is used to check +the condition: ++ +---- +$ oc describe pvc +---- + +. When the cloud provider object has finished resizing, the +persistent volume object reflects the newly requested size in +`PersistentVolume.Spec.Capacity`. At this point, you can create or +re-create a new pod from the PVC to finish the file system resizing. +Once the pod is running, the newly requested size is available and the +`FileSystemResizePending` condition is removed from the PVC. diff --git a/modules/storage-expanding-recovering-failure.adoc b/modules/storage-expanding-recovering-failure.adoc new file mode 100644 index 0000000000..31d6989c5f --- /dev/null +++ b/modules/storage-expanding-recovering-failure.adoc @@ -0,0 +1,26 @@ +// Module included in the following assemblies +// +// * storage/expanding-persistent-volumes.adoc + +[id="expanding-recovering-from-failure-{context}"] += Recovering from Failure when Expanding Volumes + +If expanding underlying storage fails, the {product-title} administrator +can manually recover the Persistent Volume Claim (PVC) state and cancel +the resize requests. Otherwise, the resize requests are continuously +retried by the controller without administrator intervention. + +.Procedure + +. Mark the persistent volume (PV) that is bound to the PVC with the +`Retain` reclaim policy. This can be done by editing the PV and changing +`persistentVolumeReclaimPolicy` to `Retain`. +. Delete the PVC. This will be recreated later. +. To ensure that the newly created PVC can bind to the PV marked `Retain`, +manually edit the PV and delete the `claimRef` entry from the PV specs. +This marks the PV as `Available`. +. Re-create 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. diff --git a/storage/expanding-persistent-volumes.adoc b/storage/expanding-persistent-volumes.adoc new file mode 100644 index 0000000000..13915f8819 --- /dev/null +++ b/storage/expanding-persistent-volumes.adoc @@ -0,0 +1,11 @@ +[id="expanding-persistent-volumes"] += Expanding persistent volumes +include::modules/common-attributes.adoc[] +:context: expanding-persistent-volumes +toc::[] + +include::modules/storage-expanding-add-volume-expansion.adoc[leveloffset=+1] + +include::modules/storage-expanding-filesystem-pvc.adoc[leveloffset=+1] + +include::modules/storage-expanding-recovering-failure.adoc[leveloffset=+1]