kemko/nomad
1
0
Fork 0
mirror of https://github.com/kemko/nomad.git synced 2026-01-10 12:25:42 +03:00
Code Issues Packages Projects Releases Wiki Activity

docs: dynamic host volume command line (#24814)

Browse Source 
Dynamic host volumes use some of the same commands as CSI volumes but with
different parameters, semantics, and inputs.

Ref: https://github.com/hashicorp/nomad/pull/24797
Ref: https://hashicorp.atlassian.net/browse/NET-11482

Co-authored-by: Aimee Ukasick <aimee.ukasick@hashicorp.com>
This commit is contained in:
Tim Gross
2025-01-15 16:12:01 -05:00
parent 0489c35110
commit 8330d406aa
5 changed files with 132 additions and 60 deletions
Download Patch File Download Diff File Expand all files Collapse all files

51
website/content/docs/commands/volume/create.mdx
View File

@@ -2,15 +2,19 @@
layout: docs
page_title: 'Commands: volume create'
description: |
Create volumes with CSI plugins.
The `nomad volume create` command creates storage volumes that are either
Container Storage Interface (CSI) volumes or dynamic host volumes.
---
# Command: volume create
The `volume create` command creates external storage volumes with Nomad's
[Container Storage Interface (CSI)][csi] support. Only CSI plugins that
implement the [Controller][csi_plugins_internals] interface support this
command. The volume will also be [registered] when it is successfully created.
The `volume create` command creates storage volumes as either [Container Storage
Interface (CSI)][csi] volumes or dynamic host volumes.
The [`volume create`][] command can create dynamic host volumes if host volume
plugins are installed on the node, or CSI volumes if the CSI plugins implement
the [Controller][csi_plugins_internals] interface. The `volume create` command
automatically [registers][] the volume as well.
## Usage
@@ -18,21 +22,41 @@ command. The volume will also be [registered] when it is successfully created.
nomad volume create [options] [file]
```
The `volume create` 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 volume will be submitted to Nomad for scheduling. If
the supplied path is "-", the volume file is read from STDIN. Otherwise it is
The `volume create` command requires a single argument, specifying the path to a
file containing a valid [volume specification][volume_specification]. Nomad
reads the file and submits the volume to the server for placement. If the
supplied path is "-", the volume file is read from STDIN. Otherwise the file 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.
When ACLs are enabled, this command requires a token with the appropriate
capability in the volume's namespace: the `csi-write-volume` capability for CSI
volumes or `host-volume-create` for dynamic host volumes.
## General Options
@include 'general_options.mdx'
## Volume Create Options
- `-detach`: Return immediately instead of entering monitor mode for dynamic
host volumes. After creating a volume, Nomad prints the volume ID to the
screen, which you can use to examine the volume using the `volume status`
command. If `-detach` is omitted or false, the command monitors the state of
the volume until it has been fingerprinted by the client and is ready to be
scheduled. Not valid for CSI volumes.
- `-verbose`: Display full information when monitoring volume state. Used for
dynamic host volumes only. Not valid for CSI volumes.
- `-policy-override`: Sets the flag to force override any soft mandatory
Sentinel policies. Used for dynamic host volumes only. Not valid for CSI
volumes.
## Volume Specification
Refer to the [CSI Volume Specification][csi_vol_spec] and the [Dynamic Host
Volume Specification](host_vol_spec) for further information.
<!--
Redirection rules are applied server-side, so we can't redirect these sections
that used to be located in this page since they use URL fragments. Creating
@@ -63,10 +87,11 @@ the exact section.
<span id="segments" />
<span id="unused-fields" />
The volume specification is documented in the [Volume
Specification][volume_specification] page.
[csi]: https://github.com/container-storage-interface/spec
[csi_plugins_internals]: /nomad/docs/concepts/plugins/csi#csi-plugins
[registers]: /nomad/docs/commands/volume/register
[registered]: /nomad/docs/commands/volume/register
[volume_specification]: /nomad/docs/other-specifications/volume
[csi_vol_spec]: /nomad/docs/other-specifications/volume/csi
[host_vol_spec]: /nomad/docs/other-specifications/volume/host

42
website/content/docs/commands/volume/delete.mdx
View File

@@ -2,16 +2,21 @@
layout: docs
page_title: 'Commands: volume delete'
description: |
Delete volumes with CSI plugins.
The `nomad volume delete` command deletes storage volumes that are either
Container Storage Interface (CSI) volumes or dynamic host volumes.
---
# Command: volume delete
The `volume delete` command deletes external storage volumes with Nomad's
[Container Storage Interface (CSI)][csi] support. Only CSI plugins that
implement the [Controller][csi_plugins_internals] interface support this
command. The volume will also be [deregistered] when it is successfully
deleted.
The `volume delete` command deletes storage volumes that are either [Container
Storage Interface (CSI)][csi] volumes or dynamic host volumes.
For CSI volumes, only CSI plugins that implement the
[Controller][csi_plugins_internals] interface support this command. The volume
is [deregistered][] when it is successfully deleted.
For dynamic host volumes, only volumes with plugins are deleted. Volumes without
plugins are deregistered without deleting them.
## Usage
@@ -20,24 +25,29 @@ nomad volume delete [options] [volume]
```
The `volume delete` command requires a single argument, specifying the ID of
volume to be deleted. The volume must still be [registered] with Nomad in
order to be deleted. Deleting will fail if the volume is still in use by an
volume to be deleted. The volume must still be [registered][] with Nomad in
order to be deleted. Deleting fails if the volume is still in use by an
allocation or in the process of being unpublished. If the volume no longer
exists, this command will silently return without an error.
exists, this command silently returns without an error.
When ACLs are enabled, this command requires a token with the
`csi-write-volume` capability for the volume's namespace.
When ACLs are enabled, this command requires a token with the appropriate
capability in the volume's namespace: the `csi-write-volume` capability for CSI
volumes or `host-volume-delete` for dynamic host volumes.
## General Options
@include 'general_options.mdx'
## Delete Options
- `-secret`: Secrets to pass to the plugin to delete the snapshot. Accepts
multiple flags in the form `-secret key=value`. Only available for CSI
volumes.
- `-type`: Type of volume to delete. Must be one of "csi" or "host". Defaults to
"csi".
[csi]: https://github.com/container-storage-interface/spec
[csi_plugins_internals]: /nomad/docs/concepts/plugins/csi#csi-plugins
[deregistered]: /nomad/docs/commands/volume/deregister
[registered]: /nomad/docs/commands/volume/register
## Delete Options
- `-secret`: Secrets to pass to the plugin to delete the
snapshot. Accepts multiple flags in the form `-secret key=value`

3
website/content/docs/commands/volume/deregister.mdx
View File

@@ -13,6 +13,9 @@ removed from Nomad's state store but not deleted from the external storage
provider. Note that deregistering a volume prevents Nomad from deleting it via
[`volume delete`] at a later time.
For dynamic host volumes, use the [`volume delete`][] command.
## Usage
```plaintext

3
website/content/docs/commands/volume/init.mdx
View File

@@ -20,6 +20,9 @@ nomad volume init
- `-json`: Create an example JSON volume specification.
- `-type`: Create an example for a specific type of volume. Use either "csi" or
"host", defaults to "csi".
## Examples
Create an example volume specification:

93
website/content/docs/commands/volume/register.mdx
View File

@@ -2,18 +2,22 @@
layout: docs
page_title: 'Commands: volume register'
description: |
Register volumes with CSI plugins.
The `nomad volume register` command registers storage volumes as either
Container Storage Interface (CSI) volumes or dynamic host volumes. The volume
must already exist on a node or remote storage provider before you can
register the volume for use in job task.
---
# Command: volume register
The `volume register` command registers external storage volumes with Nomad's
[Container Storage Interface (CSI)][csi] support. The volume must exist on the
remote storage provider before it can be registered and used by a task.
The `volume register` command registers storage volumes as either [Container
Storage Interface (CSI)][csi] volumes or dynamic host volumes. The volume must
already exist on a node or remote storage provider before you can register
the volume for use in job task.
CSI plugins that implement the [Controller][csi_plugins_internals] interface
can be created via the [`volume create`] command, which will automatically
register the volume as well.
To instead create a volume that does not already exist, use the [`volume
create`][] command. The `volume create` command automatically registers the
volume as well.
## Usage
@@ -21,21 +25,65 @@ register the volume as well.
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.
The `volume register` command requires a single argument, specifying the path to
a file containing a valid [volume specification][volume_specification]. Nomad
reads the file and submits the volume to the server for placement. If the
supplied path is "-", Nomad reads the volume file from STDIN. Otherwise Nomad
reads the file from the supplied path.
When ACLs are enabled, this command requires a token with the
`csi-write-volume` capability for the volume's namespace.
When ACLs are enabled, this command requires a token with the appropriate
capability in the volume's namespace: the `csi-write-volume` capability for CSI
volumes or `host-volume-register` for dynamic host volumes.
## General Options
@include 'general_options.mdx'
## Volume Register Options
- `-policy-override`: Sets the flag to force override any soft mandatory
Sentinel policies. Used for dynamic host volumes only. Not valid for CSI
volumes.
## Volume Specification
Refer to the [CSI Volume Specification][csi_vol_spec] and the [Dynamic Host
Volume Specification](host_vol_spec) for further information.
The `volume register` command allows updating a volume definition. However, you
can only update some fields after the volume is registered.
For CSI volumes:
- Update the `capacity_min` and `capacity_max` fields and increase
the volume size if the CSI plugin supports it. Expansion may or may not be
possible while the volume is in use, again depending on the plugin.
Reducing volume capacity is not allowed per the CSI spec.
- Add or remove the `capability` blocks, but only if the capability is
not currently in use by a mounted volume.
- Update the `mount_options` block if the volume is not in use.
- Update the `secrets` block.
- Update the `context` block. The values for this field are typically provided
by the CSI plugin, and you should not update them unless recommended by the
CSI plugin's documentation.
For dynamic host volumes:
- Update the `capacity_min` and `capacity_max` fields. The fields are ignored
but must be consistent with the `capacity` value if set.
- Update the `capacity` field to record that you've increased the size of the
volume. Reducing volume capacity is not allowed.
- Update the `constraint` fields on `volume create`, but not after you create the volume.
- Add or remove the `capability` blocks but only if a mounted volume is not
using currently using the capability.
- Change the `node_pool` field only from empty to the node pool that matches the
`node_id` field.
You cannot update the following:
- The `name`, `type`, and `plugin_id` fields.
- The `node_id` field.
<!--
Redirection rules are applied server-side, so we can't redirect these sections
that used to be located in this page since they use URL fragments. Creating
@@ -64,23 +112,6 @@ the exact section.
<span id="segments" />
<span id="unused-fields" />
The volume specification is documented in the [Volume
Specification][volume_specification] page.
Not all fields can be updated after the volume is registered:
* The `capacity_min` and `capacity_max` fields can be updated, and may increase
the volume size if the CSI plugin supports it. Expansion may or may not be
possible while the volume is in use, again depending on the plugin.
Reducing volume capacity is not allowed per the CSI spec.
* The `capability` blocks can be added or removed, but only if the capability is
not currently in use by a mounted volume.
* The `mount_options` block can be updated if the volume is not in use.
* The `secrets` block can be updated.
* The `context` block can be updated. The values for this field are typically
provided by the CSI plugin, and should not be updated unless recommended by
the CSI plugin's documentation.
[csi]: https://github.com/container-storage-interface/spec
[csi_plugins_internals]: /nomad/docs/concepts/plugins/csi#csi-plugins
[volume_specification]: /nomad/docs/other-specifications/volume