175 lines
5.5 KiB
Plaintext
175 lines
5.5 KiB
Plaintext
---
|
|
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
|