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

layout	page_title	sidebar_current	description
docs	template Stanza - Job Specification	docs-job-specification-template	The "template" block instantiates an instance of a template renderer. This creates a convenient way to ship configuration files that are populated from environment variables, Consul data, Vault secrets, or just general configurations within a Nomad task.

template Stanza

Placement	job -> group -> task -> **template**

The template block instantiates an instance of a template renderer. This creates a convenient way to ship configuration files that are populated from environment variables, Consul data, Vault secrets, or just general configurations within a Nomad task.

job "docs" {
  group "example" {
    task "server" {
      template {
        source        = "local/redis.conf.tpl"
        destination   = "local/redis.conf"
        change_mode   = "signal"
        change_signal = "SIGINT"
      }
    }
  }
}

Nomad utilizes a tool called Consul Template. Since Nomad v0.5.3, the template can reference Nomad's runtime environment variables. Since Nomad v0.5.6, the template can reference Node attributes and metadata. For a full list of the API template functions, please refer to the Consul Template README.

template Parameters

• change_mode (string: "restart") - Specifies the behavior Nomad should take if the rendered template changes. The possible values are:

  • "noop" - take no action (continue running the task)
  • "restart" - restart the task
  • "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.

• 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.

• destination (string: <required>) - Specifies the location where the resulting template should be rendered, relative to the task directory.

• 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: "666") - Specifies the rendered template's permissions. 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 different delimiter that does not conflict with the output file itself.

• 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 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.

• 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 file to disk. This file watches various keys in Consul for changes:

template {
  data        = "---\nkey: {{ key \"service/my-key\" }}"
  destination = "local/file.yml"
}

It is also possible to use heredocs for multi-line templates, like:

template {
  data = <<EOH
  ---
    bind_port:   {{ env "NOMAD_PORT_db" }}
    scratch_dir: {{ env "NOMAD_TASK_DIR" }}
    service_key: {{ key "service/my-key" }}
  EOH

  destination = "local/file.yml"
}

Remote Template

This example uses an artifact stanza to download an input template before passing it to the template engine:

artifact {
  source      = "https://example.com/file.yml.tpl"
  destination = "local/file.yml.tpl"
}

template {
  source      = "local/file.yml.tpl"
  destination = "local/file.yml"
}

Node Variables

As of Nomad v0.5.6 it is possible to access the Node's attributes and metadata.

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"
}

Client Configuration

The template block has the following client configuration options:

• template.allow_host_source - Allows templates to specify their source template as an absolute path referencing host directories. Defaults to true.