Document topologies in parameters.md

Signed-off-by: Connor Catlett <[email protected]>
kubernetes-sigs · Sep 28, 2023 · 455d847 · 455d847
1 parent 27ad245
commit 455d847
Showing 1 changed file with 28 additions and 5 deletions.
diff --git a/docs/parameters.md b/docs/parameters.md
@@ -1,5 +1,7 @@
-# CreateVolume Parameters
-There are several optional parameters that may be passed into `CreateVolumeRequest.parameters` map, these parameters can be configured in StorageClass, see [example](../examples/kubernetes/storageclass).
+# CreateVolume (`StorageClass`) Parameters
+
+## Supported Parameters
+There are several optional parameters that may be passed into `CreateVolumeRequest.parameters` map, these parameters can be configured in StorageClass, see [example](../examples/kubernetes/storageclass). Unless explicitly noted, all parameters are case insensitive (e.g. "kmsKeyId", "kmskeyid" and any other combination of upper/lowercase characters can be used).
 
 The AWS EBS CSI Driver supports [tagging](tagging.md) through `StorageClass.parameters` (in v1.6.0 and later). 
 
@@ -18,10 +20,8 @@ The AWS EBS CSI Driver supports [tagging](tagging.md) through `StorageClass.para
 | "inodeSize"                  |                                                    |         | The inode size to use when formatting the underlying filesystem. Only supported on linux nodes and with fstype `ext2`, `ext3`, `ext4`, or `xfs`.                                                                                                                                                                                                                                               |
 | "bytesPerINode"              |                                                    |         | The `bytes-per-inode` to use when formatting the underlying filesystem. Only supported on linux nodes and with fstype `ext2`, `ext3`, `ext4`.                                                                                                                                                                                                                                                  |
 | "numberOfINodes"             |                                                    |         | The `number-of-inodes` to use when formatting the underlying filesystem. Only supported on linux nodes and with fstype `ext2`, `ext3`, `ext4`.                                                                                                                                                                                                                                                 |
-
-**Appendix**
+## Restrictions
 * `gp3` is currently not supported on outposts. Outpost customers need to use a different type for their volumes.
-* Unless explicitly noted, all parameters are case insensitive (e.g. "kmsKeyId", "kmskeyid" and any other combination of upper/lowercase characters can be used).
 * If the requested IOPS (either directly from `iops` or from `iopsPerGB` multiplied by the volume's capacity) produces a value above the maximum IOPS allowed for the [volume type](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ebs-volume-types.html), the IOPS will be capped at the maximum value allowed. If the value is lower than the minimal supported IOPS value per volume, either an error is returned (the default behavior), or the value is increased to fit into the supported range when `allowautoiopspergbincrease` is `"true"`.
 * You may specify either the "iops" or "iopsPerGb" parameters, not both. Specifying both parameters will result in an invalid StorageClass.
 
@@ -31,3 +31,26 @@ The AWS EBS CSI Driver supports [tagging](tagging.md) through `StorageClass.para
 | io2 (blockExpress = false) | 100            | 64000         | 500               |
 | io2 (blockExpress = true)  | 100            | 256000        | 500               |
 | gp3                        | 3000           | 16000         | 500               |
+
+## Volume Availability Zone and Topologies
+
+The EBS CSI Driver supports the [`WaitForFirstConsumer` volume binding mode in Kubernetes](https://kubernetes.io/docs/concepts/storage/storage-classes/#volume-binding-mode). When using `WaitForFirstConsumer` binding mode the volume will automatically be created in the appropriate Availability Zone and with the appropriate topology. The `WaitForFirstConsumer` binding mode is recommended whenever possible for dynamic provisioning.
+
+When using static provisioning, or if `WaitForFirstConsumer` is not suitable for a specific usecase, the Availability Zone can be specified via the standard CSI topology mechanisms. The EBS CSI Driver supports specifying the Availability Zone via either the key `topology.kubernetes.io/zone` or the key `topology.ebs.csi.aws.com/zone`.
+
+On Kubernetes, the Availability Zone of dynamically provisioned volumes can be restricted with the [`StorageClass`'s `availableToplogies` parameter](https://kubernetes.io/docs/concepts/storage/storage-classes/#allowed-topologies), for example:
+
+```
+apiVersion: storage.k8s.io/v1
+kind: StorageClass
+metadata:
+  name: ebs-sc
+provisioner: ebs.csi.aws.com
+allowedTopologies:
+- matchLabelExpressions:
+  - key: topology.kubernetes.io/zone
+    values:
+    - us-east-1
+```
+
+Additionally, statically provisioned volumes can be restricted to pods in the appropriate Availability Zone, see the [static provisioning example](../examples/kubernetes/static-provisioning/).