Documentation for volume scheduling alpha feature

docs/concepts/storage/persistent-volumes.md

@@ -60,7 +60,7 @@ 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.
 

docs/concepts/storage/storage-classes.md

@@ -78,6 +78,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 +635,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,13 @@ 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.
+
+**Note:** Starting in 1.9, the `VolumeScheduling` feature gate must also be enabled.
+{: .note}
 
 A `local` volume represents a mounted local storage device such as a disk,
 partition or directory.
@@ -443,7 +449,7 @@ Local volumes can only be used as a statically created PersistentVolume.
 
 Compared to HostPath volumes, local volumes can be used in a durable manner
 without manually scheduling pods to nodes, as the system is aware of the volume's
-node constraints.
+node constraints by looking at the node affinity on the PersistentVolume.
 
 However, local volumes are still subject to the availability of the underlying
 node and are not suitable for all applications.
@@ -481,6 +487,13 @@ 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). Delaying volume binding 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.
+
 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).