Update docs with topology aware dynamic provisioning

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

Hide file tree

Showing 2 changed files with 73 additions and 5 deletions.
diff --git a/content/en/docs/concepts/storage/dynamic-provisioning.md b/content/en/docs/concepts/storage/dynamic-provisioning.md
@@ -124,6 +124,66 @@ 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 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, node selectors,
+pod affinity and anti-affinity, and taints and tolerations.
+
+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 should
+not be necessary to specify restrict provisioning to specific zones anymore, but
+can still 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 %}}