Update docs with topology aware dynamic provisioning

kubernetes · Sep 7, 2018 · b69c2ee · b69c2ee
1 parent f8e4d35
commit b69c2ee
Show file tree

Hide file tree

Showing 4 changed files with 92 additions and 15 deletions.
diff --git a/content/en/docs/concepts/storage/dynamic-provisioning.md b/content/en/docs/concepts/storage/dynamic-provisioning.md
@@ -124,6 +124,71 @@ Note that there can be at most one *default* storage class on a cluster, or
 a `PersistentVolumeClaim` without `storageClassName` explicitly specified cannot
 be created.
 
+## Topology Awareness
+
+{{< feature-state for_k8s_version="v1.12" state="beta" >}}
+
+**Note:** This feature requires the `VolumeScheduling` feature gate to be enabled.
+
+In [multi-zone](/docs/setup/multiple-zones) clusters, pods can be spread across
+zones and single-zone storage backends should be provisioned in the zones where
+pods are scheduled. This can be accomplished by delaying dynamic provisioning
+until pod scheduling, and is supported by the following volume plugins:
+
+* [AWSElasticBlockStore](storage-classes.md#aws-ebs)
+* [GCEPersistentDisk](storage-classes.md#gce-pd)
+* [AzureDisk](storage-classes.md#azure-disk)
+
+To enable this, in the `StorageClass`, set the `volumeBindingMode` field to
+`WaitForFirstConsumer`:
+
+```yaml
+apiVersion: storage.k8s.io/v1
+kind: StorageClass
+metadata:
+  name: slow
+provisioner: kubernetes.io/gce-pd
+volumeBindingMode: WaitForFirstConsumer
+parameters:
+  type: pd-standard
+```
+
+When this mode is specified, the volume will be provisioned in the appropriate
+zone where the pod is scheduled, based on scheduling constraints specified on
+the pod, including but not limited to: [resource
+requirements](/docs/concepts/configuration/manage-compute-resources-container),
+[node selectors](/docs/concepts/configuration/assign-pod-node/#nodeselector),
+[pod affinity and
+anti-affinity](/docs/concepts/configuration/assign-pod-node/#affinity-and-anti-affinity),
+and [taints and tolerations](/doc/concepts/configuration/taint-and-toleration).
+
+To further restrict the zones that a volume can be provisioned in,
+`allowedTopologies` can be specified in the `StorageClass`:
+
+```yaml
+apiVersion: storage.k8s.io/v1
+kind: StorageClass
+metadata:
+  name: slow
+provisioner: kubernetes.io/gce-pd
+volumeBindingMode: WaitForFirstConsumer
+allowedTopologies:
+- matchLabelExpressions:
+  - key: failure-domain.beta.kubernetes.io/zone
+    values:
+    - us-central1-a
+    - us-cetnral1-b
+parameters:
+  type: pd-standard
+```
+
+**Note:** The plugin-specific `zone` and `zones` parameters cannot be used with this
+feature and are deprecated. With `WaitForFirstConsumer` binding mode, it is no
+longer necessary to restrict provisioning to specific zones anymore in most
+situations. If zone restriction is still required, then it can be restricted with
+`allowedToplogies`.
+
+
 {{% /capture %}}
 
 
diff --git a/content/en/docs/concepts/storage/storage-classes.md b/content/en/docs/concepts/storage/storage-classes.md
@@ -66,15 +66,15 @@ for provisioning PVs. This field must be specified.
 
 | Volume Plugin        | Internal Provisioner| Config Example                       |
 | :---                 |     :---:           |    :---:                             |
-| AWSElasticBlockStore | &#x2713;            | [AWS](#aws)                          |
+| AWSElasticBlockStore | &#x2713;            | [AWS EBS](#aws-ebs)                          |
 | AzureFile            | &#x2713;            | [Azure File](#azure-file)            |
 | AzureDisk            | &#x2713;            | [Azure Disk](#azure-disk)            |
 | CephFS               | -                   | -                                    |
 | Cinder               | &#x2713;            | [OpenStack Cinder](#openstack-cinder)|
 | FC                   | -                   | -                                    |
 | FlexVolume           | -                   | -                                    |
 | Flocker              | &#x2713;            | -                                    |
-| GCEPersistentDisk    | &#x2713;            | [GCE](#gce)                          |
+| GCEPersistentDisk    | &#x2713;            | [GCE PD](#gce-pd)                          |
 | Glusterfs            | &#x2713;            | [Glusterfs](#glusterfs)              |
 | iSCSI                | -                   | -                                    |
 | Quobyte              | &#x2713;            | [Quobyte](#quobyte)                  |
@@ -128,7 +128,7 @@ class. Different parameters may be accepted depending on the `provisioner`. For
 `iopsPerGB` are specific to EBS. When a parameter is omitted, some default is
 used.
 
-### AWS
+### AWS EBS
 
 ```yaml
 kind: StorageClass
@@ -164,7 +164,11 @@ parameters:
   encrypting the volume. If none is supplied but `encrypted` is true, a key is
   generated by AWS. See AWS docs for valid ARN value.
 
-### GCE
+**Note:** `zone` and `zones` parameters are deprecated and replaced with
+[topology-aware dynamic
+provisioning](dynamic-provisioning.md#topology-awareness)
+
+### GCE PD
 
 ```yaml
 kind: StorageClass
@@ -199,6 +203,10 @@ specified, Kubernetes will arbitrarily choose among the specified zones. If the
 `zones` parameter is omitted, Kubernetes will arbitrarily choose among zones
 managed by the cluster.
 
+**Note:** `zone` and `zones` parameters are deprecated and replaced with
+[topology-aware dynamic
+provisioning](dynamic-provisioning.md#topology-awareness)
+
 ### Glusterfs
 
 ```yaml
@@ -678,4 +686,4 @@ Delaying volume binding allows the scheduler to consider all of a pod's
 scheduling constraints when choosing an appropriate PersistentVolume for a
 PersistentVolumeClaim.
 
-{{% /capture %}}
+{{% /capture %}}
diff --git a/content/en/docs/reference/command-line-tools-reference/feature-gates.md b/content/en/docs/reference/command-line-tools-reference/feature-gates.md
@@ -56,7 +56,7 @@ different Kubernetes components.
 | `DevicePlugins` | `true` | Beta | 1.10 | |
 | `DynamicKubeletConfig` | `false` | Alpha | 1.4 | 1.10 |
 | `DynamicKubeletConfig` | `true` | Beta | 1.11 | |
-| `DynamicProvisioningScheduling` | `false` | Alpha | 1.11 | |
+| `DynamicProvisioningScheduling` | `false` | Alpha | 1.11 | 1.11 |
 | `DynamicVolumeProvisioning` | `true` | Alpha | 1.3 | 1.7 |
 | `DynamicVolumeProvisioning` | `true` | GA | 1.8 | |
 | `EnableEquivalenceClassCache` | `false` | Alpha | 1.8 | |

diff --git a/content/en/docs/setup/multiple-zones.md b/content/en/docs/setup/multiple-zones.md
@@ -72,17 +72,21 @@ available and can tolerate the loss of a zone, the control plane is
 located in a single zone.  Users that want a highly available control
 plane should follow the [high availability](/docs/admin/high-availability) instructions.
 
-* StatefulSet volume zone spreading when using dynamic provisioning is currently not compatible with
-pod affinity or anti-affinity policies.
+* **Volume limitations**:
+  The following limitations are addressed with [topology-aware dynamic
+  provisiong](/docs/concepts/storage/dynamic-provisiong#topology-awareness).
 
-* If the name of the StatefulSet contains dashes ("-"), volume zone spreading
-may not provide a uniform distribution of storage across zones.
+  * StatefulSet volume zone spreading when using dynamic provisioning is currently not compatible with
+  pod affinity or anti-affinity policies.
 
-* When specifying multiple PVCs in a Deployment or Pod spec, the StorageClass
-needs to be configured for a specific, single zone, or the PVs need to be
-statically provisioned in a specific zone. Another workaround is to use a
-StatefulSet, which will ensure that all the volumes for a replica are
-provisioned in the same zone.
+  * If the name of the StatefulSet contains dashes ("-"), volume zone spreading
+  may not provide a uniform distribution of storage across zones.
+
+  * When specifying multiple PVCs in a Deployment or Pod spec, the StorageClass
+  needs to be configured for a specific, single zone, or the PVs need to be
+  statically provisioned in a specific zone. Another workaround is to use a
+  StatefulSet, which will ensure that all the volumes for a replica are
+  provisioned in the same zone.
 
 
 ## Walkthrough