diff --git a/website/content/docs/commands/volume/create.mdx b/website/content/docs/commands/volume/create.mdx
index 3dc68f39d..f0155a6be 100644
--- a/website/content/docs/commands/volume/create.mdx
+++ b/website/content/docs/commands/volume/create.mdx
@@ -33,194 +33,40 @@ When ACLs are enabled, this command requires a token with the
## Volume Specification
-The file may be provided as either HCL or JSON. An example HCL configuration:
+
-```hcl
-id = "ebs_prod_db1"
-namespace = "default"
-name = "database"
-type = "csi"
-plugin_id = "ebs-prod"
-snapshot_id = "snap-12345" # or clone_id, see below
-capacity_max = "200G"
-capacity_min = "100G"
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
-capability {
- access_mode = "single-node-reader-only"
- attachment_mode = "file-system"
-}
-
-capability {
- access_mode = "single-node-writer"
- attachment_mode = "file-system"
-}
-
-mount_options {
- fs_type = "ext4"
- 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"
-}
-
-parameters {
- skuname = "Premium_LRS"
-}
-```
-
-## Volume Specification Parameters
-
-- `id` `(string: )` - The unique ID of the volume. This is how the
- [`volume.source`][csi_volume_source] field in a job specification will refer
- to the volume.
-
-- `namespace` `(string: )` - The namespace of the volume. This field
- overrides the namespace provided by the `-namespace` flag or `NOMAD_NAMESPACE`
- environment variable. Defaults to `"default"` if unset.
-
-- `name` `(string: )` - The display name of the volume. This field
- may be used by the external storage provider to tag the volume.
-
-- `type` `(string: )` - The type of volume. Currently only `"csi"`
- is supported.
-
-- `plugin_id` `(string: )` - The ID of the [CSI plugin][csi_plugin]
- that manages this volume.
-
-- `snapshot_id` `(string: )` - If the storage provider supports
- snapshots, the external ID of the snapshot to restore when creating this
- volume. If omitted, the volume will be created from scratch. The
- `snapshot_id` cannot be set if the `clone_id` field is set.
-
-- `clone_id` `(string: )` - If the storage provider supports
- cloning, the external ID of the volume to clone when creating this
- volume. If omitted, the volume will be created from scratch. The
- `clone_id` cannot be set if the `snapshot_id` field is set.
-
-- `capacity_min` `(string: )` - Option for requesting a
- minimum capacity, in bytes. The capacity of a volume may be the
- physical size of a disk, or a quota, depending on the storage
- provider. The specific size of the resulting volume will be
- somewhere between `capacity_min` and `capacity_max`; the exact
- behavior is up to the storage provider. If you want to specify an
- exact size, you should set `capacity_min` and `capacity_max` to the
- same value. Accepts human-friendly suffixes such as `"100GiB"`. This
- field may not be supported by all storage providers.
-
-- `capacity_max` `(string: )` - Option for requesting a
- maximum capacity, in bytes. The capacity of a volume may be the
- physical size of a disk, or a quota, depending on the storage
- provider. The specific size of the resulting volume will be
- somewhere between `capacity_min` and `capacity_max`; the exact
- behavior is up to the storage provider. If you want to specify an
- exact size, you should set `capacity_min` and `capacity_max` to the
- same value. Accepts human-friendly suffixes such as `"100GiB"`. This
- field may not be supported by all storage providers.
-
-- `capability` `(Capability: )` - Option for validating the
- capability of a volume. You must provide at least one `capability` block, and
- you must provide a block for each capability you intend to use in a job's
- [`volume`] block. Each `capability` block must have the following fields:
-
- - `access_mode` `(string: )` - Defines whether a volume should be
- available concurrently. Can be one of `"single-node-reader-only"`,
- `"single-node-writer"`, `"multi-node-reader-only"`,
- `"multi-node-single-writer"`, or `"multi-node-multi-writer"`. Most CSI
- plugins support only single-node modes. Consult the documentation of the
- storage provider and CSI plugin.
-
- - `attachment_mode` `(string: )` - The storage API that will be used
- by the volume. Most storage providers will support `"file-system"`, to mount
- volumes using the CSI filesystem API. Some storage providers will support
- `"block-device"`, which will mount the volume with the CSI block device API
- within the container.
-
-- `mount_options` - Options for mounting `file-system` volumes that don't
- already have a pre-formatted file system. This block will be validated
- during volume creation against the `capability` field. The `mount_options`
- provided in a job specification's [`volume`] block will override this
- block. Consult the documentation for your storage provider and CSI plugin as
- to whether these options are required or necessary.
-
- - `fs_type` `(string )` - File system type (ex. `"ext4"`)
- - `mount_flags` `([]string: )` - The flags passed to `mount`
- (ex. `["ro", "noatime"]`)
-
-- `topology_request` ([TopologyRequest](#topology_request-parameters): nil) -
- 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` (map:nil) - An optional
- key-value map of strings used as credentials for publishing and
- unpublishing volumes.
-
-- `parameters` (map:nil) - An optional
- key-value map of strings passed directly to the CSI plugin to
- configure the volume. The details of these parameters are specific
- 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
-automatically by the plugin when `volume create` is successful. You should not
-set the `external_id` or `context` fields described on that page.
+The volume specification is documented in the [Volume
+Specification][volume_specification] page.
[csi]: https://github.com/container-storage-interface/spec
[csi_plugins_internals]: /docs/internals/plugins/csi#csi-plugins
-[volume_specification]: #volume-specification
-[csi_plugin]: /docs/job-specification/csi_plugin
-[csi_volume_source]: /docs/job-specification/volume#source
[registered]: /docs/commands/volume/register
-[`volume register`]: /docs/commands/volume/register
-[`volume`]: /docs/job-specification/volume
+[volume_specification]: /docs/other-specifications/volume
diff --git a/website/content/docs/commands/volume/register.mdx b/website/content/docs/commands/volume/register.mdx
index 63b3cb280..18f3052a3 100644
--- a/website/content/docs/commands/volume/register.mdx
+++ b/website/content/docs/commands/volume/register.mdx
@@ -22,11 +22,10 @@ nomad volume register [options] [file]
```
The `volume register` command requires a single argument, specifying the path
-to a file containing a valid [volume
-specification][volume_specification]. This file will be read and the job will
-be submitted to Nomad for scheduling. If the supplied path is "-", the job
-file is read from STDIN. Otherwise it is read from the file at the supplied
-path.
+to a file containing a valid [volume specification][volume_specification]. This
+file will be read and the job will be submitted to Nomad for scheduling. If the
+supplied path is "-", the job file is read from STDIN. Otherwise it is read
+from the file at the supplied path.
When ACLs are enabled, this command requires a token with the
`csi-write-volume` capability for the volume's namespace.
@@ -37,168 +36,38 @@ When ACLs are enabled, this command requires a token with the
## Volume Specification
-The file may be provided as either HCL or JSON. An example HCL configuration:
+
-```hcl
-id = "ebs_prod_db1"
-name = "database"
-type = "csi"
-external_id = "vol-23452345"
-plugin_id = "ebs-prod"
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
-capability {
- access_mode = "single-node-reader-only"
- attachment_mode = "file-system"
-}
-
-capability {
- access_mode = "single-node-writer"
- attachment_mode = "file-system"
-}
-
-mount_options {
- fs_type = "ext4"
- mount_flags = ["noatime"]
-}
-
-topology_request {
- required {
- topology { segments { "rack" = "R2" } }
- topology { segments { "rack" = "R1", "zone" = "us-east-1a"} }
- }
-}
-
-secrets {
- example_secret = "xyzzy"
-}
-
-parameters {
- skuname = "Premium_LRS"
-}
-
-context {
- endpoint = "http://192.168.1.101:9425"
-}
-```
-
-## Volume Specification Parameters
-
-- `id` `(string: )` - The unique ID of the volume. This is how the
- [`volume.source`][csi_volume_source] field in a job specification will refer
- to the volume.
-
-- `namespace` `(string: )` - The namespace of the volume. This field
- overrides the namespace provided by the `-namespace` flag or `NOMAD_NAMESPACE`
- environment variable. Defaults to `"default"` if unset.
-
-- `name` `(string: )` - The display name of the volume.
-
-- `type` `(string: )` - The type of volume. Currently only `"csi"`
- is supported.
-
-- `external_id` `(string: )` - The ID of the physical volume from
- the storage provider. For example, the volume ID of an AWS EBS volume or
- Digital Ocean volume.
-
-- `plugin_id` `(string: )` - The ID of the [CSI plugin][csi_plugin]
- that manages this volume.
-
-- `capability` `(Capability: )` - Option for validating the
- capability of a volume. You must provide at least one `capability` block, and
- you must provide a block for each capability you intend to use in a job's
- [`volume`] block. Each `capability` block must have the following fields:
-
- - `access_mode` `(string: )` - Defines whether a volume should be
- available concurrently. Can be one of `"single-node-reader-only"`,
- `"single-node-writer"`, `"multi-node-reader-only"`,
- `"multi-node-single-writer"`, or `"multi-node-multi-writer"`. Most CSI
- plugins support only single-node modes. Consult the documentation of the
- storage provider and CSI plugin.
-
- - `attachment_mode` `(string: )` - The storage API that will be used
- by the volume. Most storage providers will support `"file-system"`, to mount
- volumes using the CSI filesystem API. Some storage providers will support
- `"block-device"`, which will mount the volume with the CSI block device API
- within the container.
-
-- `mount_options` - Options for mounting `file-system` volumes that don't
- already have a pre-formatted file system. This block will be validated
- during volume creation against the `capability` field. The `mount_options`
- provided in a job specification's [`volume`] block will override this
- block. Consult the documentation for your storage provider and CSI plugin as
- to whether these options are required or necessary.
-
- - `fs_type`: file system type (ex. `"ext4"`)
- - `mount_flags`: the flags passed to `mount` (ex. `["ro", "noatime"]`)
-
-- `topology_request` ([TopologyRequest](#topology_request-parameters): nil) -
- 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` (map:nil) - An optional
- key-value map of strings used as credentials for publishing and
- unpublishing volumes.
-
-- `parameters` (map:nil) - An optional
- key-value map of strings passed directly to the CSI plugin to
- configure the volume. The details of these parameters are specific
- to each storage provider, so please see the specific plugin
- documentation for more information.
-
-- `context` (map:nil) - An optional
- key-value map of strings passed directly to the CSI plugin to
- validate the volume. The details of these parameters are specific 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 `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
-automatically by the plugin when `volume create` is successful and cannot be
-set on a pre-existing volume. You should not set the `snapshot_id`,
-`clone_id`, `capacity_min`, or `capacity_max` fields described on that page.
+The volume specification is documented in the [Volume
+Specification][volume_specification] page.
[csi]: https://github.com/container-storage-interface/spec
[csi_plugins_internals]: /docs/internals/plugins/csi#csi-plugins
-[volume_specification]: #volume-specification
-[csi_plugin]: /docs/job-specification/csi_plugin
-[csi_volume_source]: /docs/job-specification/volume#source
-[`volume`]: /docs/job-specification/volume
+[volume_specification]: /docs/other-specifications/volume
[`volume create`]: /docs/commands/volume/create
diff --git a/website/content/docs/other-specifications/index.mdx b/website/content/docs/other-specifications/index.mdx
new file mode 100644
index 000000000..f4c418107
--- /dev/null
+++ b/website/content/docs/other-specifications/index.mdx
@@ -0,0 +1,15 @@
+---
+layout: docs
+page_title: Other Specifications
+description: Learn about other specifications used in Nomad.
+---
+
+# Other Specifications
+
+In addition to [jobs][job_spec] there are other objects that can be specified
+in Nomad.
+
+- [Volume][volume_spec]
+
+[job_spec]: /docs/job-specification
+[volume_spec]: /docs/other-specifications/volume
diff --git a/website/content/docs/other-specifications/volume/capability.mdx b/website/content/docs/other-specifications/volume/capability.mdx
new file mode 100644
index 000000000..160aa3951
--- /dev/null
+++ b/website/content/docs/other-specifications/volume/capability.mdx
@@ -0,0 +1,73 @@
+---
+layout: docs
+page_title: capability Block - Volume Specification
+description: The "capability" block allows for validating the capability of a volume.
+---
+
+# `capability` Block
+
+
+
+The `capability` block allows validating that a volume meets the requested
+capabilities.
+
+```hcl
+id = "ebs_prod_db1"
+namespace = "default"
+name = "database"
+type = "csi"
+plugin_id = "ebs-prod"
+capacity_max = "200G"
+capacity_min = "100G"
+
+capability {
+ access_mode = "single-node-reader-only"
+ attachment_mode = "file-system"
+}
+```
+
+You must provide at least one `capability` block, and you must provide a block
+for each capability you intend to use in a job's [`volume`] block.
+
+## `capability` Parameters
+
+- `access_mode` `(string: )` - Defines whether a volume should be
+available concurrently. Can be one of `"single-node-reader-only"`,
+`"single-node-writer"`, `"multi-node-reader-only"`,
+`"multi-node-single-writer"`, or `"multi-node-multi-writer"`. Most CSI plugins
+support only single-node modes. Consult the documentation of the storage
+provider and CSI plugin.
+
+- `attachment_mode` `(string: )` - The storage API that will be used
+by the volume. Most storage providers will support `"file-system"`, to mount
+volumes using the CSI filesystem API. Some storage providers will support
+`"block-device"`, which will mount the volume with the CSI block device API
+within the container.
+
+## `capability` Examples
+
+The following examples only show the `capability` blocks. Remember that the
+`capability` block is only valid in the placement shown above.
+
+### Multiple capabilities
+
+This examples shows a volume that must satisfy multiple capability
+requirements.
+
+```hcl
+capability {
+ access_mode = "single-node-reader-only"
+ attachment_mode = "file-system"
+}
+
+capability {
+ access_mode = "single-node-writer"
+ attachment_mode = "file-system"
+}
+```
+
+[`volume`]: /docs/job-specification/volume
diff --git a/website/content/docs/other-specifications/volume/index.mdx b/website/content/docs/other-specifications/volume/index.mdx
new file mode 100644
index 000000000..60eb4a68b
--- /dev/null
+++ b/website/content/docs/other-specifications/volume/index.mdx
@@ -0,0 +1,216 @@
+---
+layout: docs
+page_title: Volume Specification
+description: Learn about the Volume specification used to create and register volumes to Nomad.
+---
+
+# Volume Specification
+
+The Nomad volume specification defines the schema for creating and registering
+volumes using the [`volume create`] and [`volume register`] commands and the
+[`PUT /v1/volume/csi/:volume_id/create`][api_volume_create] and [`PUT
+/v1/volume/csi/:volume_id`][api_volume_register] API endpoints.
+
+Some attributes are only be supported by specific operation, while others may
+have a different meaning for each action, so read the documentation for each
+attribute carefully. The section [Differences Between Create and
+Register](#differences-between-create-and-register) provides a summary of the
+differences.
+
+The file may be provided as either HCL or JSON to the commands and as JSON to
+the API. An example HCL configuration for a `volume create` command:
+
+```hcl
+id = "ebs_prod_db1"
+namespace = "default"
+name = "database"
+type = "csi"
+plugin_id = "ebs-prod"
+snapshot_id = "snap-12345" # or clone_id, see below
+capacity_max = "200G"
+capacity_min = "100G"
+
+capability {
+ access_mode = "single-node-reader-only"
+ attachment_mode = "file-system"
+}
+
+capability {
+ access_mode = "single-node-writer"
+ attachment_mode = "file-system"
+}
+
+mount_options {
+ fs_type = "ext4"
+ 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"
+}
+
+parameters {
+ skuname = "Premium_LRS"
+}
+```
+
+## Volume Specification Parameters
+
+- `id` `(string: )` - The unique ID of the volume. This is how the
+ [`volume.source`][csi_volume_source] field in a job specification will refer
+ to the volume.
+
+- `namespace` `(string: )` - The namespace of the volume. This field
+ overrides the namespace provided by the `-namespace` flag or `NOMAD_NAMESPACE`
+ environment variable. Defaults to `"default"` if unset.
+
+- `name` `(string: )` - The display name of the volume. On **volume
+ creation**, this field may be used by the external storage provider to tag
+ the volume.
+
+- `type` `(string: )` - The type of volume. Currently only `"csi"`
+ is supported.
+
+- `external_id` `(string: )` - The ID of the physical volume from
+ the storage provider. For example, the volume ID of an AWS EBS volume or
+ Digital Ocean volume. Only allowed on **volume registration**.
+
+- `plugin_id` `(string: )` - The ID of the [CSI plugin][csi_plugin]
+ that manages this volume.
+
+- `snapshot_id` `(string: )` - If the storage provider supports
+ snapshots, the external ID of the snapshot to restore when creating this
+ volume. If omitted, the volume will be created from scratch. The
+ `snapshot_id` cannot be set if the `clone_id` field is set. Only allowed on
+ **volume creation**.
+
+- `clone_id` `(string: )` - If the storage provider supports cloning,
+ the external ID of the volume to clone when creating this volume. If omitted,
+ the volume will be created from scratch. The `clone_id` cannot be set if the
+ `snapshot_id` field is set. Only allowed on **volume creation**.
+
+- `capacity_min` `(string: )` - Option for requesting a minimum
+ capacity, in bytes. The capacity of a volume may be the physical size of a
+ disk, or a quota, depending on the storage provider. The specific size of the
+ resulting volume will be somewhere between `capacity_min` and `capacity_max`;
+ the exact behavior is up to the storage provider. If you want to specify an
+ exact size, you should set `capacity_min` and `capacity_max` to the same
+ value. Accepts human-friendly suffixes such as `"100GiB"`. This field may not
+ be supported by all storage providers. Only allowed on **volume creation**.
+
+- `capacity_max` `(string: )` - Option for requesting a maximum
+ capacity, in bytes. The capacity of a volume may be the physical size of a
+ disk, or a quota, depending on the storage provider. The specific size of the
+ resulting volume will be somewhere between `capacity_min` and `capacity_max`;
+ the exact behavior is up to the storage provider. If you want to specify an
+ exact size, you should set `capacity_min` and `capacity_max` to the same
+ value. Accepts human-friendly suffixes such as `"100GiB"`. This field may not
+ be supported by all storage providers. Only allowed on **volume creation**.
+
+- `capability` ([Capability][capability]: <required>) -
+ Option for validating the capability of a volume.
+
+- `mount_options` ([MountOptions][mount_options]: <required>) -
+ Options for mounting `file-system` volumes that don't already have a
+ pre-formatted file system.
+
+- `topology_request` ([TopologyRequest][topology_request]: nil) -
+ Specify locations (region, zone, rack, etc.) where the provisioned volume
+ must be accessible from in the case of **volume creation** or the locations
+ where the existing volume is accessible from in the case of **volume
+ registration**.
+
+- `secrets` (map:nil) - An optional key-value map
+ of strings used as credentials for publishing and unpublishing volumes.
+
+- `parameters` (map:nil) - An optional key-value
+ map of strings passed directly to the CSI plugin to configure the volume. The
+ details of these parameters are specific to each storage provider, so consult
+ the specific plugin documentation for more information.
+
+- `context` (map:nil) - An optional key-value map
+ of strings passed directly to the CSI plugin to validate the volume. The
+ details of these parameters are specific to each storage provider, so consult
+ the specific plugin documentation for more information. Only allowed on
+ **volume registration**.
+
+## Differences Between Create and Register
+
+Several fields are set automatically by the plugin when `volume create` or
+`volume register` commands are successful and you should not set their values
+if they are not supported by the operation.
+
+You should not set the [`snapshot_id`](#snapshot_id), [`clone_id`](#clone_id),
+[`capacity_min`](#capacity_min), or [`capacity_max`](#capacity_max) fields on
+**volume registration**.
+
+And you should not set the [`external_id`](#external_id) or
+[`context`](#context) fields on **volume creation**.
+
+## Examples
+
+### Volume registration
+
+This is an example file used for the [`volume register`] commad.
+
+```hcl
+id = "ebs_prod_db1"
+name = "database"
+type = "csi"
+external_id = "vol-23452345"
+plugin_id = "ebs-prod"
+
+capability {
+ access_mode = "single-node-reader-only"
+ attachment_mode = "file-system"
+}
+
+capability {
+ access_mode = "single-node-writer"
+ attachment_mode = "file-system"
+}
+
+mount_options {
+ fs_type = "ext4"
+ mount_flags = ["noatime"]
+}
+
+topology_request {
+ required {
+ topology { segments { "rack" = "R2" } }
+ topology { segments { "rack" = "R1", "zone" = "us-east-1a"} }
+ }
+}
+
+secrets {
+ example_secret = "xyzzy"
+}
+
+parameters {
+ skuname = "Premium_LRS"
+}
+
+context {
+ endpoint = "http://192.168.1.101:9425"
+}
+```
+
+[api_volume_create]: /api-docs/volumes#create-volume
+[api_volume_register]: /api-docs/volumes#register-volume
+[capability]: /docs/other-specifications/volume/capability
+[csi_plugin]: /docs/job-specification/csi_plugin
+[csi_volume_source]: /docs/job-specification/volume#source
+[mount_options]: /docs/other-specifications/volume/mount_options
+[topology_request]: /docs/other-specifications/volume/topology_request
+[`volume create`]: /docs/commands/volume/create
+[`volume register`]: /docs/commands/volume/register
diff --git a/website/content/docs/other-specifications/volume/mount_options.mdx b/website/content/docs/other-specifications/volume/mount_options.mdx
new file mode 100644
index 000000000..1074440c3
--- /dev/null
+++ b/website/content/docs/other-specifications/volume/mount_options.mdx
@@ -0,0 +1,44 @@
+---
+layout: docs
+page_title: mount_options Block - Volume Specification
+description: The "mount_options" block allows for configuring how a volume is mounted.
+---
+
+# `mount_options` Block
+
+
+
+Options for mounting `file-system` volumes that don't already have a
+pre-formatted file system.
+
+```hcl
+id = "ebs_prod_db1"
+namespace = "default"
+name = "database"
+type = "csi"
+plugin_id = "ebs-prod"
+capacity_max = "200G"
+capacity_min = "100G"
+
+mount_options {
+ fs_type = "ext4"
+ mount_flags = ["noatime"]
+}
+```
+
+This block will be validated during volume creation against the `capability`
+field. The `mount_options` provided in a job specification's [`volume`] block
+will override this block. Consult the documentation for your storage provider
+and CSI plugin as to whether these options are required or necessary.
+
+## `mount_options` Parameters
+
+- `fs_type` `(string )` - File system type (ex. `"ext4"`)
+- `mount_flags` `([]string: )` - The flags passed to `mount` (ex.
+ `["ro", "noatime"]`)
+
+[`volume`]: /docs/job-specification/volume
diff --git a/website/content/docs/other-specifications/volume/topology_request.mdx b/website/content/docs/other-specifications/volume/topology_request.mdx
new file mode 100644
index 000000000..0c1c6a8ae
--- /dev/null
+++ b/website/content/docs/other-specifications/volume/topology_request.mdx
@@ -0,0 +1,82 @@
+---
+layout: docs
+page_title: topology_request Block - Volume Specification
+description: The "topology_request" block allows specifying locations where the provisioned volume must be accessible from.
+---
+
+# `topology_request` Block
+
+
+
+Specify locations (region, zone, rack, etc.) where the provisioned volume must
+be accessible from or from where an existing volume is accessible from.
+
+```hcl
+id = "ebs_prod_db1"
+namespace = "default"
+name = "database"
+type = "csi"
+plugin_id = "ebs-prod"
+capacity_max = "200G"
+capacity_min = "100G"
+
+topology_request {
+ required {
+ topology { segments { rack = "R2" } }
+ topology { segments { rack = "R1", zone = "us-east-1a"} }
+ }
+ preferred {
+ topology { segments { rack = "R1", zone = "us-east-1a"} }
+ }
+}
+```
+
+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.
+
+## `topology_request` Parameters
+
+- `required` ([Topology][topology]: nil) - On **volume creation**,
+ the `required` topologies indicate that the volume must be created in a
+ location accessible from at least one of the listed topologies. On **volume
+ registration** the `required` topologies indicate that the volume was created
+ in a location accessible from all the listed topologies.
+
+- `preferred` ([Topology][topology]: nil) - Indicate that you
+ would prefer the storage provider to create the volume in one of the provided
+ topologies. Only allowed on **volume creation**.
+
+### `topology` Parameters
+
+- `segments` `(map[string]string)` - A map of location types to their values.
+ The specific fields required are defined by the CSI plugin.
+
+## `topology_request` Examples
+
+The following examples only show the `topology_request` blocks. Remember that
+the `topology_request` block is only valid in the placements listed above.
+
+### Volume creation with `preferred` and `required` topologies
+
+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`.
+
+```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"} }
+ }
+}
+```
+
+[topology]: #topology-parameters
diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json
index cce304dbc..52e6d4f25 100644
--- a/website/data/docs-nav-data.json
+++ b/website/data/docs-nav-data.json
@@ -1418,6 +1418,36 @@
}
]
},
+ {
+ "title": "Other Specifications",
+ "routes": [
+ {
+ "title": "Overview",
+ "path": "other-specifications"
+ },
+ {
+ "title": "Volume",
+ "routes": [
+ {
+ "title": "Overview",
+ "path": "other-specifications/volume"
+ },
+ {
+ "title": "capability",
+ "path": "other-specifications/volume/capability"
+ },
+ {
+ "title": "mount_options",
+ "path": "other-specifications/volume/mount_options"
+ },
+ {
+ "title": "topology_request",
+ "path": "other-specifications/volume/topology_request"
+ }
+ ]
+ }
+ ]
+ },
{
"title": "Task Drivers",
"routes": [