From 73c95a92b0b0785d8d9a011647769bfe69d5d846 Mon Sep 17 00:00:00 2001 From: Tim Gross Date: Tue, 6 Apr 2021 14:29:28 -0400 Subject: [PATCH] docs: update CSI create/register fields Add new `access_mode`/`attachment_mode` fields. Make it more clear which set of fields belong to create vs register. Update the example spec that's generated by `volume init`. --- command/volume_init.go | 13 ++--- .../content/docs/commands/volume/create.mdx | 43 ++++++++-------- .../content/docs/commands/volume/register.mdx | 35 +++---------- .../content/docs/job-specification/volume.mdx | 49 ++++++++++++++++--- 4 files changed, 81 insertions(+), 59 deletions(-) diff --git a/command/volume_init.go b/command/volume_init.go index 12402b9ef..94f55a036 100644 --- a/command/volume_init.go +++ b/command/volume_init.go @@ -125,10 +125,11 @@ snapshot_id = "snap-12345" capacity_min = "10GiB" capacity_max = "20G" -# Optional: for 'nomad volume create', specify one or more capabilities to -# validate. Registering an existing volume will record but ignore these fields. +# Required (at least one): for 'nomad volume create', specify one or more +# capabilities to validate. Registering an existing volume will record but +# ignore these fields. capability { - access_mode = "single-node-writer" + access_mode = "single-node-writer" attachment_mode = "file-system" } @@ -137,9 +138,9 @@ capability { attachment_mode = "block-device" } -# Optional: for 'nomad volume create', specify mount options to -# validate. Registering an existing volume will record but ignore these -# fields. +# Optional: for 'nomad volume create', specify mount options to validate for +# 'attachment_mode = "file-system". Registering an existing volume will record +# but ignore these fields. mount_options { fs_type = "ext4" mount_flags = ["ro"] diff --git a/website/content/docs/commands/volume/create.mdx b/website/content/docs/commands/volume/create.mdx index c24015677..d8ee1e6ce 100644 --- a/website/content/docs/commands/volume/create.mdx +++ b/website/content/docs/commands/volume/create.mdx @@ -39,7 +39,6 @@ The file may be provided as either HCL or JSON. An example HCL configuration: id = "ebs_prod_db1" name = "database" type = "csi" -external_id = "vol-23452345" plugin_id = "ebs-prod" snapshot_id = "snap-12345" # or clone_id, see below @@ -48,12 +47,14 @@ capacity { limit = "200G" } -access_mode = "single-node-writer" -attachment_mode = "file-system" +capability { + access_mode = "single-node-reader-only" + attachment_mode = "file-system" +} -mount_options { - fs_type = "ext4" - mount_flags = ["ro"] +capability { + access_mode = "single-node-writer" + attachment_mode = "file-system" } secrets { @@ -75,15 +76,12 @@ context { [`volume.source`][csi_volume_source] field in a job specification will refer to the volume. -- `name` `(string: )` - The display name of the volume. +- `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. -- `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. @@ -109,9 +107,10 @@ context { suffixes such as `"100GiB"`. This field may not be supported by all storage providers. -- `capability` `(optional)` - Option for validating the capbility of a - volume. You may provide multiple `capability` blocks, each of which must - have the following fields: +- `capability` `(Capability: )` - Option for validating the + capbility 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"`, @@ -127,9 +126,10 @@ context { within the container. - `mount_options` - Options for mounting `file-system` volumes that don't - already have a pre-formatted file system. Consult the documentation for your - storage provider and CSI plugin as to whether these options are required or - necessary. + already have a pre-formatted file system. These field will be validated + during volume creation against the `capability` field. 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` @@ -145,9 +145,11 @@ context { to each storage provider, so please see the specific plugin documentation for more information. -- `context` (map:nil) - This field is only used - during volume registration, and will be set automatically by the plugin when - `volume create` is successful. See [`volume register`]. +### 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. [csi]: https://github.com/container-storage-interface/spec [csi_plugins_internals]: /docs/internals/plugins/csi#csi-plugins @@ -156,3 +158,4 @@ context { [csi_volume_source]: /docs/job-specification/volume#source [registered]: /docs/commands/volume/register [`volume register`]: /docs/commands/volume/register +[`volume`]: /docs/job-specification/volume diff --git a/website/content/docs/commands/volume/register.mdx b/website/content/docs/commands/volume/register.mdx index 1fe894bb1..d941d74f8 100644 --- a/website/content/docs/commands/volume/register.mdx +++ b/website/content/docs/commands/volume/register.mdx @@ -45,15 +45,6 @@ name = "database" type = "csi" external_id = "vol-23452345" plugin_id = "ebs-prod" -snapshot_id = "snap-12345" # or clone_id, see below -capacity = "100G" -access_mode = "single-node-writer" -attachment_mode = "file-system" - -mount_options { - fs_type = "ext4" - mount_flags = ["ro"] -} secrets { example_secret = "xyzzy" @@ -86,24 +77,6 @@ context { - `plugin_id` `(string: )` - The ID of the [CSI plugin][csi_plugin] that manages this volume. -- `snapshot_id` - This field is only used during volume creation, and is - ignored during volume registration. See [`volume create`]. - -- `clone_id` - This field is only used during volume creation, and is ignored - during volume registration. See [`volume create`]. - -- `capacity_min` - This field is only used during volume creation, and is - ignored during volume registration. See [`volume create`]. - -- `capacity_max` - This field is only used during volume creation, and is - ignored during volume registration. See [`volume create`]. - -- `capability` - This field is only used during volume creation, and is - ignored during volume registration. See [`volume create`]. - -- `mount_options` - This field is only used during volume creation, and is - ignored during volume registration. See [`volume create`]. - - `secrets` (map:nil) - An optional key-value map of strings used as credentials for publishing and unpublishing volumes. @@ -120,6 +93,14 @@ context { each storage provider, so please see the specific plugin documentation for more information. +### 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`, `capacity_max`, or `capability` fields described +on that page. + [csi]: https://github.com/container-storage-interface/spec [csi_plugins_internals]: /docs/internals/plugins/csi#csi-plugins [volume_specification]: #volume-specification diff --git a/website/content/docs/job-specification/volume.mdx b/website/content/docs/job-specification/volume.mdx index 08c98c1fc..b215c67c3 100644 --- a/website/content/docs/job-specification/volume.mdx +++ b/website/content/docs/job-specification/volume.mdx @@ -29,6 +29,27 @@ job "docs" { } ``` +```hcl +job "docs" { + group "example" { + volume "data" { + type = "csi" + source = "csi-volume" + read_only = true + attachment_mode = "file-system" + access_mode = "single-node-writer" + per_alloc = true + + mount_options { + fs_type = "ext4" + mount_flags = "noatime" + } + } + } +} +``` + + The Nomad server will ensure that the allocations are only scheduled on hosts that have a set of volumes that meet the criteria specified in the `volume` stanzas. These may be [host volumes][host_volume] @@ -48,18 +69,34 @@ the [volume_mount][volume_mount] stanza in the `task` configuration. name of the host volume. When using `csi` volumes, this should match the ID of the registered volume. -- `per_alloc` `(bool: false)` - Specifies that the `source` of the volume - should have the suffix `[n]`, where `n` is the allocation index. This allows - mounting a unique volume per allocation, so long as the volume's source is - named appropriately. For example, with the source `myvolume` and `per_alloc = true`, the allocation named `myjob.mygroup.mytask[0]` will require a - volume ID `myvolume[0]`. - - `read_only` `(bool: false)` - Specifies that the group only requires read only access to a volume and is used as the default value for the `volume_mount -> read_only` configuration. This value is also used for validating `host_volume` ACLs and for scheduling when a matching `host_volume` requires `read_only` usage. +The following fields are only valid for volumes with `type = "csi"`: + +- `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. + +- `per_alloc` `(bool: false)` - Specifies that the `source` of the volume + should have the suffix `[n]`, where `n` is the allocation index. This allows + mounting a unique volume per allocation, so long as the volume's source is + named appropriately. For example, with the source `myvolume` and `per_alloc + = true`, the allocation named `myjob.mygroup.mytask[0]` will require a + volume ID `myvolume[0]`. + - `mount_options` - Options for mounting CSI volumes that have the `file-system` [attachment mode]. These options override the `mount_options` field from [volume registration]. Consult the documentation for your storage