Documentation for volume scheduling alpha feature

Author: msau42

docs/concepts/storage/persistent-volumes.md

@@ -60,10 +60,27 @@ 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.
 
+#### Binding Modes
+{% assign for_k8s_version="v1.9" %}{% include feature-state-alpha.md %}
+
+This requires the `VolumeScheduling` feature gate to be enabled.
+
+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](storage-classes.md#thestorageclassresource).
+
+**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.

docs/concepts/storage/storage-classes.md

@@ -52,6 +52,21 @@ mountOptions:
   - debug
 ```
 
+### Volume Binding Mode
+{% assign for_k8s_version="v1.9" %}{% include feature-state-alpha.md %}
+
+This field requires the `VolumeScheduling` feature gate to be enabled.
+
+A new field, `volumeBindingMode`, controls if volume binding should happen
+immediately or wait until pod scheduling.  Valid values are `Immediate` and
+`WaitForFirstConsumer`.  The default mode is `Immediate`, which is the same
+behavior prior to this feature.
+
+**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.
+
 ### Provisioner
 
 Storage classes have a provisioner that determines what volume plugin is used
@@ -78,6 +93,7 @@ for provisioning PVs. This field must be specified.
 | PortworxVolume       | ✓            | [Portworx Volume](#portworx-volume)  |
 | ScaleIO              | ✓            | [ScaleIO](#scaleio)                  |
 | StorageOS            | ✓            | [StorageOS](#storageos)              |
+| Local                | -                   | [Local](#local)              |
 
 You are not restricted to specifying the "internal" provisioners
 listed here (whose names are prefixed with "kubernetes.io" and shipped
@@ -634,3 +650,22 @@ 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
+
+{% assign for_k8s_version="v1.9" %}{% include feature-state-alpha.md %}
+
+This feature requires the `VolumeScheduling` feature gate to be enabled.
+
+```yaml
+kind: StorageClass
+apiVersion: storage.k8s.io/v1
+metadata:
+  name: local-fast
+provisioner: kubernetes.io/no-provisioner
+volumeBindingMode: WaitForFirstConsumer
+```
+
+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.

docs/concepts/storage/volumes.md

@@ -434,7 +434,12 @@ See the [iSCSI example](https://github.com/kubernetes/examples/tree/{{page.githu
 
 ### local
 
-This volume type is alpha in 1.7.
+{% assign for_k8s_version="v1.7" %}{% include feature-state-alpha.md %}
+
+This alpha feature requires the `PersistentLocalVolumes` feature gate to be
+enabled.
+
+Starting in 1.9, the `VolumeScheduling` feature gate must also be enabled.
 
 A `local` volume represents a mounted local storage device such as a disk,
 partition or directory.
@@ -481,6 +486,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 until pod scheduling by
+creating a StorageClass with `volumeBindingMode` set to `WaitForFirstConsumer`.
+See the [example](storage-classes.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).