From e3fb5bd78c9c01b88d54ee239c1bf608d2c94b6b Mon Sep 17 00:00:00 2001
From: Danielle Lancashire <dani@hashicorp.com>
Date: Mon, 26 Aug 2019 13:09:54 +0200
Subject: [PATCH] docs: Initial documentation for volume(_mount)

---
 .../docs/job-specification/group.html.md      |  4 ++
 .../docs/job-specification/volume.html.md     | 66 +++++++++++++++++++
 .../job-specification/volume_mount.html.md    | 62 +++++++++++++++++
 3 files changed, 132 insertions(+)
 create mode 100644 website/source/docs/job-specification/volume.html.md
 create mode 100644 website/source/docs/job-specification/volume_mount.html.md

diff --git a/website/source/docs/job-specification/group.html.md b/website/source/docs/job-specification/group.html.md
index 772893a27..1f4d68d88 100644
--- a/website/source/docs/job-specification/group.html.md
+++ b/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"
diff --git a/website/source/docs/job-specification/volume.html.md b/website/source/docs/job-specification/volume.html.md
new file mode 100644
index 000000000..ab8171eee
--- /dev/null
+++ b/website/source/docs/job-specification/volume.html.md
@@ -0,0 +1,66 @@
+---
+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. Nomad will automatically handle ensuring that the volume is
+available, and mounted into the task.
+
+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
+stanza's.
+
+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 `host_volume`'s, 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"
diff --git a/website/source/docs/job-specification/volume_mount.html.md b/website/source/docs/job-specification/volume_mount.html.md
new file mode 100644
index 000000000..58dd2416b
--- /dev/null
+++ b/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 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"