github.com/taylorchu/nomad@v0.5.3-rc1.0.20170407200202-db11e7dd7b55/website/source/docs/http/json-jobs.html.md (about)

     1  ---
     2  layout: "http"
     3  page_title: "HTTP API: JSON Job Specification"
     4  sidebar_current: "docs-http-json-jobs"
     5  description: |-
     6    Jobs can also be specified via the HTTP API using a JSON format. This guide
     7    discusses the job specification in JSON format.
     8  ---
     9  
    10  # Job Specification
    11  
    12  This guide covers the JSON syntax for submitting jobs to Nomad. A useful command
    13  for generating valid JSON versions of HCL jobs is
    14  `nomad run -output <job.nomad>` which will emit a JSON version of the job.
    15  
    16  ## JSON Syntax
    17  
    18  Below is an example of a JSON object that submits a `periodic` job to Nomad:
    19  
    20  ```json
    21  {
    22    "Job":{
    23      "Region":"global",
    24      "ID":"example",
    25      "Name":"example",
    26      "Type":"batch",
    27      "Priority":50,
    28      "AllAtOnce":false,
    29      "Datacenters":[
    30        "dc1"
    31      ],
    32      "Constraints":[
    33        {
    34          "LTarget":"${attr.kernel.name}",
    35          "RTarget":"linux",
    36          "Operand":"="
    37        }
    38      ],
    39      "TaskGroups":[
    40        {
    41          "Name":"cache",
    42          "Count":1,
    43          "Constraints":null,
    44          "Tasks":[
    45            {
    46              "Name":"redis",
    47              "Driver":"docker",
    48              "User":"foo-user",
    49              "Config":{
    50                "image":"redis:latest",
    51                "port_map":[
    52                  {
    53                    "db":6379
    54                  }
    55                ]
    56              },
    57              "Constraints":null,
    58              "Env":{
    59                "foo":"bar",
    60                "baz":"pipe"
    61              },
    62              "Services":[
    63                {
    64                  "Name":"cache-redis",
    65                  "Tags":[
    66                    "global",
    67                    "cache"
    68                  ],
    69                  "PortLabel":"db",
    70                  "Checks":[
    71                    {
    72                      "Id":"",
    73                      "Name":"alive",
    74                      "Type":"tcp",
    75                      "Command":"",
    76                      "Args":null,
    77                      "Path":"",
    78                      "Protocol":"",
    79                      "Interval":10000000000,
    80                      "Timeout":2000000000
    81                    }
    82                  ]
    83                }
    84              ],
    85              "Vault": {
    86                "Policies": ["policy-name"],
    87                "Env": true,
    88                "ChangeMode": "restart",
    89                "ChangeSignal": ""
    90              },
    91              "Resources":{
    92                "CPU":500,
    93                "MemoryMB":256,
    94                "IOPS":0,
    95                "Networks":[
    96                  {
    97                    "ReservedPorts":[
    98                      {
    99                        "Label":"rpc",
   100                        "Value":25566
   101                      }
   102                    ],
   103                    "DynamicPorts":[
   104                      {
   105                        "Label":"db"
   106                      }
   107                    ],
   108                    "MBits":10
   109                  }
   110                ]
   111              },
   112              "Meta":{
   113                "foo":"bar",
   114                "baz":"pipe"
   115              },
   116              "KillTimeout":5000000000,
   117              "LogConfig":{
   118                "MaxFiles":10,
   119                "MaxFileSizeMB":10
   120              },
   121              "Templates":[
   122                {
   123                  "SourcePath": "local/config.conf.tpl",
   124                  "DestPath": "local/config.conf",
   125                  "EmbeddedTmpl": "",
   126                  "ChangeMode": "signal",
   127                  "ChangeSignal": "SIGUSR1",
   128                  "Splay": 5000000000
   129                }
   130              ],
   131              "Artifacts":[
   132                {
   133                  "GetterSource":"http://foo.com/artifact.tar.gz",
   134                  "GetterOptions":{
   135                    "checksum":"md5:c4aa853ad2215426eb7d70a21922e794"
   136                  },
   137                  "RelativeDest":"local/"
   138                }
   139              ],
   140              "DispatchPayload": {
   141                "File": "config.json"
   142              }
   143            }
   144          ],
   145          "RestartPolicy":{
   146            "Interval":300000000000,
   147            "Attempts":10,
   148            "Delay":25000000000,
   149            "Mode":"delay"
   150          },
   151          "Meta":{
   152            "foo":"bar",
   153            "baz":"pipe"
   154          }
   155        }
   156      ],
   157      "Update":{
   158        "Stagger":10000000000,
   159        "MaxParallel":1
   160      },
   161      "Periodic":{
   162        "Enabled":true,
   163        "Spec":"* * * * *",
   164        "SpecType":"cron",
   165        "ProhibitOverlap":true
   166      },
   167      "Meta":{
   168        "foo":"bar",
   169        "baz":"pipe"
   170      },
   171      "ParameterizedJob": {
   172        "Payload": "required",
   173        "MetaRequired": [
   174          "foo"
   175        ],
   176        "MetaOptional": [
   177          "bar"
   178         ]
   179      },
   180      "Payload": null
   181    }
   182  }
   183  ```
   184  
   185  ## Syntax Reference
   186  
   187  Following is a syntax reference for the possible keys that are supported
   188  and their default values if any for each type of object.
   189  
   190  ### Job
   191  
   192  The `Job` object supports the following keys:
   193  
   194  * `AllAtOnce` - Controls if the entire set of tasks in the job must
   195    be placed atomically or if they can be scheduled incrementally.
   196    This should only be used for special circumstances. Defaults to `false`.
   197  
   198  * `Constraints` - A list to define additional constraints where a job can be
   199    run. See the constraint reference for more details.
   200  
   201  * `Datacenters` - A list of datacenters in the region which are eligible
   202    for task placement. This must be provided, and does not have a default.
   203  
   204  * `TaskGroups` - A list to define additional task groups. See the task group
   205    reference for more details.
   206  
   207  * `Meta` - Annotates the job with opaque metadata.
   208  
   209  * `ParameterizedJob` - Specifies the job as a paramterized job such that it can
   210    be dispatched against. The `ParamaterizedJob` object supports the following
   211    attributes:
   212  
   213    * `MetaOptional` - Specifies the set of metadata keys that may be provided
   214      when dispatching against the job as a string array.
   215  
   216    * `MetaRequired` - Specifies the set of metadata keys that must be provided
   217      when dispatching against the job as a string array.
   218  
   219    * `Payload` - Specifies the requirement of providing a payload when
   220      dispatching against the parameterized job. The options for this field are
   221      "optional", "required" and "forbidden". The default value is "optional".
   222  
   223  * `Payload` - The payload may not be set when submitting a job but may appear in
   224    a dispatched job. The `Payload` will be a base64 encoded string containing the
   225    payload that the job was dispatched with. The `payload` has a **maximum size
   226    of 16 KiB**.
   227  
   228  * `Priority` - Specifies the job priority which is used to prioritize
   229    scheduling and access to resources. Must be between 1 and 100 inclusively,
   230    and defaults to 50.
   231  
   232  * `Region` - The region to run the job in, defaults to "global".
   233  
   234  * `Type` - Specifies the job type and switches which scheduler
   235    is used. Nomad provides the `service`, `system` and `batch` schedulers,
   236    and defaults to `service`. To learn more about each scheduler type visit
   237    [here](/docs/runtime/schedulers.html)
   238  
   239  * `Update` - Specifies the task's update strategy. When omitted, rolling
   240    updates are disabled. The `Update` object supports the following attributes:
   241  
   242    * `MaxParallel` - `MaxParallel` is given as an integer value and specifies
   243    the number of tasks that can be updated at the same time.
   244  
   245    * `Stagger` - `Stagger` introduces a delay between sets of task updates and
   246    is given in nanoseconds.
   247  
   248      An example `Update` block:
   249  
   250      ```json
   251      {
   252        "Update": {
   253          "MaxParallel" : 3,
   254          "Stagger" : 10000000000
   255        }
   256      }
   257      ```
   258  
   259  *   `Periodic` - `Periodic` allows the job to be scheduled at fixed times, dates
   260      or intervals. The periodic expression is always evaluated in the UTC
   261      timezone to ensure consistent evaluation when Nomad Servers span multiple
   262      time zones. The `Periodic` object is optional and supports the following attributes:
   263  
   264      * `Enabled` - `Enabled` determines whether the periodic job will spawn child
   265      jobs.
   266  
   267      * `time_zone` - Specifies the time zone to evaluate the next launch interval
   268        against. This is useful when wanting to account for day light savings in
   269        various time zones. The time zone must be parsable by Golang's
   270        [LoadLocation](https://golang.org/pkg/time/#LoadLocation). The default is
   271        UTC.
   272  
   273      * `SpecType` - `SpecType` determines how Nomad is going to interpret the
   274        periodic expression. `cron` is the only supported `SpecType` currently.
   275  
   276      * `Spec` - A cron expression configuring the interval the job is launched
   277      at. Supports predefined expressions such as "@daily" and "@weekly" See
   278      [here](https://github.com/gorhill/cronexpr#implementation) for full
   279      documentation of supported cron specs and the predefined expressions.
   280  
   281      * <a id="prohibit_overlap">`ProhibitOverlap`</a> - `ProhibitOverlap` can
   282        be set to true to enforce that the periodic job doesn't spawn a new
   283        instance of the job if any of the previous jobs are still running. It is
   284        defaulted to false.
   285  
   286      An example `periodic` block:
   287  
   288      ```json
   289      {
   290        "Periodic": {
   291            "Spec": "*/15 * * * * *"
   292            "SpecType": "cron",
   293            "Enabled": true,
   294            "ProhibitOverlap": true
   295        }
   296      }
   297      ```
   298  
   299  ### Task Group
   300  
   301  `TaskGroups` is a list of `TaskGroup` objects, each supports the following
   302  attributes:
   303  
   304  * `Constraints` - This is a list of `Constraint` objects. See the constraint
   305    reference for more details.
   306  
   307  * `Count` - Specifies the number of the task groups that should
   308    be running. Must be non-negative, defaults to one.
   309  
   310  * `Meta` - A key-value map that annotates the task group with opaque metadata.
   311  
   312  * `Name` - The name of the task group. Must be specified.
   313  
   314  * `RestartPolicy` - Specifies the restart policy to be applied to tasks in this group.
   315    If omitted, a default policy for batch and non-batch jobs is used based on the
   316    job type. See the [restart policy reference](#restart_policy) for more details.
   317  
   318  * `EphemeralDisk` - Specifies the group's ephemeral disk requirements. See the
   319    [ephemeral disk reference](#ephemeral_disk) for more details.
   320  
   321  * `Tasks` - A list of `Task` object that are part of the task group.
   322  
   323  ### Task
   324  
   325  The `Task` object supports the following keys:
   326  
   327  * `Artifacts` - `Artifacts` is a list of `Artifact` objects which define
   328    artifacts to be downloaded before the task is run. See the artifacts
   329    reference for more details.
   330  
   331  * `Config` - A map of key-value configuration passed into the driver
   332    to start the task. The details of configurations are specific to
   333    each driver.
   334  
   335  * `Constraints` - This is a list of `Constraint` objects. See the constraint
   336    reference for more details.
   337  
   338  - `DispatchPayload` - Configures the task to have access to dispatch payloads.
   339    The `DispatchPayload` object supports the following attributes:
   340  
   341    * `File` - Specifies the file name to write the content of dispatch payload
   342      to. The file is written relative to the task's local directory.
   343  
   344  * `Driver` - Specifies the task driver that should be used to run the
   345    task. See the [driver documentation](/docs/drivers/index.html) for what
   346    is available. Examples include `docker`, `qemu`, `java`, and `exec`.
   347  
   348  *   `Env` - A map of key-value representing environment variables that
   349      will be passed along to the running process. Nomad variables are
   350      interpreted when set in the environment variable values. See the table of
   351      interpreted variables [here](/docs/runtime/interpolation.html).
   352  
   353      For example the below environment map will be reinterpreted:
   354  
   355      ```json
   356      {
   357        "Env": {
   358          "NODE_CLASS" : "${nomad.class}"
   359        }
   360      }
   361      ```
   362  
   363  * `KillTimeout` - `KillTimeout` is a time duration in nanoseconds. It can be
   364    used to configure the time between signaling a task it will be killed and
   365    actually killing it. Drivers first sends a task the `SIGINT` signal and then
   366    sends `SIGTERM` if the task doesn't die after the `KillTimeout` duration has
   367    elapsed. The default `KillTimeout` is 5 seconds.
   368  
   369  * `leader` - Specifies whether the task is the leader task of the task group. If
   370    set to true, when the leader task completes, all other tasks within the task
   371    group will be gracefully shutdown.
   372  
   373  * `LogConfig` - This allows configuring log rotation for the `stdout` and `stderr`
   374    buffers of a Task. See the log rotation reference below for more details.
   375  
   376  * `Meta` - Annotates the task group with opaque metadata.
   377  
   378  * `Name` - The name of the task. This field is required.
   379  
   380  * `Resources` - Provides the resource requirements of the task.
   381    See the resources reference for more details.
   382  
   383  * `Services` - `Services` is a list of `Service` objects. Nomad integrates with
   384    Consul for service discovery. A `Service` object represents a routable and
   385    discoverable service on the network. Nomad automatically registers when a task
   386    is started and de-registers it when the task transitions to the dead state.
   387    [Click here](/docs/service-discovery/index.html) to learn more about
   388    services. Below is the fields in the `Service` object:
   389  
   390       * `Name`: An explicit name for the Service. Nomad will replace `${JOB}`,
   391         `${TASKGROUP}` and `${TASK}` by the name of the job, task group or task,
   392         respectively. `${BASE}` expands to the equivalent of
   393         `${JOB}-${TASKGROUP}-${TASK}`, and is the default name for a Service.
   394         Each service defined for a given task must have a distinct name, so if
   395         a task has multiple services only one of them can use the default name
   396         and the others must be explicitly named. Names must adhere to
   397         [RFC-1123 ยง2.1](https://tools.ietf.org/html/rfc1123#section-2) and are
   398         limited to alphanumeric and hyphen characters (i.e. `[a-z0-9\-]`), and be
   399         less than 64 characters in length.
   400  
   401       * `Tags`: A list of string tags associated with this Service. String
   402         interpolation is supported in tags.
   403  
   404       * `PortLabel`: `PortLabel` is an optional string and is used to associate
   405         a port with the service.  If specified, the port label must match one
   406         defined in the resources block.  This could be a label of either a
   407         dynamic or a static port.
   408  
   409       * `Checks`: `Checks` is an array of check objects. A check object defines a
   410         health check associated with the service. Nomad supports the `script`,
   411         `http` and `tcp` Consul Checks. Script checks are not supported for the
   412         qemu driver since the Nomad client doesn't have access to the file system
   413         of a task using the Qemu driver.
   414  
   415           * `Type`:  This indicates the check types supported by Nomad. Valid
   416             options are currently `script`, `http` and `tcp`.
   417  
   418           * `Name`: The name of the health check.
   419  
   420           * `Interval`: This indicates the frequency of the health checks that
   421             Consul will perform.
   422  
   423           * `Timeout`: This indicates how long Consul will wait for a health
   424             check query to succeed.
   425  
   426           * `Path`:The path of the http endpoint which Consul will query to query
   427             the health of a service if the type of the check is `http`. Nomad
   428             will add the IP of the service and the port, users are only required
   429             to add the relative URL of the health check endpoint.
   430  
   431           * `Protocol`: This indicates the protocol for the http checks. Valid
   432             options are `http` and `https`. We default it to `http`.
   433  
   434           * `Command`: This is the command that the Nomad client runs for doing
   435             script based health check.
   436  
   437           * `Args`: Additional arguments to the `command` for script based health
   438             checks.
   439  
   440  * `Templates` - Specifies the set of [`Template`](#template) objects to render for the task.
   441    Templates can be used to inject both static and dynamic configuration with
   442    data populated from environment variables, Consul and Vault.
   443  
   444  * `User` - Set the user that will run the task. It defaults to the same user
   445    the Nomad client is being run as. This can only be set on Linux platforms.
   446  
   447  ### Resources
   448  
   449  The `Resources` object supports the following keys:
   450  
   451  * `CPU` - The CPU required in MHz.
   452  
   453  * `IOPS` - The number of IOPS required given as a weight between 10-1000.
   454  
   455  * `MemoryMB` - The memory required in MB.
   456  
   457  * `Networks` - A list of network objects.
   458  
   459  The Network object supports the following keys:
   460  
   461  * `MBits` - The number of MBits in bandwidth required.
   462  
   463  Nomad can allocate two types of ports to a task - Dynamic and Static/Reserved
   464  ports. A network object allows the user to specify a list of `DynamicPorts` and
   465  `ReservedPorts`. Each object supports the following attributes:
   466  
   467  * `Value` - The port number for static ports. If the port is dynamic, then this
   468    attribute is ignored.
   469  * `Label` - The label to annotate a port so that it can be referred in the
   470    service discovery block or environment variables.
   471  
   472  <a id="ephemeral_disk"></a>
   473  
   474  ### Ephemeral Disk
   475  
   476  The `EphemeralDisk` object supports the following keys:
   477  
   478  * `Migrate` - Specifies that the Nomad client should make a best-effort attempt
   479    to migrate the data from a remote machine if placement cannot be made on the
   480    original node. During data migration, the task will block starting until the
   481    data migration has completed. Value is a boolean and the default is false.
   482  
   483  * `SizeMB` - Specifies the size of the ephemeral disk in MB. Default is 300.
   484  
   485  * `Sticky` - Specifies that Nomad should make a best-effort attempt to place the
   486    updated allocation on the same machine. This will move the `local/` and
   487    `alloc/data` directories to the new allocation. Value is a boolean and the
   488    default is false.
   489  
   490  <a id="restart_policy"></a>
   491  
   492  ### Restart Policy
   493  
   494  The `RestartPolicy` object supports the following keys:
   495  
   496  * `Attempts` - `Attempts` is the number of restarts allowed in an `Interval`.
   497  
   498  * `Interval` - `Interval` is a time duration that is specified in nanoseconds.
   499    The `Interval` begins when the first task starts and ensures that only
   500    `Attempts` number of restarts happens within it. If more than `Attempts`
   501    number of failures happen, behavior is controlled by `Mode`.
   502  
   503  * `Delay` - A duration to wait before restarting a task. It is specified in
   504    nanoseconds. A random jitter of up to 25% is added to the delay.
   505  
   506  *   `Mode` - `Mode` is given as a string and controls the behavior when the task
   507      fails more than `Attempts` times in an `Interval`. Possible values are listed
   508      below:
   509  
   510      * `delay` - `delay` will delay the next restart until the next `Interval` is
   511        reached.
   512  
   513      * `fail` - `fail` will not restart the task again.
   514  
   515  ### Constraint
   516  
   517  The `Constraint` object supports the following keys:
   518  
   519  * `LTarget` - Specifies the attribute to examine for the
   520    constraint. See the table of attributes [here](/docs/runtime/interpolation.html#interpreted_node_vars).
   521  
   522  * `RTarget` - Specifies the value to compare the attribute against.
   523    This can be a literal value, another attribute or a regular expression if
   524    the `Operator` is in "regexp" mode.
   525  
   526  * `Operand` - Specifies the test to be performed on the two targets. It takes on the
   527    following values:
   528  
   529    * `regexp` - Allows the `RTarget` to be a regular expression to be matched.
   530  
   531    * `set_contains` - Allows the `RTarget` to be a comma separated list of values
   532      that should be contained in the LTarget's value.
   533  
   534    * `distinct_host` - If set, the scheduler will not co-locate any task groups on the same
   535          machine. This can be specified as a job constraint which applies the
   536          constraint to all task groups in the job, or as a task group constraint which
   537          scopes the effect to just that group. The constraint may not be
   538          specified at the task level.
   539  
   540          Placing the constraint at both the job level and at the task group level is
   541          redundant since when placed at the job level, the constraint will be applied
   542          to all task groups. When specified, `LTarget` and `RTarget` should be
   543          omitted.
   544  
   545    * `distinct_property` - If set, the scheduler selects nodes that have a
   546          distinct value of the specified property for each allocation. This can
   547          be specified as a job constraint which applies the constraint to all
   548          task groups in the job, or as a task group constraint which scopes the
   549          effect to just that group. The constraint may not be specified at the
   550          task level.
   551  
   552          Placing the constraint at both the job level and at the task group level is
   553          redundant since when placed at the job level, the constraint will be applied
   554          to all task groups. When specified, `LTarget` should be the property
   555          that should be distinct and and `RTarget` should be omitted.
   556  
   557    * Comparison Operators - `=`, `==`, `is`, `!=`, `not`, `>`, `>=`, `<`, `<=`. The
   558      ordering is compared lexically.
   559  
   560  ### Log Rotation
   561  
   562  The `LogConfig` object configures the log rotation policy for a task's `stdout` and
   563  `stderr`. The `LogConfig` object supports the following attributes:
   564  
   565  * `MaxFiles` - The maximum number of rotated files Nomad will retain for
   566    `stdout` and `stderr`, each tracked individually.
   567  
   568  * `MaxFileSizeMB` - The size of each rotated file. The size is specified in
   569    `MB`.
   570  
   571  If the amount of disk resource requested for the task is less than the total
   572  amount of disk space needed to retain the rotated set of files, Nomad will return
   573  a validation error when a job is submitted.
   574  
   575  ```json
   576  {
   577    "LogConfig": {
   578      "MaxFiles": 3,
   579      "MaxFileSizeMB": 10
   580    }
   581  }
   582  ```
   583  
   584  In the above example we have asked Nomad to retain 3 rotated files for both
   585  `stderr` and `stdout` and size of each file is 10MB. The minimum disk space that
   586  would be required for the task would be 60MB.
   587  
   588  ### Artifact
   589  
   590  Nomad downloads artifacts using
   591  [`go-getter`](https://github.com/hashicorp/go-getter). The `go-getter` library
   592  allows downloading of artifacts from various sources using a URL as the input
   593  source. The key-value pairs given in the `options` block map directly to
   594  parameters appended to the supplied `source` URL. These are then used by
   595  `go-getter` to appropriately download the artifact. `go-getter` also has a CLI
   596  tool to validate its URL and can be used to check if the Nomad `artifact` is
   597  valid.
   598  
   599  Nomad allows downloading `http`, `https`, and `S3` artifacts. If these artifacts
   600  are archives (zip, tar.gz, bz2, etc.), these will be unarchived before the task
   601  is started.
   602  
   603  The `Artifact` object supports the following keys:
   604  
   605  * `GetterSource` - The path to the artifact to download.
   606  
   607  * `RelativeDest` - An optional path to download the artifact into relative to the
   608    root of the task's directory. If omitted, it will default to `local/`.
   609  
   610  * `GetterOptions` - A `map[string]string` block of options for `go-getter`.
   611    Full documentation of supported options are available
   612    [here](https://github.com/hashicorp/go-getter/tree/ef5edd3d8f6f482b775199be2f3734fd20e04d4a#protocol-specific-options-1).
   613    An example is given below:
   614  
   615  ```json
   616  {
   617    "GetterOptions": {
   618      "checksum": "md5:c4aa853ad2215426eb7d70a21922e794",
   619  
   620      "aws_access_key_id": "<id>",
   621      "aws_access_key_secret": "<secret>",
   622      "aws_access_token": "<token>"
   623    }
   624  }
   625  ```
   626  
   627  An example of downloading and unzipping an archive is as simple as:
   628  
   629  ```json
   630  {
   631    "Artifacts": [
   632      {
   633        "GetterSource": "https://example.com/my.zip",
   634        "GetterOptions": {
   635          "checksum": "md5:7f4b3e3b4dd5150d4e5aaaa5efada4c3"
   636        }
   637      }
   638    ]
   639  }
   640  ```
   641  
   642  #### S3 examples
   643  
   644  S3 has several different types of addressing and more detail can be found
   645  [here](http://docs.aws.amazon.com/AmazonS3/latest/dev/UsingBucket.html#access-bucket-intro)
   646  
   647  S3 region specific endpoints can be found
   648  [here](http://docs.aws.amazon.com/general/latest/gr/rande.html#s3_region)
   649  
   650  Path based style:
   651  
   652  ```json
   653  {
   654    "Artifacts": [
   655      {
   656        "GetterSource": "https://s3-us-west-2.amazonaws.com/my-bucket-example/my_app.tar.gz",
   657      }
   658    ]
   659  }
   660  ```
   661  
   662  or to override automatic detection in the URL, use the S3-specific syntax
   663  
   664  ```json
   665  {
   666    "Artifacts": [
   667      {
   668        "GetterSource": "s3::https://s3-eu-west-1.amazonaws.com/my-bucket-example/my_app.tar.gz",
   669      }
   670    ]
   671  }
   672  ```
   673  
   674  Virtual hosted based style
   675  
   676  ```json
   677  {
   678    "Artifacts": [
   679      {
   680        "GetterSource": "my-bucket-example.s3-eu-west-1.amazonaws.com/my_app.tar.gz",
   681      }
   682    ]
   683  }
   684  ```
   685  
   686  ### Template
   687  
   688  The `Template` block instantiates an instance of a template renderer. This
   689  creates a convenient way to ship configuration files that are populated from
   690  environment variables, Consul data, Vault secrets, or just general
   691  configurations within a Nomad task.
   692  
   693  Nomad utilizes a tool called [Consul Template][ct]. Since Nomad v0.5.3, the
   694  template can reference [Nomad's runtime environment variables][env]. For a full
   695  list of the API template functions, please refer to the [Consul Template
   696  README][ct].
   697  
   698  
   699  `Template` object supports following attributes:
   700  
   701  - `ChangeMode` - Specifies the behavior Nomad should take if the rendered
   702    template changes. The default value is `"restart"`. The possible values are:
   703  
   704    - `"noop"` - take no action (continue running the task)
   705    - `"restart"` - restart the task
   706    - `"signal"` - send a configurable signal to the task
   707  
   708  * `ChangeSignal` - Specifies the signal to send to the task as a string like
   709    "SIGUSR1" or "SIGINT". This option is required if the `ChangeMode` is
   710    `signal`.
   711  
   712  * `DestPath` - Specifies the location where the resulting template should be
   713    rendered, relative to the task directory.
   714  
   715  * `EmbeddedTmpl` -  Specifies the raw template to execute. One of `SourcePath`
   716    or `EmbeddedTmpl` must be specified, but not both. This is useful for smaller
   717    templates, but we recommend using `SourcePath` for larger templates.
   718  
   719  * `LeftDelim` - Specifies the left delimiter to use in the template. The default
   720    is "{{" for some templates, it may be easier to use a different delimiter that
   721    does not conflict with the output file itself.
   722  
   723  * `Perms` - Specifies the rendered template's permissions. File permissions are
   724    given as octal of the unix file permissions rwxrwxrwx.
   725  
   726  * `RightDelim` - Specifies the right delimiter to use in the template. The default
   727    is "}}" for some templates, it may be easier to use a different delimiter that
   728    does not conflict with the output file itself.
   729  
   730  * `SourcePath` - Specifies the path to the template to be rendered. `SourcePath`
   731    is mutually exclusive with `EmbeddedTmpl` attribute. The source can be fetched
   732    using an [`Artifact`](#artifact) resource. The template must exist on the
   733    machine prior to starting the task; it is not possible to reference a template
   734    inside of a Docker container, for example.
   735  
   736  * `Splay` - Specifies a random amount of time to wait between 0ms and the given
   737    splay value before invoking the change mode. Should be specified in
   738    nanoseconds.
   739  
   740  
   741  ```json
   742  {
   743    "Templates": [
   744      {
   745        "SourcePath": "local/config.conf.tpl",
   746        "DestPath": "local/config.conf",
   747        "EmbeddedTmpl": "",
   748        "ChangeMode": "signal",
   749        "ChangeSignal": "SIGUSR1",
   750        "Splay": 5000000000
   751      }
   752    ]
   753  }
   754  
   755  ```
   756  
   757  [ct]: https://github.com/hashicorp/consul-template "Consul Template by HashiCorp"
   758  [env]: /docs/runtime/environment.html "Nomad Runtime Environment"