docs: expand info on built-in mkdir dynamic host volume plugin (#25524)

Describe the built-in `mkdir` plugin in the plugin concepts docs in a little
more detail. Crosslink to there from the `plugin_id` field docs, and clarify
that the `mkdir` plugin doesn't support the capacity request fields.

Update the example plugins to avoid using volume author controlled variables in
favor of Nomad-controlled ones, to reduce the risk of path traversal, and
explain to plugin authors they'll likely want to avoid this in their own
plugins.

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.

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

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: <optional>)` - 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` <code>([Capability][capability]: &lt;required&gt;)</code> -
   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: <required>)` - 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