Merge pull request #6211 from hashicorp/f-host-volume-docs
docs: Initial documentation for volume(_mount)
This commit is contained in:
Michael Schurter
GitHub
commit
1a69911237
|
|
@ -154,6 +154,9 @@ driver) but will be removed in a future release.
|
|||
- `template` <code>([Template](#template-parameters): nil)</code> - Specifies
|
||||
controls on the behavior of task [`template`](/docs/job-specification/template.html) stanzas.
|
||||
|
||||
- `host_volume` <code>([host_volume](#host_volume-stanza): nil)</code> - Exposes
|
||||
paths from the host as volumes that can be mounted into jobs.
|
||||
|
||||
|
||||
### `chroot_env` Parameters
|
||||
|
||||
|
|
@ -349,6 +352,31 @@ see the [drivers documentation](/docs/drivers/index.html).
|
|||
files on the client host via the `file` function. By default templates can
|
||||
access files only within the task directory.
|
||||
|
||||
### `host_volume` Stanza
|
||||
|
||||
The `host_volume` stanza is used to make volumes available to jobs.
|
||||
|
||||
The key of the stanza corresponds to the name of the volume for use in the
|
||||
`source` parameter of a `"host"` type [`volume`](/docs/job-specification/volume.html)
|
||||
and ACLs.
|
||||
|
||||
```hcl
|
||||
client {
|
||||
host_volume "ca-certificates" {
|
||||
path = "/etc/ssl/certs"
|
||||
read_only = true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### `host_volume` Parameters
|
||||
|
||||
- `path` `(string: "", required)` - Specifies the path on the host that should
|
||||
be used as the source when this volume is mounted into a task. The path must
|
||||
exist on client startup.
|
||||
|
||||
- `read_only` `(bool: false)` - Specifies whether the volume should only ever be
|
||||
allowed to be mounted `read_only`, or if it should be writeable.
|
||||
|
||||
## `client` Examples
|
||||
|
||||
|
|
|
|||
|
|
@ -73,6 +73,9 @@ job "docs" {
|
|||
required by all tasks in this group. Overrides a `vault` block set at the
|
||||
`job` level.
|
||||
|
||||
- `volume` <code>([Volume][]: nil)</code> - Specifies the volumes that are
|
||||
required by tasks within the group.
|
||||
|
||||
## `group` Examples
|
||||
|
||||
The following examples only show the `group` stanzas. Remember that the
|
||||
|
|
@ -134,3 +137,4 @@ group "example" {
|
|||
[reschedule]: /docs/job-specification/reschedule.html "Nomad reschedule Job Specification"
|
||||
[restart]: /docs/job-specification/restart.html "Nomad restart Job Specification"
|
||||
[vault]: /docs/job-specification/vault.html "Nomad vault Job Specification"
|
||||
[volume]: /docs/job-specification/volume.html "Nomad volume Job Specification"
|
||||
|
|
|
|||
|
|
@ -0,0 +1,65 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "volume Stanza - Job Specification"
|
||||
sidebar_current: "docs-job-specification-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
|
||||
|
||||
<table class="table table-bordered table-striped">
|
||||
<tr>
|
||||
<th width="120">Placement</th>
|
||||
<td>
|
||||
<code>job -> group -> **volume**</code>
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
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"
|
||||
read_only = true
|
||||
|
||||
config {
|
||||
source = "ca-certificates"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
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. Currently the
|
||||
only possible volume type is `"host"`.
|
||||
|
||||
- `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.
|
||||
|
||||
- `config` `(json/hcl: nil)` - Specifies the configuration for the volume
|
||||
provider. For a `host_volume`, the only key is `source`, which is the name of
|
||||
the volume to request.
|
||||
|
||||
[volume_mount]: /docs/job-specification/volume_mount.html "Nomad volume_mount Job Specification"
|
||||
|
|
@ -0,0 +1,62 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "volume_mount Stanza - Job Specification"
|
||||
sidebar_current: "docs-job-specification-volume_mount"
|
||||
description: |-
|
||||
The "volume_mount" stanza allows the task to specify where a group "volume"
|
||||
should be mounted.
|
||||
---
|
||||
|
||||
# `volume_mount` Stanza
|
||||
|
||||
<table class="table table-bordered table-striped">
|
||||
<tr>
|
||||
<th width="120">Placement</th>
|
||||
<td>
|
||||
<code>job -> group -> task -> **volume_mount**</code>
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
The "volume_mount" stanza allows the task to specify how a group
|
||||
[`volume`][volume] should be mounted into the task.
|
||||
|
||||
```hcl
|
||||
job "docs" {
|
||||
group "example" {
|
||||
volume "certs" {
|
||||
type = "host"
|
||||
read_only = true
|
||||
|
||||
config {
|
||||
source = "ca-certificates"
|
||||
}
|
||||
}
|
||||
|
||||
task "example" {
|
||||
volume_mount {
|
||||
source = "certs"
|
||||
destination = "/etc/ssl/certs"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The Nomad client will make the volumes available to tasks according to this
|
||||
configuration, and it will fail the allocation if the client configuration
|
||||
updates to remove a volume that it depends on.
|
||||
|
||||
## `volume_mount` Parameters
|
||||
|
||||
- `source` `(string: "")` - Specifies the group volume that the mount is going
|
||||
to access.
|
||||
|
||||
- `destination` `(string: "")` - Specifies where the volume should be mounted
|
||||
inside the tasks container.
|
||||
|
||||
- `read_only` `(bool: false)` - When a group volume is writeable, you may
|
||||
specify that it is read_only on a per mount level using the `read_only` option
|
||||
here.
|
||||
|
||||
[volume]: /docs/job-specification/volume.html "Nomad volume Job Specification"
|
||||
|
|
@ -437,6 +437,12 @@
|
|||
<li<%= sidebar_current("docs-job-specification-vault")%>>
|
||||
<a href="/docs/job-specification/vault.html">vault</a>
|
||||
</li>
|
||||
<li<%= sidebar_current("docs-job-specification-volume")%>>
|
||||
<a href="/docs/job-specification/volume.html">volume</a>
|
||||
</li>
|
||||
<li<%= sidebar_current("docs-job-specification-volume_mount")%>>
|
||||
<a href="/docs/job-specification/volume_mount.html">volume_mount</a>
|
||||
</li>
|
||||
</ul>
|
||||
</li>
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue