Documentation for volume scheduling alpha feature

Author: msau42

docs/concepts/storage/persistent-volumes.md

@@ -66,10 +66,23 @@ please check [kube-apiserver](/docs/admin/kube-apiserver/) documentation.
 
 ### Binding
 
-A user creates, or has already created in the case of dynamic provisioning, a `PersistentVolumeClaim` with a specific amount of storage requested and with certain access modes.  A control loop in the master watches for new PVCs, finds a matching PV (if possible), and binds them together.  If a PV was dynamically provisioned for a new PVC, the loop will always bind that PV to the PVC. Otherwise, the user will always get at least what they asked for, but the volume may be in excess of what was requested.  Once bound, `PersistentVolumeClaim` binds are exclusive, regardless of the mode used to bind them.
+A user creates, or has already created in the case of dynamic provisioning, a `PersistentVolumeClaim` with a specific amount of storage requested and with certain access modes.  A control loop in the master watches for new PVCs, finds a matching PV (if possible), and binds them together.  If a PV was dynamically provisioned for a new PVC, the loop will always bind that PV to the PVC. Otherwise, the user will always get at least what they asked for, but the volume may be in excess of what was requested.  Once bound, `PersistentVolumeClaim` binds are exclusive, regardless of how they were bound.  A PVC to PV binding is a one-to-one mapping.
 
 Claims will remain unbound indefinitely if a matching volume does not exist.  Claims will be bound as matching volumes become available.  For example, a cluster provisioned with many 50Gi PVs would not match a PVC requesting 100Gi.  The PVC can be bound when a 100Gi PV is added to the cluster.
 
+Alpha support for volume binding during pod scheduling is available in 1.9.
+Normally, volume binding occurs immediately upon PVC creation.
+However, for PVs that specify NodeAffinity, it may be beneficial to delay
+binding until there is a pod consumer that references the PVC.  This ensures
+that the volume binding decision will also be evaluated with any other node
+constraints the pod may have, such as node resource requirements, node
+selectors, pod affinity, and pod anti-affinity.  This new mode of binding is
+controlled through the `VolumeBindingMode` parameter in the
+[StorageClass](#StorageClasses).
+
+**Note:** Dynamic provisioning is not supported yet with this alpha feature.
+{: .note}
+
 ### Using
 
 Pods use claims as volumes. The cluster inspects the claim to find the bound volume and mounts that volume for a pod.  For volumes which support multiple access modes, the user specifies which mode desired when using their claim as a volume in a pod.
@@ -437,6 +450,15 @@ request any particular class to bind to: see the
 [`PersistentVolumeClaim` section](#persistentvolumeclaims)
 for details.
 
+A new alpha field in 1.9, `volumeBindingMode`, controls if volume binding should happen
+immediately or wait until pod scheduling.  Valid values are `Immediate` and
+`WaitForFirstConsumer`.  The default mode is `Immediate`.
+
+**Note:** The `WaitForFirstConsumer` volume binding mode does not support
+dynamic provisioning yet.  Also, it currently is only useful for the
+[local](volumes.md#local) volume type.  Additional volume types will be
+supported in the future.
+
 ```yaml
 kind: StorageClass
 apiVersion: storage.k8s.io/v1
@@ -474,6 +496,7 @@ for provisioning PVs. This field must be specified.
 | VsphereVolume        | ✓            | [vSphere](#vsphere)                  |
 | PortworxVolume       | ✓            | [Portworx Volume](#portworx-volume)  |
 | ScaleIO              | ✓            | [ScaleIO](#scaleio)                  |
+| Local                | -                   | [Local](#local)                  |
 
 You are not restricted to specifying the "internal" provisioners
 listed here (whose names are prefixed with "kubernetes.io" and shipped
@@ -875,6 +898,25 @@ $ kubectl create secret generic storageos-secret --type="kubernetes.io/storageos
 
 Secrets used for dynamically provisioned volumes may be created in any namespace and referenced with the `adminSecretNamespace` parameter.  Secrets used by pre-provisioned volumes must be created in the same namespace as the PVC that references it.
 
+#### Local
+
+```yaml
+kind: StorageClass
+apiVersion: storage.k8s.io/v1
+metadata:
+  name: local-fast
+provisioner: kubernetes.io/no-provisioner
+volumeBindingMode: WaitForFirstConsumer
+parameters:
+```
+
+Local volumes do not support dynamic provisioning yet, however a StorageClass
+should still be created to delay volume binding until pod scheduling.  This is
+specified by the `WaitForFirstConsumer` volume binding mode.
+
+**Note:** Local volumes are an alpha feature in 1.7.  Volume binding during pod
+scheduling is an alpha feature in 1.9.
+
 ## Writing Portable Configuration
 
 If you're writing configuration templates or examples that run on a wide range of clusters

docs/concepts/storage/volumes.md

@@ -814,6 +814,10 @@ spec:
 **Note:** The local PersistentVolume cleanup and deletion requires manual intervention without the external provisioner.
 {: .note}
 
+Starting in 1.9, local volume binding can be delayed by creating a StorageClass
+with `volumeBindingMode` set to `WaitForFirstConsumer`.  See the
+[example](persistent-volumes.md#local).
+
 For details on the `local` volume type, see the [Local Persistent Storage
 user guide](https://github.com/kubernetes-incubator/external-storage/tree/master/local-volume).