open-nomad/website/pages/docs/job-specification/volume.mdx

---
layout: docs
page_title: volume Stanza - Job Specification
sidebar_title: volume
description: >-
  The "volume" stanza allows the group to specify that it requires a given
  volume from the cluster. Nomad will automatically handle ensuring that the
  volume is available and mounted into the task.
---

# `volume` Stanza

<Placement groups={['job', 'group', 'volume']} />

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.

```hcl
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][host_volume]
configured on the client, or [CSI volumes][csi_volume] dynamically
mounted by [CSI plugins][csi_plugin].

The Nomad client will make the volumes available to tasks according to
the [volume_mount][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.

```hcl
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.

```shell-session
$ 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
```


[volume_mount]: /docs/job-specification/volume_mount 'Nomad volume_mount Job Specification'
[host_volume]: /docs/configuration/client#host_volume-stanza
[csi_volume]: /docs/commands/volume/register
[csi_plugin]: /docs/job-specification/csi_plugin
[csi_volume]: /docs/commands/volume/register
[attachment mode]: /docs/commands/volume/register#attachment_mode
[volume registration]: /docs/commands/volume/register#mount_options
[HCL2]: /docs/job-specification/hcl2
[GH-8212]: https://github.com/hashicorp/nomad/issues/8212