2016-10-31 04:05:05 +00:00
|
|
|
---
|
|
|
|
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
|
2017-01-24 17:12:42 +00:00
|
|
|
environment variables, Consul data, Vault secrets, or just general
|
|
|
|
configurations within a Nomad task.
|
2016-10-31 04:05:05 +00:00
|
|
|
---
|
|
|
|
|
|
|
|
# `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
|
2017-01-24 17:12:42 +00:00
|
|
|
environment variables, Consul data, Vault secrets, or just general
|
|
|
|
configurations within a Nomad task.
|
2016-10-31 04:05:05 +00:00
|
|
|
|
|
|
|
```hcl
|
|
|
|
job "docs" {
|
|
|
|
group "example" {
|
|
|
|
task "server" {
|
|
|
|
template {
|
|
|
|
source = "local/redis.conf.tpl"
|
|
|
|
destination = "local/redis.conf"
|
|
|
|
change_mode = "signal"
|
2017-03-14 09:12:48 +00:00
|
|
|
change_signal = "SIGINT"
|
2016-10-31 04:05:05 +00:00
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|
|
|
|
```
|
|
|
|
|
2017-01-24 01:02:13 +00:00
|
|
|
Nomad utilizes a tool called [Consul Template][ct]. Since Nomad v0.5.3, the
|
2017-03-27 21:58:04 +00:00
|
|
|
template can reference [Nomad's runtime environment variables][env]. Since Nomad
|
|
|
|
v0.5.6, the template can reference [Node attributes and metadata][nodevars]. For
|
|
|
|
a full list of the API template functions, please refer to the [Consul Template
|
2017-05-24 00:24:21 +00:00
|
|
|
README][ct]. Since Nomad v0.6.0, templates can be read as environment variables.
|
2016-10-31 04:05:05 +00:00
|
|
|
|
|
|
|
## `template` Parameters
|
|
|
|
|
2017-02-01 04:00:33 +00:00
|
|
|
- `change_mode` `(string: "restart")` - Specifies the behavior Nomad should take
|
2017-05-03 19:40:27 +00:00
|
|
|
if the rendered template changes. Nomad will always write the new contents of
|
|
|
|
the template to the specified destination. The possible values below describe
|
|
|
|
Nomad's action after writing the template to disk.
|
2017-02-01 04:00:33 +00:00
|
|
|
|
|
|
|
- `"noop"` - take no action (continue running the task)
|
|
|
|
- `"restart"` - restart the task
|
|
|
|
- `"signal"` - send a configurable signal to the task
|
|
|
|
|
2017-01-26 05:16:18 +00:00
|
|
|
- `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`.
|
2016-10-31 04:05:05 +00:00
|
|
|
|
|
|
|
- `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.
|
|
|
|
|
2017-01-26 05:16:18 +00:00
|
|
|
- `destination` `(string: <required>)` - Specifies the location where the
|
|
|
|
resulting template should be rendered, relative to the task directory.
|
|
|
|
|
2017-05-24 00:24:21 +00:00
|
|
|
- `env` `(bool: false)` - Specifies the template should be read back in as
|
2019-02-21 17:47:18 +00:00
|
|
|
environment variables for the task. ([See below](#environment-variables))
|
2017-05-24 00:24:21 +00:00
|
|
|
|
|
|
|
- `left_delimiter` `(string: "{{")` - Specifies the left delimiter to use in the
|
2017-02-21 00:43:28 +00:00
|
|
|
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.
|
|
|
|
|
2017-05-24 16:54:22 +00:00
|
|
|
- `perms` `(string: "644")` - Specifies the rendered template's permissions.
|
2019-02-21 17:47:18 +00:00
|
|
|
File permissions are given as octal of the Unix file permissions `rwxrwxrwx`.
|
2016-10-31 04:05:05 +00:00
|
|
|
|
2017-05-24 00:24:21 +00:00
|
|
|
- `right_delimiter` `(string: "}}")` - Specifies the right delimiter to use in the
|
2017-02-21 00:43:28 +00:00
|
|
|
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.
|
|
|
|
|
2017-01-26 05:16:18 +00:00
|
|
|
- `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. This template
|
|
|
|
must exist on the machine prior to starting the task; it is not possible to
|
|
|
|
reference a template inside of a Docker container, for example.
|
2016-10-31 04:05:05 +00:00
|
|
|
|
|
|
|
- `splay` `(string: "5s")` - Specifies a random amount of time to wait between
|
2017-07-17 18:41:50 +00:00
|
|
|
0 ms and the given splay value before invoking the change mode. This is
|
2016-10-31 04:05:05 +00:00
|
|
|
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.
|
|
|
|
|
2017-10-13 17:15:44 +00:00
|
|
|
- `vault_grace` `(string: "15s")` - Specifies the grace period between lease
|
2017-10-12 00:48:18 +00:00
|
|
|
renewal and secret re-acquisition. When renewing a secret, if the remaining
|
|
|
|
lease is less than or equal to the configured grace, the template will request
|
|
|
|
a new credential. This prevents Vault from revoking the secret at its
|
|
|
|
expiration and the task having a stale secret.
|
2018-07-04 00:56:22 +00:00
|
|
|
|
2017-10-12 00:48:18 +00:00
|
|
|
If the grace is set to a value that is higher than your default TTL or max
|
|
|
|
TTL, the template will always read a new secret. **If secrets are being
|
2017-11-13 17:59:20 +00:00
|
|
|
renewed constantly, decrease the `vault_grace`.**
|
2018-07-04 00:56:22 +00:00
|
|
|
|
2017-10-12 00:48:18 +00:00
|
|
|
If the task defines several templates, the `vault_grace` will be set to the
|
|
|
|
lowest value across all the templates.
|
|
|
|
|
2017-08-01 21:14:08 +00:00
|
|
|
|
2016-10-31 04:05:05 +00:00
|
|
|
## `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
|
|
|
|
|
2016-10-31 20:51:06 +00:00
|
|
|
This example uses an inline template to render a file to disk. This file watches
|
|
|
|
various keys in Consul for changes:
|
2016-10-31 04:05:05 +00:00
|
|
|
|
|
|
|
```hcl
|
|
|
|
template {
|
|
|
|
data = "---\nkey: {{ key \"service/my-key\" }}"
|
|
|
|
destination = "local/file.yml"
|
|
|
|
}
|
|
|
|
```
|
|
|
|
|
2016-10-31 20:51:06 +00:00
|
|
|
It is also possible to use heredocs for multi-line templates, like:
|
|
|
|
|
|
|
|
```hcl
|
|
|
|
template {
|
|
|
|
data = <<EOH
|
|
|
|
---
|
2017-01-24 01:02:13 +00:00
|
|
|
bind_port: {{ env "NOMAD_PORT_db" }}
|
|
|
|
scratch_dir: {{ env "NOMAD_TASK_DIR" }}
|
2017-07-25 23:53:10 +00:00
|
|
|
node_id: {{ env "node.unique.id" }}
|
2017-01-23 23:50:38 +00:00
|
|
|
service_key: {{ key "service/my-key" }}
|
2016-10-31 20:51:06 +00:00
|
|
|
EOH
|
|
|
|
|
|
|
|
destination = "local/file.yml"
|
|
|
|
}
|
|
|
|
```
|
|
|
|
|
2016-10-31 04:05:05 +00:00
|
|
|
### 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"
|
|
|
|
}
|
|
|
|
```
|
|
|
|
|
2017-03-27 21:58:04 +00:00
|
|
|
### Node Variables
|
|
|
|
|
|
|
|
As of Nomad v0.5.6 it is possible to access the Node's attributes and metadata.
|
|
|
|
|
|
|
|
```hcl
|
|
|
|
template {
|
|
|
|
data = <<EOH
|
|
|
|
---
|
|
|
|
node_dc: {{ env "node.datacenter" }}
|
|
|
|
node_cores: {{ env "attr.cpu.numcores" }}
|
|
|
|
meta_key: {{ env "meta.node_meta_key" }}
|
|
|
|
EOH
|
|
|
|
|
|
|
|
destination = "local/file.yml"
|
|
|
|
}
|
|
|
|
```
|
|
|
|
|
2017-05-24 00:24:21 +00:00
|
|
|
### Environment Variables
|
|
|
|
|
|
|
|
Since v0.6.0 templates may be used to create environment variables for tasks.
|
2019-02-21 17:47:18 +00:00
|
|
|
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.
|
2017-05-24 00:24:21 +00:00
|
|
|
|
|
|
|
For example the following template stanza:
|
|
|
|
|
|
|
|
```hcl
|
|
|
|
template {
|
|
|
|
data = <<EOH
|
|
|
|
# Lines starting with a # are ignored
|
|
|
|
|
|
|
|
# Empty lines are also ignored
|
2017-07-24 23:40:39 +00:00
|
|
|
LOG_LEVEL="{{key "service/geo-api/log-verbosity"}}"
|
2017-12-13 10:40:22 +00:00
|
|
|
API_KEY="{{with secret "secret/geo-api-key"}}{{.Data.value}}{{end}}"
|
2017-05-24 00:24:21 +00:00
|
|
|
EOH
|
|
|
|
|
2017-07-25 16:51:11 +00:00
|
|
|
destination = "secrets/file.env"
|
2017-05-24 00:24:21 +00:00
|
|
|
env = true
|
|
|
|
}
|
|
|
|
```
|
|
|
|
|
2017-05-24 20:55:21 +00:00
|
|
|
The task's environment would then have environment variables like the
|
|
|
|
following:
|
2017-05-24 00:24:21 +00:00
|
|
|
|
|
|
|
```
|
2017-07-24 23:40:39 +00:00
|
|
|
LOG_LEVEL=DEBUG
|
|
|
|
API_KEY=12345678-1234-1234-1234-1234-123456789abc
|
2017-05-24 00:24:21 +00:00
|
|
|
```
|
|
|
|
|
|
|
|
This allows [12factor app](https://12factor.net/config) style environment
|
|
|
|
variable based configuration while keeping all of the familiar features and
|
2017-05-24 20:55:21 +00:00
|
|
|
semantics of Nomad templates.
|
2017-05-24 00:24:21 +00:00
|
|
|
|
2019-02-21 17:47:18 +00:00
|
|
|
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:
|
2017-06-02 22:08:08 +00:00
|
|
|
|
|
|
|
```
|
|
|
|
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.
|
|
|
|
|
2019-02-21 17:47:18 +00:00
|
|
|
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 }}
|
|
|
|
```
|
|
|
|
|
2017-06-02 22:08:08 +00:00
|
|
|
For more details see [go-envparser's
|
2018-03-08 18:59:56 +00:00
|
|
|
README](https://github.com/hashicorp/go-envparse#readme).
|
2017-05-24 00:24:21 +00:00
|
|
|
|
2018-02-26 20:41:39 +00:00
|
|
|
## Vault Integration
|
|
|
|
|
2018-07-04 00:56:22 +00:00
|
|
|
### PKI Certificate
|
|
|
|
|
2018-03-05 18:11:35 +00:00
|
|
|
This example acquires a PKI certificate from Vault in PEM format and stores it into your application's secret directory.
|
2018-02-26 20:41:39 +00:00
|
|
|
|
2018-03-08 18:59:56 +00:00
|
|
|
```hcl
|
2018-02-26 20:41:39 +00:00
|
|
|
template {
|
|
|
|
data = <<EOH
|
|
|
|
{{ with secret "pki/issue/foo" "common_name=foo.service.consul" "ip_sans=127.0.0.1" "format=pem" }}
|
|
|
|
{{ .Data.certificate }}
|
|
|
|
{{ .Data.issuing_ca }}
|
|
|
|
{{ .Data.private_key }}{{ end }}
|
|
|
|
EOH
|
2018-03-08 18:59:56 +00:00
|
|
|
destination = "${NOMAD_SECRETS_DIR}/bundle.pem"
|
2018-02-26 20:41:39 +00:00
|
|
|
change_mode = "restart"
|
|
|
|
}
|
|
|
|
```
|
|
|
|
|
2018-10-17 22:14:40 +00:00
|
|
|
Most users should set `generate_lease=true` on the `pki/issue/foo` role in Vault's
|
|
|
|
PKI backend. If this value is not set, the template stanza will frequently render a new
|
|
|
|
certificate, approximately every minute, which is probably not what you want.
|
2018-10-15 10:21:13 +00:00
|
|
|
|
2018-07-04 00:56:22 +00:00
|
|
|
### Vault KV API v1
|
|
|
|
|
|
|
|
Under Vault KV API v1, paths start with `secret/`, and the response returns the
|
|
|
|
raw key/value data. This secret was set using
|
|
|
|
`vault kv put secret/aws/s3 aws_access_key_id=somekeyid`.
|
|
|
|
|
|
|
|
```hcl
|
|
|
|
template {
|
|
|
|
data = <<EOF
|
|
|
|
AWS_ACCESS_KEY_ID = "{{with secret "secret/aws/s3"}}{{.Data.aws_access_key_id}}{{end}}"
|
|
|
|
EOF
|
|
|
|
}
|
|
|
|
```
|
|
|
|
|
|
|
|
### Vault KV API v2
|
|
|
|
|
|
|
|
Under Vault KV API v2, paths start with `secret/data/`, and the response returns
|
|
|
|
metadata in addition to key/value data. This secret was set using
|
|
|
|
`vault kv put secret/aws/s3 aws_access_key_id=somekeyid`.
|
|
|
|
|
|
|
|
```hcl
|
|
|
|
template {
|
|
|
|
data = <<EOF
|
|
|
|
AWS_ACCESS_KEY_ID = "{{with secret "secret/data/aws/s3"}}{{.Data.data.aws_access_key_id}}{{end}}"
|
|
|
|
EOF
|
|
|
|
}
|
|
|
|
```
|
|
|
|
|
|
|
|
Notice the addition of `data` in both the path and the field accessor string.
|
|
|
|
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/...`.
|
|
|
|
|
2017-03-27 21:58:04 +00:00
|
|
|
## Client Configuration
|
2016-11-02 20:03:54 +00:00
|
|
|
|
|
|
|
The `template` block has the following [client configuration
|
2018-06-22 20:50:42 +00:00
|
|
|
options](/docs/configuration/client.html#options):
|
2016-11-02 20:03:54 +00:00
|
|
|
|
|
|
|
* `template.allow_host_source` - Allows templates to specify their source
|
|
|
|
template as an absolute path referencing host directories. Defaults to `true`.
|
|
|
|
|
2016-10-31 04:05:05 +00:00
|
|
|
[ct]: https://github.com/hashicorp/consul-template "Consul Template by HashiCorp"
|
|
|
|
[artifact]: /docs/job-specification/artifact.html "Nomad artifact Job Specification"
|
2017-01-23 23:54:56 +00:00
|
|
|
[env]: /docs/runtime/environment.html "Nomad Runtime Environment"
|
2017-03-27 21:58:04 +00:00
|
|
|
[nodevars]: /docs/runtime/interpolation.html#interpreted_node_vars "Nomad Node Variables"
|