luxolus
/
open-nomad
2
0
Fork 0
Code Issues 1 Pull Requests Packages Releases Wiki Activity

Merge pull request #5348 from hashicorp/docs-env-json 

docs: clarify use of toJSON for passwords
This commit is contained in:
Michael Schurter 2019-02-21 14:36:28 -08:00 committed by GitHub
parent 6d30284ec9 7dd6259e93
commit 3a9730a890
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 23 additions and 6 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

29
website/source/docs/job-specification/template.html.md
View File

@ -69,14 +69,14 @@ README][ct]. Since Nomad v0.6.0, templates can be read as environment variables.
resulting template should be rendered, relative to the task directory.
- `env` `(bool: false)` - Specifies the template should be read back in as
environment variables for the task. (See below)
environment variables for the task. ([See below](#environment-variables))
- `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
different delimiter that does not conflict with the output file itself.
- `perms` `(string: "644")` - Specifies the rendered template's permissions.
File permissions are given as octal of the Unix file permissions rwxrwxrwx.
File permissions are given as octal of the Unix file permissions `rwxrwxrwx`.
- `right_delimiter` `(string: "}}")` - Specifies the right delimiter to use in the
template. The default is "}}" for some templates, it may be easier to use a
@ -178,9 +178,9 @@ template {
### Environment Variables
Since v0.6.0 templates may be used to create environment variables for tasks.
Env templates work exactly like other templates except once they're written,
they're read back in as `KEY=value` pairs. Those key value pairs are included
in the task's environment.
Env templates work exactly like other templates except once the templates are
written, they are parsed as `KEY=value` pairs. Those key value pairs are
included in the task's environment.
For example the following template stanza:
@ -211,7 +211,12 @@ This allows [12factor app](https://12factor.net/config) style environment
variable based configuration while keeping all of the familiar features and
semantics of Nomad templates.
If a value may include newlines you should JSON encode it:
Secrets or certificates may contain a wide variety of characters such as
newlines, quotes, and backslashes which may be difficult to quote or escape
properly.
Whenever a templated variable may include special characters, use the `toJSON`
function to ensure special characters are properly parsed by Nomad:
```
CERT_PEM={{ file "path/to/cert.pem" | toJSON }}
@ -220,6 +225,18 @@ CERT_PEM={{ file "path/to/cert.pem" | toJSON }}
The parser will read the JSON string, so the `$CERT_PEM` environment variable
will be identical to the contents of the file.
Likewise when evaluating a password that may contain quotes or `#`, use the
`toJSON` function to ensure Nomad passes the password to task unchanged:
```
# Passwords may contain any character including special characters like:
# \"'#
# Use toJSON to ensure Nomad passes them to the environment unchanged.
{{ with secret "secrets/data/application/backend" }}
DB_PASSWD={{ .Data.data.DB_PASSWD | toJSON }}
{{ end }}
```
For more details see [go-envparser's
README](https://github.com/hashicorp/go-envparse#readme).