diff --git a/website/content/docs/commands/volume/create.mdx b/website/content/docs/commands/volume/create.mdx index aa32fb98a..57cac585e 100644 --- a/website/content/docs/commands/volume/create.mdx +++ b/website/content/docs/commands/volume/create.mdx @@ -11,7 +11,7 @@ description: | 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 +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. diff --git a/website/content/docs/concepts/plugins/storage/host-volumes.mdx b/website/content/docs/concepts/plugins/storage/host-volumes.mdx index 719bbbdf8..df5caf368 100644 --- a/website/content/docs/concepts/plugins/storage/host-volumes.mdx +++ b/website/content/docs/concepts/plugins/storage/host-volumes.mdx @@ -13,6 +13,10 @@ This page describes the plugin specification for your own plugin to dynamically configure persistent storage on your Nomad client nodes. +Nomad has one built-in plugin called `mkdir`, which creates a directory on the +host in the Nomad agent's [host_volumes_dir][]. The `mkdir` plugin does not +support the `capacity_min` or `capacity_max` fields. + Review the examples first to get a sense of the specification in action. A plugin can be as basic as a short shell script. @@ -66,12 +70,12 @@ get_path() { stderr "DHV_VOLUMES_DIR must not be empty" exit 1 fi - if [ -z "$DHV_VOLUME_NAME" ]; then - stderr "DHV_VOLUME_NAME must not be empty" + if [ -z "$DHV_VOLUME_ID" ]; then + stderr "DHV_VOLUME_ID must not be empty" exit 1 fi # create and delete assign this echo output to a variable - echo "$DHV_VOLUMES_DIR/$DHV_VOLUME_NAME" + echo "$DHV_VOLUMES_DIR/$DHV_VOLUME_ID" } case "$DHV_OPERATION" in @@ -132,11 +136,11 @@ get_path() { stderr "DHV_VOLUMES_DIR must not be empty" exit 1 fi - if [ -z "$DHV_VOLUME_NAME" ]; then - stderr "DHV_VOLUME_NAME must not be empty" + if [ -z "$DHV_VOLUME_ID" ]; then + stderr "DHV_VOLUME_ID must not be empty" exit 1 fi - echo "$DHV_VOLUMES_DIR/$DHV_VOLUME_NAME" + echo "$DHV_VOLUMES_DIR/$DHV_VOLUME_ID" } is_mounted() { @@ -378,6 +382,10 @@ Plugin authors should consider these details when writing plugins. * Errors from `create` while restoring a volume during Nomad agent start do not halt the client. The error will be in client logs, and the volume is not registered as available on the node. +* Be aware that the `DHV_VOLUME_NAME` and `DHV_PARAMETERS` fields are controlled + by the volume author. If the expected volume authors are not the Nomad + administrators, you should ensure your plugin handles these fields safely or + ignores them. ### Uniqueness @@ -387,9 +395,10 @@ Plugin authors should consider these details when writing plugins. operations for different volume IDs may run concurrently, even on the same node. * We suggest placing volumes in `DHV_VOLUMES_DIR` for consistency, but it is not - required. Often `$DHV_VOLUMES_DIR/$DVH_VOLUME_NAME` will suffice, as the - volume `name` is unique per node, or `$DHV_VOLUMES_DIR/$DHV_VOLUME_ID` for - uniqueness per Nomad region. + required. The built-in `mkdir` plugin uses `$DHV_VOLUMES_DIR/$DHV_VOLUME_ID` + to ensure uniqueness across the cluster. We recommend against using + `DHV_VOLUME_NAME` in the path unless the plugin guards against path + traversal. * Plugins that write into network storage need to take care not to delete remote/shared state by `name`, unless they know that there are no other volumes with workloads using that name. @@ -416,3 +425,4 @@ Plugin authors should consider these details when writing plugins. [api-create]: /nomad/api-docs/volumes#create-dynamic-host-volume [cli-delete]: /nomad/docs/commands/volume/delete [api-delete]: /nomad/api-docs/volumes#delete-dynamic-host-volume +[host_volumes_dir]: /nomad/docs/configuration/client#host_volumes_dir diff --git a/website/content/docs/other-specifications/volume/host.mdx b/website/content/docs/other-specifications/volume/host.mdx index 2247142f9..173ad3606 100644 --- a/website/content/docs/other-specifications/volume/host.mdx +++ b/website/content/docs/other-specifications/volume/host.mdx @@ -47,8 +47,8 @@ the API. volume is somewhere between `capacity_min` and `capacity_max`; the exact behavior is up to the plugin. If you want to specify an exact size, set `capacity_min` and `capacity_max` to the same value. Accepts human-friendly - suffixes such as `"100GiB"`. Plugins that cannot restrict the size of volumes - may ignore this field. + suffixes such as `"100GiB"`. Plugins that cannot restrict the size of volumes, + such as the built-in `mkdir` plugin, may ignore this field. - `capacity_max` `(string: )` - Option for requesting a maximum capacity, in bytes. The capacity of a volume may be the physical size of a @@ -56,8 +56,8 @@ the API. volume is somewhere between `capacity_min` and `capacity_max`; the exact behavior is up to the plugin. If you want to specify an exact size, set `capacity_min` and `capacity_max` to the same value. Accepts human-friendly - suffixes such as `"100GiB"`. Plugins that cannot restrict the size of volumes - may ignore this field. + suffixes such as `"100GiB"`. Plugins that cannot restrict the size of volumes, + such as the built-in `mkdir` plugin, may ignore this field. - `capability` ([Capability][capability]: <required>) - Option for validating the capability of a volume. @@ -100,7 +100,9 @@ the API. of these parameters are specific to the plugin. - `plugin_id` `(string)` - The ID of the [dynamic host volume - plugin][dhv_plugin] that manages this volume. Required for volume creation. + plugin][dhv_plugin] that manages this volume. Required for volume + creation. Nomad has one built-in plugin called `mkdir`, which creates a + directory on the host in the Nomad agent's [host_volumes_dir][]. - `type` `(string: )` - The type of volume. Must be `"host"` for dynamic host volumes. @@ -305,3 +307,4 @@ registered. [`volume register`]: /nomad/docs/commands/volume/register [`volume status`]: /nomad/docs/commands/volume/status [dhv_plugin]: /nomad/docs/concepts/plugins/storage/host-volumes +[host_volumes_dir]: /nomad/docs/configuration/client#host_volumes_dir