Add docs for implementing resize (#5528)

* Add docs for implementing resize

* Update admission-controllers.md

* Added link to PVC section

* minor typo fixes

docs/admin/admission-controllers.md

@@ -280,7 +280,7 @@ namespace.  In order to enforce integrity of that process, we strongly recommend
 ### NodeRestriction
 
 This plug-in limits the `Node` and `Pod` objects a kubelet can modify. In order to be limited by this admission plugin,
-kubelets must use credentials in the `system:nodes` group, with a username in the form `system:node:<nodeName>`. 
+kubelets must use credentials in the `system:nodes` group, with a username in the form `system:node:<nodeName>`.
 Such kubelets will only be allowed to modify their own `Node` API object, and only modify `Pod` API objects that are bound to their node.
 Future versions may add additional restrictions to ensure kubelets have the minimal set of permissions required to operate correctly.
 
@@ -332,6 +332,35 @@ metadata:
   name: namespace3
 ```
 
+### PersistentVolumeClaimResize
+
+This plug-in implements additional validations for checking incoming `PersistentVolumeClaim` resize requests.
+**Note:** Support for volume resizing is available as an alpha feature. Admins must set the feature gate `ExpandPersistentVolumes`
+to `true` to enable resizing.
+{: .note}
+
+After enabling the `ExpandPersistentVolumes` feature gate, enabling the `PersistentVolumeClaimResize` admission
+plug-in is recommended, too. This plug-in prevents resizing of all claims by default unless a claim's `StorageClass`
+ explicitly enables resizing by setting `allowVolumeExpansion` to `true`.
+
+For example: all `PersistnetVolumeClaim`s created from the following `StorageClass` support volume expansion:
+
+```yaml
+kind: StorageClass
+apiVersion: storage.k8s.io/v1
+metadata:
+  name: gluster-vol-default
+provisioner: kubernetes.io/glusterfs
+parameters:
+  resturl: "http://192.168.10.100:8080"
+  restuser: ""
+  secretNamespace: ""
+  secretName: ""
+allowVolumeExpansion: true
+```
+
+For more information about persistent volume claims, see ["PersistentVolumeClaims"](/docs/concepts/storage/persistent-volumes/#persistentvolumeclaims).
+
 ### PodPreset
 
 This plug-in injects a pod with the fields specified in a matching PodPreset.
@@ -387,6 +416,7 @@ This plug-in will deny any pod that attempts to set certain escalating [Security
 This plug-in implements automation for [serviceAccounts](/docs/user-guide/service-accounts).
 We strongly recommend using this plug-in if you intend to make use of Kubernetes `ServiceAccount` objects.
 
+
 ## Is there a recommended set of plug-ins to use?
 
 Yes.

docs/concepts/storage/persistent-volumes.md

@@ -109,6 +109,39 @@ However, the particular path specified in the custom recycler pod template in th
 
 For volume plugins that support the Delete reclaim policy, deletion removes both the `PersistentVolume` object from Kubernetes, as well as deleting the associated storage asset in the external infrastructure, such as an AWS EBS, GCE PD, Azure Disk, or Cinder volume. Volumes that were dynamically provisioned inherit the [reclaim policy of their `StorageClass`](#reclaim-policy-1), which defaults to Delete. The administrator should configure the `StorageClass` according to users' expectations, otherwise the PV must be edited or patched after it is created. See [Change the Reclaim Policy of a PersistentVolume](https://kubernetes.io/docs/tasks/administer-cluster/change-pv-reclaim-policy/).
 
+
+### Expanding Persistent Volumes Claims
+
+With Kubernetes 1.8, we have added Alpha support for expanding persistent volumes. The current Alpha support was designed to only support volume types
+that don't need file system resizing (Currently only glusterfs).
+
+Administrator can allow expanding persistent volume claims by setting `ExpandPersistentVolumes` feature gate to true. Administrator
+should also enable [`PersistentVolumeClaimResize` admission plugin](/docs/admin/admission-controllers/#persistentvolumeclaimresize)
+to perform additional validations of volumes that can be resized.
+
+Once `PersistentVolumeClaimResize` admission plug-in has been turned on, resizing will only be allowed for storage classes
+whose `allowVolumeExpansion` field is set to true.
+
+``` yaml
+kind: StorageClass
+apiVersion: storage.k8s.io/v1
+metadata:
+  name: gluster-vol-default
+provisioner: kubernetes.io/glusterfs
+parameters:
+  resturl: "http://192.168.10.100:8080"
+  restuser: ""
+  secretNamespace: ""
+  secretName: ""
+allowVolumeExpansion: true
+```
+
+Once both feature gate and aforementioned admission plug-in are turned on, an user can request larger volume for their `PersistentVolumeClaim`
+by simply editing the claim and requesting bigger size.  This in turn will trigger expansion of volume that is backing underlying `PersistentVolume`.
+
+Under no circustances a new `PersistentVolume` gets created to satisfy the claim. Kubernetes will attempt to resize existing volume to satisfy the claim.
+
+
 ## Types of Persistent Volumes
 
 `PersistentVolume` types are implemented as plugins.  Kubernetes currently supports the following plugins: