BZ-1699212: Included instructions for expanding persistent volumes.

_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
 ---

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.

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 <pvc_name>
+----
+
+. 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.

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.

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]