29a5454894
The CSI specification for `ValidateVolumeCapability` says that we shall "reconcile successful capability-validation responses by comparing the validated capabilities with those that it had originally requested" but leaves the details of that reconcilation unspecified. This API is not implemented in Kubernetes, so controller plugins don't have a real-world implementation to verify their behavior against. We have found that CSI plugins in the wild may return "successful" but incomplete `VolumeCapability` responses, so we can't require that all capabilities we expect have been validated, only that the ones that have been validated match. This appears to violate the CSI specification but until that's been resolved in upstream we have to loosen our validation requirements. The tradeoff is that we're more likely to have runtime errors during `NodeStageVolume` instead of at the time of volume registration.
75 lines
2.7 KiB
Plaintext
75 lines
2.7 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_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
|