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`.
This commit is contained in:
Tim Gross
Tim Gross
parent
276633673d
commit
70f5363a89
|
|
@ -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"]
|
||||
|
|
|
|||
|
|
@ -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: <required>)` - The display name of the volume.
|
||||
- `name` `(string: <required>)` - The display name of the volume. This field
|
||||
may be used by the external storage provider to tag the volume.
|
||||
|
||||
- `type` `(string: <required>)` - The type of volume. Currently only `"csi"`
|
||||
is supported.
|
||||
|
||||
- `external_id` `(string: <required>)` - 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: <required>)` - 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: <required>)` - 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: <required>)` - 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 <optional>)` - File system type (ex. `"ext4"`)
|
||||
- `mount_flags` `([]string: <optional>)` - 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` <code>(map<string|string>:nil)</code> - 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
|
||||
|
|
|
|||
|
|
@ -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: <required>)` - 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` <code>(map<string|string>:nil)</code> - 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
|
||||
|
|
|
|||
|
|
@ -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: <required>)` - 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: <required>)` - 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
|
||||
|
|
|
|||
Loading…
Reference in New Issue