From 1392246e4e843ad58fa1c1755b8bbfee85d097b3 Mon Sep 17 00:00:00 2001
From: Tim Gross <tgross@hashicorp.com>
Date: Thu, 19 Nov 2020 15:09:54 -0500
Subject: [PATCH] docs: template behavior warnings

* vault secrets named with `-` characters cannot be read by `consul-template`
  due to limitations in golang's template rendering engine.
* environment variables are not modified in running tasks if
`change_mode.noop` is set.
---
 .../pages/docs/job-specification/template.mdx | 28 +++++++++++++++++++
 1 file changed, 28 insertions(+)

diff --git a/website/pages/docs/job-specification/template.mdx b/website/pages/docs/job-specification/template.mdx
index 7f174fdb7..d3086b75d 100644
--- a/website/pages/docs/job-specification/template.mdx
+++ b/website/pages/docs/job-specification/template.mdx
@@ -68,6 +68,10 @@ README][ct]. Since Nomad v0.6.0, templates can be read as environment variables.
 
 - `env` `(bool: false)` - Specifies the template should be read back in as
   environment variables for the task. ([See below](#environment-variables))
+  Note that if `noop` mode is used for the `change_mode`, the task will not be
+  restarted and the environment variables wwon't be changed in the task. If
+  you set `env = true`, then the `change_mode` should be one of `restart` or
+  `signal`.
 
 - `left_delimiter` `(string: "{{")` - Specifies the left delimiter to use in the
   template. The default is "{{" for some templates, it may be easier to use a
@@ -347,6 +351,18 @@ raw key/value data. This secret was set using
   }
 ```
 
+Note that if the name of a secret includes the `-` character, you must access
+it by index. This secret was set using `vault kv put secret/app
+db-password=somepassword`.
+
+```hcl
+  template {
+    data = <<EOF
+      DB_PASSWORD = "{{with secret "secret/app"}}{{index .Data "db-password"}}{{end}}"
+    EOF
+  }
+```
+
 ### Vault KV API v2
 
 Under Vault KV API v2, paths start with `secret/data/`, and the response returns
@@ -366,6 +382,18 @@ Additionally, when using the Vault v2 API, the Vault policies applied to your
 Nomad jobs will need to grant permissions to `read` under `secret/data/...`
 rather than `secret/...`.
 
+Similar to KV API v1, if the name of a secret includes the `-` character, you
+must access it by index. This secret was set using `vault kv put secret/app
+db-password=somepassword`.
+
+```hcl
+  template {
+    data = <<EOF
+      DB_PASSWORD = "{{with secret "secret/data/app"}}{{index .Data.data "db-password"}}{{end}}"
+    EOF
+  }
+```
+
 ## Client Configuration
 
 The `template` block has the following [client configuration