diff --git a/website/content/docs/concepts/stateful-deployments.mdx b/website/content/docs/concepts/stateful-deployments.mdx new file mode 100644 index 000000000..05f3c3714 --- /dev/null +++ b/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 + + + +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. + + + +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 diff --git a/website/content/docs/job-specification/volume.mdx b/website/content/docs/job-specification/volume.mdx index d976bbde4..925503b46 100644 --- a/website/content/docs/job-specification/volume.mdx +++ b/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 diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index 18df8fbe9..d7c9b11ed 100644 --- a/website/data/docs-nav-data.json +++ b/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"