diff --git a/website/content/docs/operations/stateful-workloads.mdx b/website/content/docs/operations/stateful-workloads.mdx
index e5c7da089..7a10f3a83 100644
--- a/website/content/docs/operations/stateful-workloads.mdx
+++ b/website/content/docs/operations/stateful-workloads.mdx
@@ -141,22 +141,32 @@ NFS/CIFS volume from a NAS or a public cloud service such as AWS EFS. Therefore
you can use host volumes for both local somewhat persistent storage and for
highly persistent networked storage.
-Because you need to declare host volumes in the Nomad agent's configuration
-file, you must restart the Nomad client to reconfigure them. This makes host
-volumes impractical if you frequently change your storage configuration.
-Furthermore, it might require coordination between different
-[personas](/nomad/docs/concepts/security#personas) to configure and consume
-host volumes. For example, a Nomad Administrator must modify Nomad's
-configuration file to add/update/remove host volumes to make them available for
-consumption by Nomad Operators. Or, with networked host volumes, a Storage
-Administrator will need to provision the volumes and make them available to the
-Nomad clients. A System Administrator will then mount them on the Nomad clients.
+Host volumes may be dynamic or static. Provision dynamic host volumes
+with the [`volume create`](/nomad/docs/commands/volume/create) command or
+API. [ACL policies](/nomad/docs/other-specifications/acl-policy#namespace-rules)
+allow delegation of control for storage within a namespace to Nomad
+Operators. The dynamic host volume [plugin
+specification](/nomad/docs/concepts/plugins/storage/host-volumes) allows you to
+develop plugins specific to your local storage environment. For example, in an
+on-prem cluster you could write a plugin to perform LVM thin-provisioning.
-Host volumes backed by local storage help persist data that is not critical, for
-example an on-disk cache that can be rebuilt if needed. When backed by networked
-storage such as NFS/CIFS-mounted volumes or distributed storage via
-GlusterFS/Ceph, host volumes provide a quick option to consume highly available
-and reliable storage.
+You declare static host volumes in the Nomad agent's configuration file, and
+you must restart the Nomad client to reconfigure them. This makes static host
+volumes impractical if you frequently change your storage
+configuration. Furthermore, it might require coordination between different
+[personas](/nomad/docs/concepts/security#personas) to configure and consume host
+volumes. For example, a Nomad Administrator must modify Nomad's configuration
+file to add, update, and remove host volumes to make them available for consumption by
+Nomad Operators. Or, with networked host volumes, a Storage Administrator
+needs to provision the volumes and makes them available to the Nomad clients. A
+System Administrator then mounts them on the Nomad clients.
+
+Host volumes backed by local storage help persist data that is not critical or
+can be readily restored. For example, an on-disk cache that can be rebuilt, or a
+clustered application where a single node can rebuild its state from the rest
+of the cluster. When backed by networked storage such as NFS/CIFS-mounted
+volumes or distributed storage with GlusterFS or Ceph, host volumes provide a quick
+option to consume highly available and reliable storage.
Refer to the [Stateful workloads with Nomad host
volumes](/nomad/tutorials/stateful-workloads/stateful-workloads-host-volumes)
@@ -205,8 +215,10 @@ choose the storage options that best addresses your Nomad storage requirements.
| Storage option | Advantages | Disadvantages | Ideal for |
|---|---|---|---|
| CSI volumes |
- Wide ecosystem with many providers
- Advanced features such as snapshots, cloning, and resizing
- Dynamic, flexible, and self-service (anyone with the correct ACL policies can create volumes on-demand)
| - Some complexity and ongoing maintenance
- Plugin upgrades have to follow the underlying storage provider's API changes/upgrades
- Not all CSI plugins implement all features
- Not all CSI plugins respect the CSI spec and are Nomad compatible
- Node plugins need to run in privileged mode to be able to mount the volumes in allocations
| - Environments where Nomad cluster operators and consumers need to easily add/change storage, and where the storage provider of choice has a CSI plugin that respects the CSI spec
|
-| Host volumes backed by local storage | - Readily available
- Fast due to being local
- Doesn't require ongoing maintenance
| - Requires coordination between multiple personas to configure and consume (operators running the Nomad clients need to configure them statically in the Nomad client's configuration file)
- Not fault tolerant. In case of hardware failure on a single instance, the data will be lost
| - Environments with low persistent storage requirements that could tolerate some failure but prefer not to or have high performance and low latency needs.
|
-| Host volumes backed by networked or clustered storage | - Readily available
- Require no ongoing maintenance on the Nomad side (but might on the storage provider)
| - Require coordination between multiple personas to configure and consume (storage admins need to provision volumes, operators running the Nomad clients need to configure them statically in the Nomad client's configuration file)
- The underlying networked storage and its limitations are decoupled from the consumer, but need to be understood. For example, is concurrent access possible
| - Environments with low amounts or low frequency of change of storage that have an existing storage provider that can be consumed via NFS/CIFS.
|
+| Dynamic host volumes backed by local storage | - Readily available
- Fast due to being local
- Doesn't require ongoing maintenance
| - Not fault tolerant. In case of hardware failure on a single instance, the data will be lost unless the application can restore the data
| - Environments with high performance and low latency persistent storage requirements where the application is designed to tolerate node failures.
|
+| Dynamic host volumes backed by networked or clustered storage | - Readily available
- Require no ongoing maintenance on the Nomad side (but might on the storage provider)
| - The underlying networked storage and its limitations are decoupled from the consumer, but need to be understood. For example, is concurrent access possible
| - Environments that have an existing storage provider that can be consumed via NFS/CIFS.
|
+| Static host volumes backed by local storage | - Readily available
- Fast due to being local
- Doesn't require ongoing maintenance
| - Requires coordination between multiple personas to configure and consume (operators running the Nomad clients need to configure them statically in the Nomad client's configuration file)
- Not fault tolerant. In case of hardware failure on a single instance, the data will be lost
| - Environments with low persistent storage requirements that could tolerate some failure but prefer not to or have high performance and low latency needs.
|
+| Static host volumes backed by networked or clustered storage | - Readily available
- Require no ongoing maintenance on the Nomad side (but might on the storage provider)
| - Require coordination between multiple personas to configure and consume (storage admins need to provision volumes, operators running the Nomad clients need to configure them statically in the Nomad client's configuration file)
- The underlying networked storage and its limitations are decoupled from the consumer, but need to be understood. For example, is concurrent access possible
| - Environments with low amounts or low frequency of change of storage that have an existing storage provider that can be consumed via NFS/CIFS.
|
| Ephemeral disks | - Fast due to being local
- Basic best effort persistence, including optional migration across Nomad clients
| - Not fault tolerant. In case of hardware failure on a single instance, the data will be lost
| - Environments that need temporary caches, somewhere to store files undergoing processing, etc. Everything which is ephemeral and can be easily rebuilt.
|
## Additional resources
@@ -222,7 +234,7 @@ following resources:
### CSI
-- [Nomad CSI plugin concepts](/nomad/docs/concepts/plugins/csi)
+- [Nomad CSI plugin concepts](/nomad/docs/concepts/plugins/storage/csi)
- [Nomad CSI
tutorial](/nomad/tutorials/stateful-workloads/stateful-workloads-csi-volumes)
- [Nomad CSI examples](https://github.com/hashicorp/nomad/tree/main/demo/csi)
@@ -232,3 +244,8 @@ following resources:
- [JuiceFS CSI with Nomad](https://juicefs.com/docs/csi/csi-in-nomad/)
- [Hetzner CSI](https://github.com/hetznercloud/csi-driver/blob/main/docs/nomad/README.md)
- [NFS CSI Plugin](https://gitlab.com/rocketduck/csi-plugin-nfs)
+
+### Dynamic Host Volumes
+
+- [Dynamic host volume plugins](/nomad/docs/concepts/plugins/storage/host-volumes)
+- [Dynamic host volume tutorial](/nomad/tutorial/stateful-workloads/stateful-workloads-dynamic-host-volumes)