Add template example

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

@@ -0,0 +1,108 @@
+---
+layout: "docs"
+page_title: "template Stanza - Job Specification"
+sidebar_current: "docs-job-specification-template"
+description: |-
+  The "template" block instantiates an instance of a template renderer. This
+  creates a convenient way to ship configuration files that are populated from
+  Consul data, Vault secrets, or just general configurations within a Nomad
+  task.
+---
+
+# `template` Stanza
+
+<table class="table table-bordered table-striped">
+  <tr>
+    <th width="120">Placement</th>
+    <td>
+      <code>job -> group -> task -> **template**</code>
+    </td>
+  </tr>
+</table>
+
+The `template` block instantiates an instance of a template renderer. This
+creates a convenient way to ship configuration files that are populated from
+Consul data, Vault secrets, or just general configurations within a Nomad task.
+
+```hcl
+job "docs" {
+  group "example" {
+    task "server" {
+      template {
+        source        = "local/redis.conf.tpl"
+        destination   = "local/redis.conf"
+        change_mode   = "signal"
+        change_signal = "SIGNINT"
+      }
+    }
+  }
+}
+```
+
+Nomad is utilizes a tool called [Consul Template][ct]. For a full list of the
+API template functions, please see the [Consul Template README][ct].
+
+## `template` Parameters
+
+- `source` `(string: "")` - Specifies the path to the template to be rendered.
+  One of `source` or `data` must be specified, but not both. This source can
+  optionally be fetched using an [`artifact`][artifact] resource.
+
+- `destination` `(string: required)` - Specifies the location where the resulting template should be rendered, relative to the task directory.
+
+- `data` `(string: "")` - Specifies the raw template to execute. One of `source`
+  or `data` must be specified, but not both. This is useful for smaller
+  templates, but we recommend using `source` for larger templates.
+
+- `change_mode` `(string: "restart")` - Specifies the behavior Nomad should take if the Vault token changes. The possible values are:
+
+  - `"noop"` - take no action (continue running the task)
+  - `"restart"` - restart the task as per the task's [restart policy][restart]
+  - `"signal"` - send a configurable signal to the task
+
+- `change_signal` `(string: "")` - Specifies the signal to send to the task as a
+  string like `"SIGUSR1"` or `"SIGINT"`. This option is required if the
+  `change_mode` is `signal`.
+
+- `splay` `(string: "5s")` - Specifies a random amount of time to wait between
+  0ms and the given splay value before invoking the change mode. This is
+  specified using a label suffix like "30s" or "1h", and is often used to
+  prevent a thundering herd problem where all task instances restart at the same
+  time.
+
+## `template` Examples
+
+The following examples only show the `template` stanzas. Remember that the
+`template` stanza is only valid in the placements listed above.
+
+### Inline Template
+
+This example uses an inline template to render a controlled file to disk. This
+file watches various keys in Consul for changes:
+
+```hcl
+template {
+  data        = "---\nkey: {{ key \"service/my-key\" }}"
+  destination = "local/file.yml"
+}
+```
+
+### Remote Template
+
+This example uses an [`artifact`][artifact] stanza to download an input template
+before passing it to the template engine:
+
+```hcl
+artifact {
+  source      = "https://example.com/file.yml.tpl"
+  destination = "local/file.yml.tpl"
+}
+
+template {
+  source      = "local/file.yml.tpl"
+  destination = "local/file.yml"
+}
+```
+
+[ct]: https://github.com/hashicorp/consul-template "Consul Template by HashiCorp"
+[artifact]: /docs/job-specification/artifact.html "Nomad artifact Job Specification"

website/source/layouts/docs.erb

@@ -81,6 +81,9 @@
             <li<%= sidebar_current("docs-job-specification-task")%>>
               <a href="/docs/job-specification/task.html">task</a>
             </li>
+            <li<%= sidebar_current("docs-job-specification-template")%>>
+              <a href="/docs/job-specification/template.html">template</a>
+            </li>
             <li<%= sidebar_current("docs-job-specification-update")%>>
               <a href="/docs/job-specification/update.html">update</a>
             </li>