Stateful deployments

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.

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.

Task group host volume claims

Nomad uses its state store to save associations of host volume IDs and their task groups, as well as job IDs, volume names, and namespaces. Use the API to list and delete these associations. If you delete a task group host volume claim, Nomad assigns a different volume ID to the task group, assuming the old volume ID is unavailable and another feasible host volume with matching name is. However, after placement, Nomad once again records the claim in its state store. You should only use claim deletions in operational emergency situations or while debugging problems with nodes. For example, use claim deletions in situations where you want to drain a node with a stateful deployment on it, but do not want to stop the job.

Related resources

Refer to the following Nomad pages for more information about stateful workloads and volumes:

• Considerations for Stateful Workloads explores the options for persistent storage of workloads running in Nomad.
• The Nomad volume specification defines the schema for creating and registering volumes.
• The job specification volume block lets you configure a group that requires a specific volume from the cluster.
• The Stateful Workloads tutorials explore techniques to run jobs that require access to persistent storage.