From ece8a1324fcfe0fd623e0a022adebc9f5bf0c3c4 Mon Sep 17 00:00:00 2001
From: Tim Gross <tgross@hashicorp.com>
Date: Fri, 25 Feb 2022 14:31:21 -0500
Subject: [PATCH] docs: updates for CSI topology

---
 .../content/docs/commands/volume/create.mdx   | 53 +++++++++++++++++++
 .../content/docs/commands/volume/register.mdx | 48 +++++++++++++++++
 2 files changed, 101 insertions(+)

diff --git a/website/content/docs/commands/volume/create.mdx b/website/content/docs/commands/volume/create.mdx
index dcf276d99679..0ffc78da02a6 100644
--- a/website/content/docs/commands/volume/create.mdx
+++ b/website/content/docs/commands/volume/create.mdx
@@ -59,6 +59,16 @@ mount_options {
   mount_flags = ["noatime"]
 }
 
+topology_request {
+  required {
+    topology { segments { "rack" = "R2" } }
+    topology { segments { "rack" = "R1", "zone" = "us-east-1a"} }
+  }
+  preferred {
+    topology { segments { "rack" = "R1", "zone" = "us-east-1a"} }
+  }
+}
+
 secrets {
   example_secret = "xyzzy"
 }
@@ -134,6 +144,15 @@ parameters {
   - `mount_flags` `([]string: <optional>)` - The flags passed to `mount`
     (ex. `["ro", "noatime"]`)
 
+- `topology_request` <code>([TopologyRequest](#topology_request-parameters): nil)</code> -
+  Specify locations (region, zone, rack, etc.)  where the provisioned
+  volume must be accessible from. Consult the documentation for your
+  storage provider and CSI plugin as to whether it supports defining
+  topology and what values it expects for topology
+  segments. Specifying topology segments that aren't supported by the
+  storage provider may return an error or may be silently removed by
+  the plugin.
+
 - `secrets` <code>(map<string|string>:nil)</code> - An optional
   key-value map of strings used as credentials for publishing and
   unpublishing volumes.
@@ -144,6 +163,40 @@ parameters {
   to each storage provider, so please see the specific plugin
   documentation for more information.
 
+### `topology_request` Parameters
+
+For the `topology_request` field, you may specify a list of either
+`required` or `preferred` topologies (or both). The `required`
+topologies indicate that the volume must be created in a location
+accessible from at least one of the listed topologies. The `preferred`
+topologies indicate that you would prefer the storage provider to
+create the volume in one of the provided topologies.
+
+Each topology listed has a single field:
+
+- `segments` `(map[string]string)` - A map of location types to their
+ values. The specific fields required are defined by the CSI
+ plugin. For example, a plugin might require defining both a rack and
+ a zone: `segments {rack = "R2", zone = "us-east-1a"}`.
+
+For example:
+
+```hcl
+topology_request {
+  required {
+    topology { segments { "rack" = "R1", "zone" = "us-east-1a" } }
+    topology { segments { "rack" = "R2", "zone" = "us-east-1a" } }
+  }
+  preferred {
+    topology { segments { "rack" = "R1", "zone" = "us-east-1a"} }
+  }
+}
+```
+
+This configuration indicates you require the volume to be created
+within racks `R1` or `R2`, but that you prefer the volume to be
+created within `R1`.
+
 ### Unused Fields
 
 Note that several fields used in the [`volume register`] command are set
diff --git a/website/content/docs/commands/volume/register.mdx b/website/content/docs/commands/volume/register.mdx
index 1e2023250094..343f8b94269d 100644
--- a/website/content/docs/commands/volume/register.mdx
+++ b/website/content/docs/commands/volume/register.mdx
@@ -61,6 +61,13 @@ mount_options {
   mount_flags = ["noatime"]
 }
 
+topology_request {
+  required {
+    topology { segments { "rack" = "R2" } }
+    topology { segments { "rack" = "R1", "zone" = "us-east-1a"} }
+  }
+}
+
 secrets {
   example_secret = "xyzzy"
 }
@@ -120,6 +127,15 @@ context {
   - `fs_type`: file system type (ex. `"ext4"`)
   - `mount_flags`: the flags passed to `mount` (ex. `"ro,noatime"`)
 
+- `topology_request` <code>([TopologyRequest](#topology_request-parameters): nil)</code> -
+  Specify locations (region, zone, rack, etc.)  where the provisioned
+  volume is accessible from. Consult the documentation for your
+  storage provider and CSI plugin as to whether it supports defining
+  topology and what values it expects for topology
+  segments. Specifying topology segments that aren't supported by the
+  storage provider may return an error or may be silently removed by
+  the plugin.
+
 - `secrets` <code>(map<string|string>:nil)</code> - An optional
   key-value map of strings used as credentials for publishing and
   unpublishing volumes.
@@ -136,6 +152,38 @@ context {
   each storage provider, so please see the specific plugin
   documentation for more information.
 
+### `topology_request` Parameters
+
+For the `topology_request` field, you may specify a list of `required`
+topologies. The `required` topologies indicate that the volume was
+created in a location accessible from all the listed topologies.
+
+Note this behavior is different from the `nomad volume create`
+command, because the volume has already been created and you are
+defining the topology for Nomad. The `register` command does not
+support setting `preferred` topologies.
+
+Each topology listed has a single field:
+
+- `segments` `(map[string]string)` - A map of location types to their
+ values. The specific fields required are defined by the CSI
+ plugin. For example, a plugin might require defining both a rack and
+ a zone: `segments {rack = "R2", zone = "us-east-1a"}`.
+
+For example:
+
+```hcl
+topology_request {
+  required {
+    topology { segments { "rack" = "R1", "zone" = "us-east-1a" } }
+    topology { segments { "rack" = "R2", "zone" = "us-east-1a" } }
+  }
+}
+```
+
+This configuration indicates that the volume is accessible from both
+racks `R1` or `R2`.
+
 ### Unused Fields
 
 Note that several fields used in the [`volume create`] command are set