volume Stanza

The volume stanza allows the group to specify that it requires a given volume from the cluster.

The key of the stanza is the name of the volume as it will be exposed to task configuration.

job "docs" {
  group "example" {
    volume "certs" {
      type      = "host"
      source    = "ca-certificates"
      read_only = true
    }
  }
}

The Nomad server will ensure that the allocations are only scheduled on hosts that have a set of volumes that meet the criteria specified in the volume stanzas. These may be host volumes configured on the client, or CSI volumes dynamically mounted by CSI plugins.

The Nomad client will make the volumes available to tasks according to the volume_mount stanza in the task configuration.

volume Parameters

• type (string: "") - Specifies the type of a given volume. The valid volume types are "host" and "csi".

• source (string: <required>) - The name of the volume to request. When using host_volume's this should match the published name of the host volume. When using csi volumes, this should match the ID of the registered volume.

• read_only (bool: false) - Specifies that the group only requires read only access to a volume and is used as the default value for the volume_mount -> read_only configuration. This value is also used for validating host_volume ACLs and for scheduling when a matching host_volume requires read_only usage.

• mount_options - Options for mounting CSI volumes that have the file-system attachment mode. These options override the mount_options field from volume registration. Consult the documentation for your storage provider and CSI plugin as to whether these options are required or necessary.

  • fs_type: file system type (ex. "ext4")
  • mount_flags: the flags passed to mount (ex. "ro,noatime")

Volume Interpolation

Because volumes represent state, many workloads with multiple allocations will want to mount specific volumes to specific tasks. You can use the HCL2 syntax in Nomad 1.0 for fine-grained control over how volumes are used.

There are two limitations to using HCL2 interpolation for volume blocks:

• The volume block is used to schedule workloads, so any interpolation needs to be done before placement. This means that variables like NOMAD_ALLOC_INDEX can't be used for interpolation.
• Nomad does not yet support dynamic volume creation (see GH-8212), so volumes must be created and registered before being used as a volume.source.

The following job specification demonstrates how to use multiple volumes with multiple allocations. It uses a dynamic block to create a new task group for each of the two volumes. This job specification also shows using HCL2 variables interpolation to expose information to the task's environment.

variables {
  volume_index = ["0", "1"]
  path         = "test"
}

job "example" {
  datacenters = ["dc1"]

  dynamic "group" {
    for_each = var.volume_index
    labels   = ["cache-${group.value}"]

    content {

      volume "cache-volume" {
        type   = "csi"
        source = "test-volume${group.value}"
      }

      network {
        port "db" {
          to = 6379
        }
      }

      task "redis" {
        driver = "docker"
        config {
          image = "redis:3.2"
          ports = ["db"]
        }
        resources {
          cpu    = 500
          memory = 256
        }

        env {
          # this will be available as the MOUNT_PATH environment
          # variable in the task
          MOUNT_PATH = "${NOMAD_ALLOC_DIR}/${var.path}"
        }

        volume_mount {
          volume      = "cache-volume"
          destination = "${NOMAD_ALLOC_DIR}/${var.path}"
        }

      }
    }
  }
}

The job that results from this job specification has two task groups, each one named for each of the two volumes. Each allocation has its own volume.

$ nomad job status example
ID            = example
...

Allocations
ID        Node ID   Task Group  Version  Desired  Status   Created  Modified
81d32909  352c6926  cache-1     0        run      running  4s ago   3s ago
ce6fbfc8  352c6926  cache-0     0        run      running  4s ago   3s ago

$ nomad volume status test-volume0
...
Allocations
ID        Node ID   Task Group  Version  Desired  Status   Created  Modified
ce6fbfc8  352c6926  cache-0     0        run      running  29s ago  18s ago

$ nomad volume status test-volume1
...
Allocations
ID        Node ID   Task Group  Version  Desired  Status   Created  Modified
81d32909  352c6926  cache-0     0        run      running  29s ago  18s ago