stateful deployments: concept and jobspec documentation (#25288)

website/content/docs/concepts/stateful-deployments.mdx

@@ -0,0 +1,70 @@
+---
+layout: docs
+page_title: Stateful deployments
+description: |-
+  Learn how Nomad handles stateful deployments. Use a dynamic host volume for your stateful workload and bind an allocation to a volume ID with the sticky parameter. Learn how Nomad scales jobs with sticky volumes. 
+---
+
+# Stateful deployments
+
+<Note>
+
+Stateful deployments support only dynamic host volumes. For CSI volumes, use the
+[`per_alloc` property](/nomad/docs/job-specification/volume#per_alloc), 
+which serves a similar purpose.
+
+</Note>
+
+Nomad stateful deployments let you effectively bind your jobs to host [volumes].
+On a lower level, this means taking Nomad's basic unit of workload placement,
+the [allocation], and making it possible for you to have allocations that are
+[sticky] to volume IDs. Since stateful deployments only support dynamic host
+volumes, using them effectively means binding a job to a particular node.
+
+Stateful deployments work on a per-task-group basis. Use the `volume.sticky`
+parameter in your job specification to indicate that each task group requires a
+sticky host volume.
+
+This example sets the volume's `sticky` parameter to `true`.
+
+```hcl
+job "app" {
+  group "example" {
+    # ...
+    volume "example" {
+      type      = "host"
+      source    = "ca-certificates"
+      read_only = true
+      sticky    = true
+    }
+    # ...
+  }
+}
+```
+
+If you set the volume to sticky, during the deployment the scheduler associates
+its ID with the task group that uses it. Stateful deployments require that any
+allocations belonging to that task group must be places or replaced on nodes
+that have this volume ID available.
+
+Scaling jobs with sticky volumes up results in more volume IDs claimed by the
+task group, but scaling jobs down does not delete unused volumes, nor does it
+touch the data present on them.
+
+If the scheduler cannot find a node that has the right volume ID present,
+perhaps because the node is down or disconnected, Nomad creates a blocked
+evaluation.
+
+## Related resources
+
+Refer to the following Nomad pages for more information about stateful workloads
+and volumes:
+
+- [Considerations for Stateful Workloads](/nomad/docs/operations/stateful-workloads) explores the options for persistent storage of workloads running in Nomad.
+- The [Nomad volume specification][volumes] defines the schema for creating and registering volumes. 
+- The [job specification `volume` block](/nomad/docs/job-specification/volume) lets you configure a group that requires a specific volume from the cluster.
+- The [Stateful Workloads](/nomad/tutorials/stateful-workloads) tutorials explore techniques to run jobs that require access to persistent storage.
+ 
+[allocation]: /nomad/docs/glossary#allocation
+[sticky]: /nomad/docs/job-specification/volume#sticky
+[volumes]: /nomad/docs/other-specifications/volume

website/content/docs/job-specification/volume.mdx

@@ -76,6 +76,13 @@ the [volume_mount][volume_mount] block in the `task` configuration.
   used for validating `host_volume` ACLs and for scheduling when a
   matching `host_volume` requires `read_only` usage.
 
+- `sticky` `(bool: false)` - Specifies that this volume sticks to the allocation
+  that uses it. Upon every reschedule and replacement, the task
+  group always receives the volume with the same ID, if available. Use sticky
+  volumes for [stateful deployments]. You may only use the `sticky` field for
+  dynamic host volumes. For CSI volumes, the `per_alloc` field provides similar
+  functionality
+
 - `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
@@ -84,7 +91,9 @@ the [volume_mount][volume_mount] block in the `task` configuration.
   volume ID `myvolume[0]`.
 
   The `per_alloc` field cannot be true for system jobs, sysbatch jobs, or jobs
-  that use canaries.
+  that use canaries. `per_alloc` is mutually exclusive with the `sticky`
+  property. Use `per_alloc` only with CSI volumes and `sticky` only
+  with dynamic host volumes.
 
 The following fields are only valid for volumes with `type = "csi"` or dynamic
 host volumes with `type = "host"`:
@@ -235,5 +244,6 @@ ID        Node ID   Task Group  Version  Desired  Status   Created  Modified
 [attachment mode]: /nomad/docs/commands/volume/register#attachment_mode
 [volume registration]: /nomad/docs/commands/volume/register#mount_options
 [dynamic host volumes]: /nomad/docs/other-specifications/volume/host
+[stateful deployments]: /nomad/docs/concepts/stateful-deployments
 [`volume create`]: /nomad/docs/commands/volume/create
 [`volume register`]: /nomad/docs/commands/volume/register

website/data/docs-nav-data.json

@@ -251,6 +251,10 @@
         "title": "Job",
         "path": "concepts/job"
       },
+      {
+        "title": "Stateful Deployments",
+        "path": "concepts/stateful-deployments"
+      },
       {
         "title": "Workload Identity",
         "path": "concepts/workload-identity"