github.com/maier/nomad@v0.4.1-0.20161110003312-a9e3d0b8549d/website/source/docs/job-specification/template.html.md (about)

     1  ---
     2  layout: "docs"
     3  page_title: "template Stanza - Job Specification"
     4  sidebar_current: "docs-job-specification-template"
     5  description: |-
     6    The "template" block instantiates an instance of a template renderer. This
     7    creates a convenient way to ship configuration files that are populated from
     8    Consul data, Vault secrets, or just general configurations within a Nomad
     9    task.
    10  ---
    11  
    12  # `template` Stanza
    13  
    14  <table class="table table-bordered table-striped">
    15    <tr>
    16      <th width="120">Placement</th>
    17      <td>
    18        <code>job -> group -> task -> **template**</code>
    19      </td>
    20    </tr>
    21  </table>
    22  
    23  The `template` block instantiates an instance of a template renderer. This
    24  creates a convenient way to ship configuration files that are populated from
    25  Consul data, Vault secrets, or just general configurations within a Nomad task.
    26  
    27  ```hcl
    28  job "docs" {
    29    group "example" {
    30      task "server" {
    31        template {
    32          source        = "local/redis.conf.tpl"
    33          destination   = "local/redis.conf"
    34          change_mode   = "signal"
    35          change_signal = "SIGNINT"
    36        }
    37      }
    38    }
    39  }
    40  ```
    41  
    42  Nomad utilizes a tool called [Consul Template][ct]. For a full list of the
    43  API template functions, please refer to the [Consul Template README][ct].
    44  
    45  ## `template` Parameters
    46  
    47  - `source` `(string: "")` - Specifies the path to the template to be rendered.
    48    One of `source` or `data` must be specified, but not both. This source can
    49    optionally be fetched using an [`artifact`][artifact] resource. This template
    50    must exist on the machine prior to starting the task; it is not possible to
    51    reference a template inside of a Docker container, for example.
    52  
    53  - `destination` `(string: <required>)` - Specifies the location where the
    54    resulting template should be rendered, relative to the task directory.
    55  
    56  - `data` `(string: "")` - Specifies the raw template to execute. One of `source`
    57    or `data` must be specified, but not both. This is useful for smaller
    58    templates, but we recommend using `source` for larger templates.
    59  
    60  - `change_mode` `(string: "restart")` - Specifies the behavior Nomad should take
    61    if the Vault token changes. The possible values are:
    62  
    63    - `"noop"` - take no action (continue running the task)
    64    - `"restart"` - restart the task
    65    - `"signal"` - send a configurable signal to the task
    66  
    67  - `change_signal` `(string: "")` - Specifies the signal to send to the task as a
    68    string like `"SIGUSR1"` or `"SIGINT"`. This option is required if the
    69    `change_mode` is `signal`.
    70  
    71  - `splay` `(string: "5s")` - Specifies a random amount of time to wait between
    72    0ms and the given splay value before invoking the change mode. This is
    73    specified using a label suffix like "30s" or "1h", and is often used to
    74    prevent a thundering herd problem where all task instances restart at the same
    75    time.
    76  
    77  ## `template` Examples
    78  
    79  The following examples only show the `template` stanzas. Remember that the
    80  `template` stanza is only valid in the placements listed above.
    81  
    82  ### Inline Template
    83  
    84  This example uses an inline template to render a file to disk. This file watches
    85  various keys in Consul for changes:
    86  
    87  ```hcl
    88  template {
    89    data        = "---\nkey: {{ key \"service/my-key\" }}"
    90    destination = "local/file.yml"
    91  }
    92  ```
    93  
    94  It is also possible to use heredocs for multi-line templates, like:
    95  
    96  ```hcl
    97  template {
    98    data = <<EOH
    99    ---
   100      key: {{ key "service/my-key" }}
   101    EOH
   102  
   103    destination = "local/file.yml"
   104  }
   105  ```
   106  
   107  ### Remote Template
   108  
   109  This example uses an [`artifact`][artifact] stanza to download an input template
   110  before passing it to the template engine:
   111  
   112  ```hcl
   113  artifact {
   114    source      = "https://example.com/file.yml.tpl"
   115    destination = "local/file.yml.tpl"
   116  }
   117  
   118  template {
   119    source      = "local/file.yml.tpl"
   120    destination = "local/file.yml"
   121  }
   122  ```
   123  
   124  ### Client Configuration
   125  
   126  The `template` block has the following [client configuration
   127  options](/docs/agent/config.html#options):
   128  
   129  * `template.allow_host_source` - Allows templates to specify their source
   130    template as an absolute path referencing host directories. Defaults to `true`.
   131  
   132  [ct]: https://github.com/hashicorp/consul-template "Consul Template by HashiCorp"
   133  [artifact]: /docs/job-specification/artifact.html "Nomad artifact Job Specification"