From 842b0bdb8831ded40ae6ed5db2631ec2c1ea983c Mon Sep 17 00:00:00 2001 From: Luiz Aoqui Date: Mon, 13 Jun 2022 17:56:46 -0400 Subject: [PATCH] docs: create volume spec page In addition to jobs, there are other objects in Nomad that have a specific format and can be provided to commands and API endpoints. This commit creates a new menu section to hold the specification for volumes and update the command pages to point to the new centralized definition. Redirecting the previous entries is not possible with `redirect.js` because they are done server-side and URL fragments are not accessible to detect a match. So we provide hidden anchors with a link to the new page to guide users towards the new documentation. --- .../content/docs/commands/volume/create.mdx | 220 +++--------------- .../content/docs/commands/volume/register.mdx | 201 +++------------- .../docs/other-specifications/index.mdx | 15 ++ .../volume/capability.mdx | 73 ++++++ .../other-specifications/volume/index.mdx | 168 +++++++++++++ .../volume/mount_options.mdx | 44 ++++ .../other-specifications/volume/topology.mdx | 57 +++++ .../volume/topology_request.mdx | 77 ++++++ website/data/docs-nav-data.json | 34 +++ 9 files changed, 536 insertions(+), 353 deletions(-) create mode 100644 website/content/docs/other-specifications/index.mdx create mode 100644 website/content/docs/other-specifications/volume/capability.mdx create mode 100644 website/content/docs/other-specifications/volume/index.mdx create mode 100644 website/content/docs/other-specifications/volume/mount_options.mdx create mode 100644 website/content/docs/other-specifications/volume/topology.mdx create mode 100644 website/content/docs/other-specifications/volume/topology_request.mdx diff --git a/website/content/docs/commands/volume/create.mdx b/website/content/docs/commands/volume/create.mdx index 3dc68f39de8..f0155a6be54 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 63b3cb280ab..18f3052a3f8 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 00000000000..f4c4181075d --- /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 00000000000..7be8ba6b3bc --- /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 placements listed 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 00000000000..274cf98d8ba --- /dev/null +++ b/website/content/docs/other-specifications/volume/index.mdx @@ -0,0 +1,168 @@ +--- +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**. + +[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 00000000000..9d99f5434a8 --- /dev/null +++ b/website/content/docs/other-specifications/volume/mount_options.mdx @@ -0,0 +1,44 @@ +--- +layout: docs +page_title: mout_options Block - Volume Specification +description: The "mout_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.mdx b/website/content/docs/other-specifications/volume/topology.mdx new file mode 100644 index 00000000000..1dfc705d834 --- /dev/null +++ b/website/content/docs/other-specifications/volume/topology.mdx @@ -0,0 +1,57 @@ +--- +layout: docs +page_title: topology Block - Volume Specification +description: The "topology" block specifies the details of a topology request. +--- + +# `topology` Block + + + +Define the details of a topology requirement. + +```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"} } + } +} +``` + +## `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` Examples + +The following examples only show the `topology` blocks. Remember that the +`topology` block is only valid in the placements listed above. + +### Defining a `rack` and `zone` locations + +```hcl +topology { + segments { + rack = "R1", + zone = "us-east-1a" + } +} +``` 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 00000000000..b6370bbc274 --- /dev/null +++ b/website/content/docs/other-specifications/volume/topology_request.mdx @@ -0,0 +1,77 @@ +--- +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 registration**. + +## `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]: /docs/other-specifications/volume/topology diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index cce304dbc31..35ab42b9889 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -1418,6 +1418,40 @@ } ] }, + { + "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", + "path": "other-specifications/volume/topology" + }, + { + "title": "topology_request", + "path": "other-specifications/volume/topology_request" + } + ] + } + ] + }, { "title": "Task Drivers", "routes": [