Merge pull request #8603 from openshift-cherrypick-robot/cherry-pick-8124-to-enterprise-3.10

[enterprise-3.10] Add new topic for expanding PV size

Author: Traci Morrison

_topic_map.yml

@@ -866,6 +866,9 @@ Topics:
   File: volumes
 - Name: Using Persistent Volumes
   File: persistent_volumes
+- Name: Expanding Persistent Volumes
+  File: expanding_persistent_volumes
+  Distros: openshift-enterprise,openshift-origin
 - Name: Storage Classes
   File: storage_classes
   Distros: openshift-online

dev_guide/expanding_persistent_volumes.adoc

@@ -0,0 +1,118 @@
+[[expanding_persistent_volumes]]
+= Expanding Persistent Volumes
+{product-author}
+{product-version}
+:data-uri:
+:icons:
+:experimental:
+:toc: macro
+:toc-title:
+
+toc::[]
+
+[[enabling_expansion_pvc]]
+== Enabling Expansion of Persistent Volume Claims
+
+Volume expansion is a Technology Preview feature, and hence, is not enabled by
+default in your {product-title} {product-version} cluster. There may be other reasons that
+{product-title} administrators wish to enable this feature for certain use
+cases.
+
+[NOTE]
+====
+For more information on Red Hat Technology Preview features support scope,  see
+https://access.redhat.com/support/offerings/techpreview/. 
+====
+
+To allow expansion of persistent volume claims (PVC) by {product-title} users,
+{product-title} administrators must create or update a StorageClass with
+`allowVolumeExpansion` set to `true`. Only PVCs created from that class are
+allowed to expand.
+
+Apart from that, {product-title} administrators must enable the
+`ExpandPersistentVolumes` feature flag and turn on the
+`PersistentVolumeClaimResize` admission controller. Refer to 
+xref:../architecture/additional_concepts/admission_controllers.adoc#architecture-additional-concepts-admission-controllers[Admission Controllers]
+for more information on the `PersistentVolumeClaimResize` admission controller.
+
+To enable the feature gate, set `ExpandPersistentVolumes` to `true` across the system:
+
+. Configure node-config.yaml on all nodes in the cluster:
++
+----
+# cat /etc/origin/node/node-config.yaml
+...
+kubeletArguments:
+...
+  feature-gates:
+  - ExpandPersistentVolumes=true
+# systemctl restart atomic-openshift-node
+----
+
+. Enable the `ExpandPersistentVolumes` feature gate on the master API:
++
+----
+# cat /etc/origin/master/master-config.yaml
+...
+kubernetesMasterConfig:
+  apiServerArguments:
+  ...
+  feature-gates:
+  - ExpandPersistentVolumes=true
+
+# systemctl restart atomic-openshift-master-api
+----
+
+[[expanding_glusterfs_pvc]]
+== Expanding GlusterFS-Based Persistent Volume Claims
+
+Expanding GlusterFS volumes is easiest. Once the  {product-title} administrator
+has created a StorageClass with `allowVolumeExpansion` set to `true`, you can
+create a PVC from that class, and afterwards, whenever needed, you can edit the
+PVC and request a new size. 
+
+For example:
+
+----
+kind: PersistentVolumeClaim
+apiVersion: v1
+metadata:
+  name: gluster-mysql
+spec: 
+  storageClass: "storageClassWithFlagSet" 
+  accessModes:
+    - ReadWriteOnce
+  resources: 
+    requests:  
+      storage: 8Gi <1>
+----
+<1> You can request an expanded volume by updating `spec.resources.requests`.
+
+[[expanding_file_system_pvc]]
+== Expanding Persistent Volume Claims 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 usually involves
+expanding volume objects in the CloudProvider, 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.  
+
+The following process assumes that the PVC was previously created from a
+StorageClass with `allowVolumeExpansion` set to `true`:
+
+. Edit the PVC and request a new size by editing `spec.resources.requests`. Once
+the CloudProvider object has finished resizing, the PVC is set to
+`FileSystemResizePending`.
+
+. Type the following command to check the condition:
+----
+  oc describe pvc <pvc_name>
+----
+
+When the CloudProvider object has finished resizing, the persistent volume (PV)
+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 `FileSystemResizePending` condition is removed from the PVC.