Merge pull request #6211 from hashicorp/f-host-volume-docs

docs: Initial documentation for volume(_mount)

website/source/docs/configuration/client.html.md

@@ -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
 

website/source/docs/job-specification/group.html.md

@@ -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"

website/source/docs/job-specification/volume.html.md

@@ -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"

website/source/docs/job-specification/volume_mount.html.md

@@ -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"

website/source/layouts/docs.erb

@@ -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>