2016-02-21 18:19:37 +00:00
|
|
|
---
|
2017-05-26 23:15:35 +00:00
|
|
|
layout: api
|
|
|
|
page_title: JSON Job Specification - HTTP API
|
2016-02-21 18:19:37 +00:00
|
|
|
description: |-
|
2016-10-28 03:01:11 +00:00
|
|
|
Jobs can also be specified via the HTTP API using a JSON format. This guide
|
|
|
|
discusses the job specification in JSON format.
|
2016-02-21 18:19:37 +00:00
|
|
|
---
|
|
|
|
|
2017-05-26 23:15:35 +00:00
|
|
|
# JSON Job Specification
|
2016-02-21 18:19:37 +00:00
|
|
|
|
2022-04-22 22:57:27 +00:00
|
|
|
Nomad's HTTP API uses JSON formatted job specifications except for the
|
|
|
|
[`/job/parse` API][job-parse] which exists to convert HCL to JSON.
|
|
|
|
|
|
|
|
The Nomad CLI includes a number of useful commands for working with JSON jobs.
|
|
|
|
|
|
|
|
The [`nomad job run -output`][job-output] flag converts HCL jobs to JSON
|
|
|
|
without submitting the job:
|
2016-02-21 18:19:37 +00:00
|
|
|
|
2020-05-18 20:53:06 +00:00
|
|
|
```shell-session
|
|
|
|
$ nomad job run -output my-job.nomad
|
2017-05-26 23:15:35 +00:00
|
|
|
```
|
|
|
|
|
2022-04-22 22:57:27 +00:00
|
|
|
The [`nomad job inspect`][job-inspect] command retrieves the JSON specification
|
|
|
|
for an existing job:
|
|
|
|
|
|
|
|
```shell-session
|
|
|
|
$ nomad job inspect example
|
|
|
|
```
|
|
|
|
|
|
|
|
The [`nomad job run -json`][job-run-json] flag submits a JSON formatted job:
|
|
|
|
|
|
|
|
```shell-session
|
|
|
|
$ nomad job run -json example.json
|
|
|
|
```
|
|
|
|
|
2023-01-25 17:31:14 +00:00
|
|
|
[job-inspect]: /nomad/docs/commands/job/inspect
|
|
|
|
[job-output]: /nomad/docs/commands/job/run#output
|
|
|
|
[job-parse]: /nomad/api-docs/jobs#parse-job
|
|
|
|
[job-run-json]: /nomad/docs/commands/job/run#json
|
2022-04-22 22:57:27 +00:00
|
|
|
|
2017-05-26 23:15:35 +00:00
|
|
|
## Syntax
|
2016-02-21 18:19:37 +00:00
|
|
|
|
2022-04-22 22:57:27 +00:00
|
|
|
Below is the JSON representation of the example job as well as the commands to
|
|
|
|
reproduce it:
|
|
|
|
|
|
|
|
```shell-session
|
|
|
|
$ nomad init
|
2023-02-02 17:47:47 +00:00
|
|
|
Example job file written to example.nomad.hcl
|
|
|
|
$ nomad job run -output example.nomad.hcl
|
2022-04-22 22:57:27 +00:00
|
|
|
```
|
2016-02-21 18:19:37 +00:00
|
|
|
|
2016-10-03 22:23:50 +00:00
|
|
|
```json
|
2016-02-21 18:19:37 +00:00
|
|
|
{
|
2020-02-06 23:45:31 +00:00
|
|
|
"Job": {
|
2022-04-22 22:57:27 +00:00
|
|
|
"Region": null,
|
|
|
|
"Namespace": null,
|
2020-02-06 23:45:31 +00:00
|
|
|
"ID": "example",
|
|
|
|
"Name": "example",
|
|
|
|
"Type": "service",
|
2022-04-22 22:57:27 +00:00
|
|
|
"Priority": null,
|
|
|
|
"AllAtOnce": null,
|
|
|
|
"Datacenters": [
|
|
|
|
"dc1"
|
|
|
|
],
|
|
|
|
"Constraints": null,
|
|
|
|
"Affinities": null,
|
2020-02-06 23:45:31 +00:00
|
|
|
"TaskGroups": [
|
|
|
|
{
|
|
|
|
"Name": "cache",
|
|
|
|
"Count": 1,
|
2022-04-22 22:57:27 +00:00
|
|
|
"Constraints": null,
|
|
|
|
"Affinities": null,
|
2020-02-06 23:45:31 +00:00
|
|
|
"Tasks": [
|
|
|
|
{
|
|
|
|
"Name": "redis",
|
|
|
|
"Driver": "docker",
|
|
|
|
"User": "",
|
2022-04-22 22:57:27 +00:00
|
|
|
"Lifecycle": null,
|
2020-02-06 23:45:31 +00:00
|
|
|
"Config": {
|
2023-02-02 18:59:14 +00:00
|
|
|
"auth_soft_fail": true,
|
2022-05-17 15:24:19 +00:00
|
|
|
"image": "redis:7",
|
2022-04-22 22:57:27 +00:00
|
|
|
"ports": [
|
|
|
|
"db"
|
2020-02-06 23:45:31 +00:00
|
|
|
]
|
2018-04-12 18:34:01 +00:00
|
|
|
},
|
2022-04-22 22:57:27 +00:00
|
|
|
"Constraints": null,
|
|
|
|
"Affinities": null,
|
|
|
|
"Env": null,
|
|
|
|
"Services": null,
|
2020-02-06 23:45:31 +00:00
|
|
|
"Resources": {
|
|
|
|
"CPU": 500,
|
2022-04-22 22:57:27 +00:00
|
|
|
"Cores": null,
|
2020-02-06 23:45:31 +00:00
|
|
|
"MemoryMB": 256,
|
2022-04-22 22:57:27 +00:00
|
|
|
"MemoryMaxMB": null,
|
|
|
|
"DiskMB": null,
|
|
|
|
"Networks": null,
|
|
|
|
"Devices": null,
|
|
|
|
"IOPS": null
|
2017-07-28 16:02:15 +00:00
|
|
|
},
|
2022-04-22 22:57:27 +00:00
|
|
|
"RestartPolicy": null,
|
|
|
|
"Meta": null,
|
|
|
|
"KillTimeout": null,
|
|
|
|
"LogConfig": null,
|
|
|
|
"Artifacts": null,
|
|
|
|
"Vault": null,
|
|
|
|
"Templates": null,
|
|
|
|
"DispatchPayload": null,
|
|
|
|
"VolumeMounts": null,
|
|
|
|
"Leader": false,
|
|
|
|
"ShutdownDelay": 0,
|
|
|
|
"KillSignal": "",
|
|
|
|
"Kind": "",
|
2023-02-02 18:59:14 +00:00
|
|
|
"ScalingPolicies": null,
|
|
|
|
"Identity": {
|
|
|
|
"Env": true,
|
|
|
|
"File": true
|
|
|
|
}
|
2020-02-06 23:45:31 +00:00
|
|
|
}
|
|
|
|
],
|
2022-04-22 22:57:27 +00:00
|
|
|
"Spreads": null,
|
|
|
|
"Volumes": null,
|
2020-02-06 23:45:31 +00:00
|
|
|
"RestartPolicy": {
|
|
|
|
"Interval": 1800000000000,
|
|
|
|
"Attempts": 2,
|
|
|
|
"Delay": 15000000000,
|
|
|
|
"Mode": "fail"
|
|
|
|
},
|
2022-04-22 22:57:27 +00:00
|
|
|
"ReschedulePolicy": null,
|
2020-02-06 23:45:31 +00:00
|
|
|
"EphemeralDisk": {
|
2022-04-22 22:57:27 +00:00
|
|
|
"Sticky": null,
|
|
|
|
"Migrate": null,
|
2020-02-06 23:45:31 +00:00
|
|
|
"SizeMB": 300
|
2022-04-22 22:57:27 +00:00
|
|
|
},
|
|
|
|
"Update": null,
|
|
|
|
"Migrate": null,
|
|
|
|
"Networks": [
|
|
|
|
{
|
|
|
|
"Mode": "",
|
|
|
|
"Device": "",
|
|
|
|
"CIDR": "",
|
|
|
|
"IP": "",
|
|
|
|
"DNS": null,
|
|
|
|
"ReservedPorts": null,
|
|
|
|
"DynamicPorts": [
|
|
|
|
{
|
|
|
|
"Label": "db",
|
|
|
|
"Value": 0,
|
|
|
|
"To": 6379,
|
|
|
|
"HostNetwork": ""
|
|
|
|
}
|
|
|
|
],
|
|
|
|
"Hostname": "",
|
|
|
|
"MBits": null
|
|
|
|
}
|
|
|
|
],
|
|
|
|
"Meta": null,
|
|
|
|
"Services": [
|
|
|
|
{
|
|
|
|
"Name": "redis-cache",
|
|
|
|
"Tags": [
|
|
|
|
"global",
|
|
|
|
"cache"
|
|
|
|
],
|
|
|
|
"CanaryTags": null,
|
|
|
|
"EnableTagOverride": false,
|
|
|
|
"PortLabel": "db",
|
|
|
|
"AddressMode": "",
|
2023-02-02 18:59:14 +00:00
|
|
|
"Address": "",
|
2022-04-22 22:57:27 +00:00
|
|
|
"Checks": null,
|
|
|
|
"CheckRestart": null,
|
|
|
|
"Connect": null,
|
|
|
|
"Meta": null,
|
|
|
|
"CanaryMeta": null,
|
2023-02-02 18:59:14 +00:00
|
|
|
"TaggedAddresses": null,
|
2022-04-22 22:57:27 +00:00
|
|
|
"TaskName": "",
|
|
|
|
"OnUpdate": "",
|
2023-02-02 18:59:14 +00:00
|
|
|
"Provider": "nomad"
|
2022-04-22 22:57:27 +00:00
|
|
|
}
|
|
|
|
],
|
|
|
|
"ShutdownDelay": null,
|
|
|
|
"StopAfterClientDisconnect": null,
|
|
|
|
"MaxClientDisconnect": null,
|
|
|
|
"Scaling": null,
|
|
|
|
"Consul": null
|
2020-02-06 23:45:31 +00:00
|
|
|
}
|
|
|
|
],
|
|
|
|
"Update": {
|
2022-04-22 22:57:27 +00:00
|
|
|
"Stagger": null,
|
2020-02-06 23:45:31 +00:00
|
|
|
"MaxParallel": 1,
|
2022-04-22 22:57:27 +00:00
|
|
|
"HealthCheck": null,
|
2020-02-06 23:45:31 +00:00
|
|
|
"MinHealthyTime": 10000000000,
|
|
|
|
"HealthyDeadline": 180000000000,
|
2022-04-22 22:57:27 +00:00
|
|
|
"ProgressDeadline": 600000000000,
|
|
|
|
"Canary": 0,
|
2020-02-06 23:45:31 +00:00
|
|
|
"AutoRevert": false,
|
2022-04-22 22:57:27 +00:00
|
|
|
"AutoPromote": null
|
|
|
|
},
|
|
|
|
"Multiregion": null,
|
|
|
|
"Spreads": null,
|
|
|
|
"Periodic": null,
|
|
|
|
"ParameterizedJob": null,
|
|
|
|
"Reschedule": null,
|
|
|
|
"Migrate": {
|
|
|
|
"MaxParallel": 1,
|
|
|
|
"HealthCheck": "checks",
|
|
|
|
"MinHealthyTime": 10000000000,
|
|
|
|
"HealthyDeadline": 300000000000
|
|
|
|
},
|
|
|
|
"Meta": null,
|
|
|
|
"ConsulToken": null,
|
|
|
|
"VaultToken": null,
|
|
|
|
"Stop": null,
|
|
|
|
"ParentID": null,
|
|
|
|
"Dispatched": false,
|
|
|
|
"DispatchIdempotencyToken": null,
|
|
|
|
"Payload": null,
|
|
|
|
"ConsulNamespace": null,
|
|
|
|
"VaultNamespace": null,
|
|
|
|
"NomadTokenID": null,
|
|
|
|
"Status": null,
|
|
|
|
"StatusDescription": null,
|
|
|
|
"Stable": null,
|
|
|
|
"Version": null,
|
|
|
|
"SubmitTime": null,
|
|
|
|
"CreateIndex": null,
|
|
|
|
"ModifyIndex": null,
|
|
|
|
"JobModifyIndex": null
|
2020-02-06 23:45:31 +00:00
|
|
|
}
|
2017-07-28 16:02:15 +00:00
|
|
|
}
|
|
|
|
```
|
|
|
|
|
2016-02-21 18:19:37 +00:00
|
|
|
## Syntax Reference
|
|
|
|
|
2017-05-26 23:15:35 +00:00
|
|
|
Following is a syntax reference for the possible keys that are supported and
|
|
|
|
their default values if any for each type of object.
|
2016-02-21 18:19:37 +00:00
|
|
|
|
|
|
|
### Job
|
|
|
|
|
|
|
|
The `Job` object supports the following keys:
|
|
|
|
|
2017-08-29 23:20:28 +00:00
|
|
|
- `AllAtOnce` - Controls whether the scheduler can make partial placements if
|
|
|
|
optimistic scheduling resulted in an oversubscribed node. This does not
|
|
|
|
control whether all allocations for the job, where all would be the desired
|
|
|
|
count for each task group, must be placed atomically. This should only be
|
|
|
|
used for special circumstances. Defaults to `false`.
|
2016-02-21 18:19:37 +00:00
|
|
|
|
2017-05-26 23:15:35 +00:00
|
|
|
- `Constraints` - A list to define additional constraints where a job can be
|
2016-02-21 18:19:37 +00:00
|
|
|
run. See the constraint reference for more details.
|
|
|
|
|
2018-11-05 22:41:20 +00:00
|
|
|
- `Affinities` - A list to define placement preferences on nodes where a job can be
|
|
|
|
run. See the affinity reference for more details.
|
|
|
|
|
2019-07-30 09:25:29 +00:00
|
|
|
- `Spreads` - A list to define allocation spread across attributes. See the spread reference
|
2019-01-04 03:59:23 +00:00
|
|
|
for more details.
|
|
|
|
|
2017-05-26 23:15:35 +00:00
|
|
|
- `Datacenters` - A list of datacenters in the region which are eligible
|
2016-02-21 18:19:37 +00:00
|
|
|
for task placement. This must be provided, and does not have a default.
|
|
|
|
|
2017-05-26 23:15:35 +00:00
|
|
|
- `TaskGroups` - A list to define additional task groups. See the task group
|
2016-02-21 18:19:37 +00:00
|
|
|
reference for more details.
|
|
|
|
|
2017-05-26 23:15:35 +00:00
|
|
|
- `Meta` - Annotates the job with opaque metadata.
|
2016-02-21 18:19:37 +00:00
|
|
|
|
2022-04-22 22:57:27 +00:00
|
|
|
- `ConsulToken` - Specifies the Consul token that proves the submitter of the
|
|
|
|
job has access to the Service Identity policies associated with the job's
|
|
|
|
Consul Connect enabled services. This field is only used to transfer the
|
|
|
|
token and is not stored after job submission.
|
|
|
|
|
|
|
|
- `VaultToken` - Specifies the Vault token that proves the submitter of the job
|
2023-01-30 14:48:43 +00:00
|
|
|
has access to the specified policies in the `vault` block. This field is
|
2022-04-22 22:57:27 +00:00
|
|
|
only used to transfer the token and is not stored after job submission.
|
|
|
|
|
2017-09-19 14:47:10 +00:00
|
|
|
- `Namespace` - The namespace to execute the job in, defaults to "default".
|
2020-10-22 21:59:40 +00:00
|
|
|
Prior to Nomad 1.0 namespaces were Enterprise-only.
|
2017-09-19 14:47:10 +00:00
|
|
|
|
2017-07-17 18:41:50 +00:00
|
|
|
- `ParameterizedJob` - Specifies the job as a parameterized job such that it can
|
2018-03-11 18:36:05 +00:00
|
|
|
be dispatched against. The `ParameterizedJob` object supports the following
|
2017-01-26 06:15:00 +00:00
|
|
|
attributes:
|
|
|
|
|
2017-05-26 23:15:35 +00:00
|
|
|
- `MetaOptional` - Specifies the set of metadata keys that may be provided
|
2017-01-26 06:15:00 +00:00
|
|
|
when dispatching against the job as a string array.
|
|
|
|
|
2017-05-26 23:15:35 +00:00
|
|
|
- `MetaRequired` - Specifies the set of metadata keys that must be provided
|
2017-01-26 06:15:00 +00:00
|
|
|
when dispatching against the job as a string array.
|
|
|
|
|
2017-05-26 23:15:35 +00:00
|
|
|
- `Payload` - Specifies the requirement of providing a payload when
|
2017-01-26 06:15:00 +00:00
|
|
|
dispatching against the parameterized job. The options for this field are
|
2017-01-26 19:31:47 +00:00
|
|
|
"optional", "required" and "forbidden". The default value is "optional".
|
2017-01-26 06:15:00 +00:00
|
|
|
|
2022-04-22 22:57:27 +00:00
|
|
|
- `DispatchIdempotencyToken` - Optional identifier used to prevent more than one
|
|
|
|
instance of the job from being dispatched.
|
|
|
|
|
2017-05-26 23:15:35 +00:00
|
|
|
- `Payload` - The payload may not be set when submitting a job but may appear in
|
2017-01-26 06:15:00 +00:00
|
|
|
a dispatched job. The `Payload` will be a base64 encoded string containing the
|
2017-01-26 19:31:47 +00:00
|
|
|
payload that the job was dispatched with. The `payload` has a **maximum size
|
|
|
|
of 16 KiB**.
|
2017-01-26 06:15:00 +00:00
|
|
|
|
2017-05-26 23:15:35 +00:00
|
|
|
- `Priority` - Specifies the job priority which is used to prioritize
|
2016-02-21 18:19:37 +00:00
|
|
|
scheduling and access to resources. Must be between 1 and 100 inclusively,
|
|
|
|
and defaults to 50.
|
|
|
|
|
2017-05-26 23:15:35 +00:00
|
|
|
- `Region` - The region to run the job in, defaults to "global".
|
2016-02-21 18:19:37 +00:00
|
|
|
|
2017-05-26 23:15:35 +00:00
|
|
|
- `Type` - Specifies the job type and switches which scheduler
|
2016-02-21 18:19:37 +00:00
|
|
|
is used. Nomad provides the `service`, `system` and `batch` schedulers,
|
|
|
|
and defaults to `service`. To learn more about each scheduler type visit
|
2023-01-25 17:31:14 +00:00
|
|
|
[here](/nomad/docs/schedulers)
|
2016-02-21 18:19:37 +00:00
|
|
|
|
2017-07-26 00:18:15 +00:00
|
|
|
- `Update` - Specifies an update strategy to be applied to all task groups
|
|
|
|
within the job. When specified both at the job level and the task group level,
|
|
|
|
the update blocks are merged with the task group's taking precedence. For more
|
2023-01-30 14:48:43 +00:00
|
|
|
details on the update block, please see below.
|
2016-02-21 18:19:37 +00:00
|
|
|
|
2020-02-06 23:45:31 +00:00
|
|
|
- `Periodic` - `Periodic` allows the job to be scheduled at fixed times, dates
|
|
|
|
or intervals. The periodic expression is always evaluated in the UTC
|
|
|
|
timezone to ensure consistent evaluation when Nomad Servers span multiple
|
|
|
|
time zones. The `Periodic` object is optional and supports the following attributes:
|
2016-02-21 18:19:37 +00:00
|
|
|
|
2020-02-06 23:45:31 +00:00
|
|
|
- `Enabled` - `Enabled` determines whether the periodic job will spawn child
|
2016-02-21 18:19:37 +00:00
|
|
|
jobs.
|
|
|
|
|
2020-02-06 23:45:31 +00:00
|
|
|
- `TimeZone` - Specifies the time zone to evaluate the next launch interval
|
|
|
|
against. This is useful when wanting to account for day light savings in
|
|
|
|
various time zones. The time zone must be parsable by Golang's
|
|
|
|
[LoadLocation](https://golang.org/pkg/time/#LoadLocation). The default is
|
|
|
|
UTC.
|
2017-02-15 22:37:06 +00:00
|
|
|
|
2020-02-06 23:45:31 +00:00
|
|
|
- `SpecType` - `SpecType` determines how Nomad is going to interpret the
|
|
|
|
periodic expression. `cron` is the only supported `SpecType` currently.
|
2016-02-21 18:19:37 +00:00
|
|
|
|
2020-02-06 23:45:31 +00:00
|
|
|
- `Spec` - A cron expression configuring the interval the job is launched
|
2016-02-21 18:19:37 +00:00
|
|
|
at. Supports predefined expressions such as "@daily" and "@weekly" See
|
|
|
|
[here](https://github.com/gorhill/cronexpr#implementation) for full
|
|
|
|
documentation of supported cron specs and the predefined expressions.
|
|
|
|
|
2020-05-01 20:02:21 +00:00
|
|
|
- <a id="prohibit_overlap">`ProhibitOverlap`</a> - `ProhibitOverlap` can be set
|
|
|
|
to true to enforce that the periodic job doesn't spawn a new instance of the
|
|
|
|
job if any of the previous jobs are still running. It is defaulted to false.
|
2020-02-06 23:45:31 +00:00
|
|
|
|
|
|
|
An example `periodic` block:
|
|
|
|
|
|
|
|
```json
|
|
|
|
{
|
|
|
|
"Periodic": {
|
|
|
|
"Spec": "*/15 - *",
|
|
|
|
"TimeZone": "Europe/Berlin",
|
|
|
|
"SpecType": "cron",
|
|
|
|
"Enabled": true,
|
|
|
|
"ProhibitOverlap": true
|
2016-10-03 22:23:50 +00:00
|
|
|
}
|
2020-02-06 23:45:31 +00:00
|
|
|
}
|
|
|
|
```
|
2016-02-21 18:19:37 +00:00
|
|
|
|
2018-02-09 22:31:24 +00:00
|
|
|
- `ReschedulePolicy` - Specifies a reschedule policy to be applied to all task groups
|
|
|
|
within the job. When specified both at the job level and the task group level,
|
|
|
|
the reschedule blocks are merged, with the task group's taking precedence. For more
|
|
|
|
details on `ReschedulePolicy`, please see below.
|
|
|
|
|
2016-02-21 18:19:37 +00:00
|
|
|
### Task Group
|
|
|
|
|
2016-05-09 23:23:25 +00:00
|
|
|
`TaskGroups` is a list of `TaskGroup` objects, each supports the following
|
2016-02-21 18:19:37 +00:00
|
|
|
attributes:
|
|
|
|
|
2017-05-26 23:15:35 +00:00
|
|
|
- `Constraints` - This is a list of `Constraint` objects. See the constraint
|
2016-05-09 23:23:25 +00:00
|
|
|
reference for more details.
|
|
|
|
|
2018-11-05 22:41:20 +00:00
|
|
|
- `Affinities` - This is a list of `Affinity` objects. See the affinity
|
2020-02-06 23:45:31 +00:00
|
|
|
reference for more details.
|
2018-11-05 22:41:20 +00:00
|
|
|
|
2019-01-04 03:59:23 +00:00
|
|
|
- `Spreads` - This is a list of `Spread` objects. See the spread
|
|
|
|
reference for more details.
|
|
|
|
|
2017-05-26 23:15:35 +00:00
|
|
|
- `Count` - Specifies the number of the task groups that should
|
2016-04-14 23:47:24 +00:00
|
|
|
be running. Must be non-negative, defaults to one.
|
2016-02-21 18:19:37 +00:00
|
|
|
|
2017-05-26 23:15:35 +00:00
|
|
|
- `Meta` - A key-value map that annotates the task group with opaque metadata.
|
2016-05-09 23:23:25 +00:00
|
|
|
|
2018-04-12 18:34:01 +00:00
|
|
|
- `Migrate` - Specifies a migration strategy to be applied during [node
|
|
|
|
drains][drain].
|
|
|
|
|
|
|
|
- `HealthCheck` - One of `checks` or `task_states`. Indicates how task health
|
|
|
|
should be determined: either via Consul health checks or whether the task
|
|
|
|
was able to run successfully.
|
|
|
|
|
|
|
|
- `HealthyDeadline` - Specifies duration a task must become healthy within
|
|
|
|
before it is considered unhealthy.
|
|
|
|
|
|
|
|
- `MaxParallel` - Specifies how many allocations may be migrated at once.
|
|
|
|
|
|
|
|
- `MinHealthyTime` - Specifies duration a task must be considered healthy
|
|
|
|
before the migration is considered healthy.
|
|
|
|
|
2017-05-26 23:15:35 +00:00
|
|
|
- `Name` - The name of the task group. Must be specified.
|
2016-02-21 18:19:37 +00:00
|
|
|
|
2017-05-26 23:15:35 +00:00
|
|
|
- `RestartPolicy` - Specifies the restart policy to be applied to tasks in this group.
|
2016-02-21 18:19:37 +00:00
|
|
|
If omitted, a default policy for batch and non-batch jobs is used based on the
|
2016-08-03 13:42:51 +00:00
|
|
|
job type. See the [restart policy reference](#restart_policy) for more details.
|
2016-02-21 18:19:37 +00:00
|
|
|
|
2018-02-09 22:31:24 +00:00
|
|
|
- `ReschedulePolicy` - Specifies the reschedule policy to be applied to tasks in this group.
|
|
|
|
If omitted, a default policy is used for batch and service jobs. System jobs are not eligible
|
|
|
|
for rescheduling. See the [reschedule policy reference](#reschedule_policy) for more details.
|
|
|
|
|
2020-04-13 21:33:49 +00:00
|
|
|
- `Scaling` - Specifies the autoscaling policy for the task group. This is primarily for supporting
|
|
|
|
external autoscalers. See the [scaling policy reference](#scaling_policy) for more details.
|
|
|
|
|
2017-05-26 23:15:35 +00:00
|
|
|
- `EphemeralDisk` - Specifies the group's ephemeral disk requirements. See the
|
2017-04-07 19:49:53 +00:00
|
|
|
[ephemeral disk reference](#ephemeral_disk) for more details.
|
|
|
|
|
2017-07-26 00:18:15 +00:00
|
|
|
- `Update` - Specifies an update strategy to be applied to all task groups
|
|
|
|
within the job. When specified both at the job level and the task group level,
|
|
|
|
the update blocks are merged with the task group's taking precedence. For more
|
2023-01-30 14:48:43 +00:00
|
|
|
details on the update block, please see below.
|
2017-07-26 00:18:15 +00:00
|
|
|
|
2017-05-26 23:15:35 +00:00
|
|
|
- `Tasks` - A list of `Task` object that are part of the task group.
|
2016-02-21 18:19:37 +00:00
|
|
|
|
|
|
|
### Task
|
|
|
|
|
|
|
|
The `Task` object supports the following keys:
|
|
|
|
|
2017-05-26 23:15:35 +00:00
|
|
|
- `Artifacts` - `Artifacts` is a list of `Artifact` objects which define
|
2016-05-09 23:23:25 +00:00
|
|
|
artifacts to be downloaded before the task is run. See the artifacts
|
|
|
|
reference for more details.
|
|
|
|
|
2017-05-26 23:15:35 +00:00
|
|
|
- `Config` - A map of key-value configuration passed into the driver
|
2016-05-09 23:23:25 +00:00
|
|
|
to start the task. The details of configurations are specific to
|
|
|
|
each driver.
|
|
|
|
|
2017-05-26 23:15:35 +00:00
|
|
|
- `Constraints` - This is a list of `Constraint` objects. See the constraint
|
2016-05-09 23:23:25 +00:00
|
|
|
reference for more details.
|
|
|
|
|
2018-11-05 22:41:20 +00:00
|
|
|
- `Affinities` - This is a list of `Affinity` objects. See the affinity
|
2020-02-06 23:45:31 +00:00
|
|
|
reference for more details.
|
2018-11-05 22:41:20 +00:00
|
|
|
|
2019-01-04 03:59:23 +00:00
|
|
|
- `Spreads` - This is a list of `Spread` objects. See the spread
|
|
|
|
reference for more details.
|
|
|
|
|
2017-01-26 06:15:00 +00:00
|
|
|
- `DispatchPayload` - Configures the task to have access to dispatch payloads.
|
|
|
|
The `DispatchPayload` object supports the following attributes:
|
|
|
|
|
2017-05-26 23:15:35 +00:00
|
|
|
- `File` - Specifies the file name to write the content of dispatch payload
|
2017-01-26 06:15:00 +00:00
|
|
|
to. The file is written relative to the task's local directory.
|
|
|
|
|
2017-05-26 23:15:35 +00:00
|
|
|
- `Driver` - Specifies the task driver that should be used to run the
|
2023-01-25 17:31:14 +00:00
|
|
|
task. See the [driver documentation](/nomad/docs/drivers) for what
|
2016-02-21 18:19:37 +00:00
|
|
|
is available. Examples include `docker`, `qemu`, `java`, and `exec`.
|
|
|
|
|
2020-02-06 23:45:31 +00:00
|
|
|
- `Env` - A map of key-value representing environment variables that
|
|
|
|
will be passed along to the running process. Nomad variables are
|
|
|
|
interpreted when set in the environment variable values. See the table of
|
2023-01-25 17:31:14 +00:00
|
|
|
interpreted variables [here](/nomad/docs/runtime/interpolation).
|
2016-04-14 23:47:24 +00:00
|
|
|
|
2020-02-06 23:45:31 +00:00
|
|
|
For example the below environment map will be reinterpreted:
|
2016-02-21 18:19:37 +00:00
|
|
|
|
2020-02-06 23:45:31 +00:00
|
|
|
```json
|
|
|
|
{
|
|
|
|
"Env": {
|
|
|
|
"NODE_CLASS": "${nomad.class}"
|
2016-10-03 22:23:50 +00:00
|
|
|
}
|
2020-02-06 23:45:31 +00:00
|
|
|
}
|
|
|
|
```
|
2016-02-21 18:19:37 +00:00
|
|
|
|
2023-02-02 18:59:14 +00:00
|
|
|
- `Identity` - Specifies whether to expose Nomad's [Workload Identity][]
|
|
|
|
to the task.
|
|
|
|
|
|
|
|
- `Env` - If `true` the `NOMAD_TOKEN` environment variable will be set.
|
|
|
|
|
|
|
|
- `File` - If `true` the `secrets/nomad_token` file will be created.
|
|
|
|
|
2017-12-20 00:19:40 +00:00
|
|
|
- `KillSignal` - Specifies a configurable kill signal for a task, where the
|
|
|
|
default is SIGINT. Note that this is only supported for drivers which accept
|
|
|
|
sending signals (currently `docker`, `exec`, `raw_exec`, and `java` drivers).
|
|
|
|
|
2017-05-26 23:15:35 +00:00
|
|
|
- `KillTimeout` - `KillTimeout` is a time duration in nanoseconds. It can be
|
2016-05-09 23:23:25 +00:00
|
|
|
used to configure the time between signaling a task it will be killed and
|
|
|
|
actually killing it. Drivers first sends a task the `SIGINT` signal and then
|
|
|
|
sends `SIGTERM` if the task doesn't die after the `KillTimeout` duration has
|
2016-09-12 16:53:57 +00:00
|
|
|
elapsed. The default `KillTimeout` is 5 seconds.
|
2016-05-09 23:23:25 +00:00
|
|
|
|
2017-12-20 00:19:40 +00:00
|
|
|
- `Leader` - Specifies whether the task is the leader task of the task group. If
|
2017-02-13 18:18:34 +00:00
|
|
|
set to true, when the leader task completes, all other tasks within the task
|
|
|
|
group will be gracefully shutdown.
|
|
|
|
|
2017-05-26 23:15:35 +00:00
|
|
|
- `LogConfig` - This allows configuring log rotation for the `stdout` and `stderr`
|
2016-05-09 23:23:25 +00:00
|
|
|
buffers of a Task. See the log rotation reference below for more details.
|
|
|
|
|
2017-05-26 23:15:35 +00:00
|
|
|
- `Meta` - Annotates the task group with opaque metadata.
|
2016-05-09 23:23:25 +00:00
|
|
|
|
2017-05-26 23:15:35 +00:00
|
|
|
- `Name` - The name of the task. This field is required.
|
2016-05-09 23:23:25 +00:00
|
|
|
|
2017-05-26 23:15:35 +00:00
|
|
|
- `Resources` - Provides the resource requirements of the task.
|
2016-05-09 23:23:25 +00:00
|
|
|
See the resources reference for more details.
|
|
|
|
|
2020-04-13 21:33:49 +00:00
|
|
|
- `RestartPolicy` - Specifies the task-specific restart policy.
|
|
|
|
If omitted, the restart policy from the encapsulating task group is used. If both
|
|
|
|
are present, they are merged. See the [restart policy reference](#restart_policy)
|
|
|
|
for more details.
|
|
|
|
|
2017-05-26 23:15:35 +00:00
|
|
|
- `Services` - `Services` is a list of `Service` objects. Nomad integrates with
|
2016-05-09 23:23:25 +00:00
|
|
|
Consul for service discovery. A `Service` object represents a routable and
|
|
|
|
discoverable service on the network. Nomad automatically registers when a task
|
|
|
|
is started and de-registers it when the task transitions to the dead state.
|
2023-01-25 17:31:14 +00:00
|
|
|
[Click here](/nomad/docs/integrations/consul-integration#service-discovery) to learn more about
|
2016-05-09 23:23:25 +00:00
|
|
|
services. Below is the fields in the `Service` object:
|
2016-02-21 18:19:37 +00:00
|
|
|
|
2020-02-06 23:45:31 +00:00
|
|
|
- `Name`: An explicit name for the Service. Nomad will replace `${JOB}`,
|
|
|
|
`${TASKGROUP}` and `${TASK}` by the name of the job, task group or task,
|
|
|
|
respectively. `${BASE}` expands to the equivalent of
|
|
|
|
`${JOB}-${TASKGROUP}-${TASK}`, and is the default name for a Service.
|
|
|
|
Each service defined for a given task must have a distinct name, so if
|
|
|
|
a task has multiple services only one of them can use the default name
|
|
|
|
and the others must be explicitly named. Names must adhere to
|
|
|
|
[RFC-1123 §2.1](https://tools.ietf.org/html/rfc1123#section-2) and are
|
|
|
|
limited to alphanumeric and hyphen characters (i.e. `[a-z0-9\-]`), and be
|
|
|
|
less than 64 characters in length.
|
|
|
|
|
|
|
|
- `Tags`: A list of string tags associated with this Service. String
|
|
|
|
interpolation is supported in tags.
|
|
|
|
|
|
|
|
- `Meta`: A key-value map that annotates the Consul service with
|
|
|
|
user-defined metadata. String interpolation is supported in meta.
|
|
|
|
|
|
|
|
- `CanaryTags`: A list of string tags associated with this Service while it
|
|
|
|
is a canary. Once the canary is promoted, the registered tags will be
|
|
|
|
updated to the set defined in the `Tags` field. String interpolation is
|
|
|
|
supported in tags.
|
|
|
|
|
|
|
|
- `CanaryMeta`: A key-value map that annotates this Service while it
|
|
|
|
is a canary. Once the canary is promoted, the registered meta will be
|
|
|
|
updated to the set defined in the `Meta` field or removed if the `Meta`
|
|
|
|
field is not set. String interpolation is supported in meta keys and
|
|
|
|
values.
|
|
|
|
|
|
|
|
- `PortLabel`: `PortLabel` is an optional string and is used to associate
|
|
|
|
a port with the service. If specified, the port label must match one
|
|
|
|
defined in the resources block. This could be a label of either a
|
|
|
|
dynamic or a static port.
|
|
|
|
|
2022-04-22 22:57:27 +00:00
|
|
|
- `Provider`: Specifies the service registration provider to use for service
|
|
|
|
registrations. Valid options are either `consul` or `nomad`. All services
|
|
|
|
within a single task group must utilise the same provider value.
|
|
|
|
|
|
|
|
- `Address`: Specifies a custom address to advertise in Consul or Nomad
|
|
|
|
service registration. If set, `AddressMode` must be in `auto` mode. Useful
|
|
|
|
with interpolation - for example to advertise the public IP address of an
|
|
|
|
AWS EC2 instance set this to `${attr.unique.platform.aws.public-ipv4}`.
|
|
|
|
|
2020-02-06 23:45:31 +00:00
|
|
|
- `AddressMode`: Specifies what address (host or driver-specific) this
|
|
|
|
service should advertise. This setting is supported in Docker since
|
|
|
|
Nomad 0.6 and rkt since Nomad 0.7. Valid options are:
|
|
|
|
|
|
|
|
- `auto` - Allows the driver to determine whether the host or driver
|
|
|
|
address should be used. Defaults to `host` and only implemented by
|
|
|
|
Docker. If you use a Docker network plugin such as weave, Docker will
|
|
|
|
automatically use its address.
|
|
|
|
|
|
|
|
- `driver` - Use the IP specified by the driver, and the port specified
|
|
|
|
in a port map. A numeric port may be specified since port maps aren't
|
|
|
|
required by all network plugins. Useful for advertising SDN and
|
|
|
|
overlay network addresses. Task will fail if driver network cannot be
|
|
|
|
determined. Only implemented for Docker and rkt.
|
|
|
|
|
|
|
|
- `host` - Use the host IP and port.
|
|
|
|
|
|
|
|
- `Checks`: `Checks` is an array of check objects. A check object defines a
|
|
|
|
health check associated with the service. Nomad supports the `script`,
|
|
|
|
`http` and `tcp` Consul Checks. Script checks are not supported for the
|
|
|
|
qemu driver since the Nomad client doesn't have access to the file system
|
2020-12-03 00:02:03 +00:00
|
|
|
of a task using the QEMU driver.
|
2020-02-06 23:45:31 +00:00
|
|
|
|
|
|
|
- `Type`: This indicates the check types supported by Nomad. Valid
|
|
|
|
options are currently `script`, `http` and `tcp`.
|
|
|
|
|
|
|
|
- `Name`: The name of the health check.
|
|
|
|
|
2021-03-31 10:37:56 +00:00
|
|
|
- `AddressMode`: Same as `AddressMode` on `Service`. Unlike services,
|
|
|
|
checks do not have an `auto` address mode as there's no way for
|
|
|
|
Nomad to know which is the best address to use for checks. Consul
|
|
|
|
needs access to the address for any HTTP or TCP checks. Added in
|
|
|
|
Nomad 0.7.1. Unlike `PortLabel`, this setting is _not_ inherited
|
|
|
|
from the `Service`.
|
|
|
|
|
|
|
|
- `PortLabel`: Specifies the label of the port on which the check will
|
|
|
|
be performed. Note this is the _label_ of the port and not the port
|
|
|
|
number unless `AddressMode: "driver"`. The port label must match one
|
2023-01-30 14:48:43 +00:00
|
|
|
defined in the Network block. If a port value was declared on the
|
2021-03-31 10:37:56 +00:00
|
|
|
`Service`, this will inherit from that value if not supplied. If
|
|
|
|
supplied, this value takes precedence over the `Service.PortLabel`
|
|
|
|
value. This is useful for services which operate on multiple ports.
|
|
|
|
`http` and `tcp` checks require a port while `script` checks do not.
|
|
|
|
Checks will use the host IP and ports by default. In Nomad 0.7.1 or
|
|
|
|
later numeric ports may be used if `AddressMode: "driver"` is set on
|
|
|
|
the check.
|
|
|
|
|
|
|
|
- `Header`: Headers for HTTP checks. Should be an object where the values
|
|
|
|
are an array of values. Headers will be written once for each value.
|
2020-02-06 23:45:31 +00:00
|
|
|
|
|
|
|
- `Interval`: This indicates the frequency of the health checks that
|
|
|
|
Consul will perform.
|
|
|
|
|
|
|
|
- `Timeout`: This indicates how long Consul will wait for a health
|
|
|
|
check query to succeed.
|
|
|
|
|
|
|
|
- `Method`: The HTTP method to use for HTTP checks. Defaults to GET.
|
|
|
|
|
2021-03-18 11:27:48 +00:00
|
|
|
- `Body`: The HTTP body to use for HTTP checks. Defaults to an empty string.
|
|
|
|
|
2020-02-06 23:45:31 +00:00
|
|
|
- `Path`: The path of the HTTP endpoint which Consul will query to query
|
|
|
|
the health of a service if the type of the check is `http`. Nomad
|
|
|
|
will add the IP of the service and the port, users are only required
|
|
|
|
to add the relative URL of the health check endpoint. Absolute paths
|
|
|
|
are not allowed.
|
|
|
|
|
|
|
|
- `Protocol`: This indicates the protocol for the HTTP checks. Valid
|
|
|
|
options are `http` and `https`. We default it to `http`.
|
|
|
|
|
|
|
|
- `Command`: This is the command that the Nomad client runs for doing
|
|
|
|
script based health check.
|
|
|
|
|
|
|
|
- `Args`: Additional arguments to the `command` for script based health
|
|
|
|
checks.
|
|
|
|
|
2021-03-31 10:37:56 +00:00
|
|
|
- `TLSSkipVerify`: If true, Consul will not attempt to verify the
|
|
|
|
certificate when performing HTTPS checks. Requires Consul >= 0.7.2.
|
2020-02-06 23:45:31 +00:00
|
|
|
|
|
|
|
- `CheckRestart`: `CheckRestart` is an object which enables
|
|
|
|
restarting of tasks based upon Consul health checks.
|
|
|
|
|
|
|
|
- `Limit`: The number of unhealthy checks allowed before the
|
|
|
|
service is restarted. Defaults to `0` which disables health-based restarts.
|
|
|
|
|
|
|
|
- `Grace`: The duration to wait after a task starts or restarts
|
|
|
|
before counting unhealthy checks count against the limit. Defaults to "1s".
|
|
|
|
|
|
|
|
- `IgnoreWarnings`: Treat checks that are warning as passing.
|
|
|
|
Defaults to false which means warnings are considered unhealthy.
|
2017-09-11 04:38:31 +00:00
|
|
|
|
2017-08-17 18:30:29 +00:00
|
|
|
- `ShutdownDelay` - Specifies the duration to wait when killing a task between
|
|
|
|
removing it from Consul and sending it a shutdown signal. Ideally services
|
|
|
|
would fail healthchecks once they receive a shutdown signal. Alternatively
|
|
|
|
`ShutdownDelay` may be set to give in flight requests time to complete before
|
|
|
|
shutting down.
|
|
|
|
|
2017-05-26 23:15:35 +00:00
|
|
|
- `Templates` - Specifies the set of [`Template`](#template) objects to render for the task.
|
2017-01-24 17:12:42 +00:00
|
|
|
Templates can be used to inject both static and dynamic configuration with
|
|
|
|
data populated from environment variables, Consul and Vault.
|
2016-04-22 18:12:02 +00:00
|
|
|
|
2017-05-26 23:15:35 +00:00
|
|
|
- `User` - Set the user that will run the task. It defaults to the same user
|
2016-06-12 21:33:45 +00:00
|
|
|
the Nomad client is being run as. This can only be set on Linux platforms.
|
2016-04-14 23:47:24 +00:00
|
|
|
|
2016-02-21 18:19:37 +00:00
|
|
|
### Resources
|
|
|
|
|
|
|
|
The `Resources` object supports the following keys:
|
|
|
|
|
2017-05-26 23:15:35 +00:00
|
|
|
- `CPU` - The CPU required in MHz.
|
2016-02-21 18:19:37 +00:00
|
|
|
|
2017-05-26 23:15:35 +00:00
|
|
|
- `MemoryMB` - The memory required in MB.
|
2016-02-21 18:19:37 +00:00
|
|
|
|
2017-05-26 23:15:35 +00:00
|
|
|
- `Networks` - A list of network objects.
|
2016-02-21 18:19:37 +00:00
|
|
|
|
2019-01-23 18:51:33 +00:00
|
|
|
- `Devices` - A list of device objects.
|
|
|
|
|
2016-02-21 18:19:37 +00:00
|
|
|
The Network object supports the following keys:
|
|
|
|
|
2017-05-26 23:15:35 +00:00
|
|
|
- `MBits` - The number of MBits in bandwidth required.
|
2016-02-21 18:19:37 +00:00
|
|
|
|
2016-05-09 23:23:25 +00:00
|
|
|
Nomad can allocate two types of ports to a task - Dynamic and Static/Reserved
|
|
|
|
ports. A network object allows the user to specify a list of `DynamicPorts` and
|
|
|
|
`ReservedPorts`. Each object supports the following attributes:
|
2016-02-21 18:19:37 +00:00
|
|
|
|
2017-05-26 23:15:35 +00:00
|
|
|
- `Value` - The port number for static ports. If the port is dynamic, then this
|
2016-02-21 18:19:37 +00:00
|
|
|
attribute is ignored.
|
2017-05-26 23:15:35 +00:00
|
|
|
- `Label` - The label to annotate a port so that it can be referred in the
|
2016-02-21 18:19:37 +00:00
|
|
|
service discovery block or environment variables.
|
|
|
|
|
2019-01-23 18:51:33 +00:00
|
|
|
The Device object supports the following keys:
|
|
|
|
|
|
|
|
- `Name` - Specifies the device required. The following inputs are valid:
|
|
|
|
|
2020-02-06 23:45:31 +00:00
|
|
|
- `<device_type>`: If a single value is given, it is assumed to be the device
|
2019-01-23 18:51:33 +00:00
|
|
|
type, such as "gpu", or "fpga".
|
|
|
|
|
2020-02-06 23:45:31 +00:00
|
|
|
- `<vendor>/<device_type>`: If two values are given separated by a `/`, the
|
2019-01-23 18:51:33 +00:00
|
|
|
given device type will be selected, constraining on the provided vendor.
|
|
|
|
Examples include "nvidia/gpu" or "amd/gpu".
|
|
|
|
|
2020-02-06 23:45:31 +00:00
|
|
|
- `<vendor>/<device_type>/<model>`: If three values are given separated by a `/`, the
|
2019-01-23 18:51:33 +00:00
|
|
|
given device type will be selected, constraining on the provided vendor, and
|
|
|
|
model name. Examples include "nvidia/gpu/1080ti" or "nvidia/gpu/2080ti".
|
|
|
|
|
2020-02-06 23:45:31 +00:00
|
|
|
* `Count` - The count of devices being requested per task. Defaults to 1.
|
2019-01-23 18:51:33 +00:00
|
|
|
|
2020-02-06 23:45:31 +00:00
|
|
|
* `Constraints` - A list to define constraints on which device can satisfy the
|
2019-01-23 18:51:33 +00:00
|
|
|
request. See the constraint reference for more details.
|
|
|
|
|
2020-02-06 23:45:31 +00:00
|
|
|
* `Affinities` - A list to define preferences for which device should be
|
|
|
|
chosen. See the affinity reference for more details.
|
2019-01-23 18:51:33 +00:00
|
|
|
|
2017-04-07 19:49:53 +00:00
|
|
|
<a id="ephemeral_disk"></a>
|
|
|
|
|
|
|
|
### Ephemeral Disk
|
|
|
|
|
|
|
|
The `EphemeralDisk` object supports the following keys:
|
|
|
|
|
2017-05-26 23:15:35 +00:00
|
|
|
- `Migrate` - Specifies that the Nomad client should make a best-effort attempt
|
2017-04-07 19:49:53 +00:00
|
|
|
to migrate the data from a remote machine if placement cannot be made on the
|
|
|
|
original node. During data migration, the task will block starting until the
|
|
|
|
data migration has completed. Value is a boolean and the default is false.
|
|
|
|
|
2017-05-26 23:15:35 +00:00
|
|
|
- `SizeMB` - Specifies the size of the ephemeral disk in MB. Default is 300.
|
2017-04-07 19:49:53 +00:00
|
|
|
|
2017-05-26 23:15:35 +00:00
|
|
|
- `Sticky` - Specifies that Nomad should make a best-effort attempt to place the
|
2017-04-07 19:49:53 +00:00
|
|
|
updated allocation on the same machine. This will move the `local/` and
|
|
|
|
`alloc/data` directories to the new allocation. Value is a boolean and the
|
|
|
|
default is false.
|
|
|
|
|
2018-02-09 22:31:24 +00:00
|
|
|
<a id="reschedule_policy"></a>
|
|
|
|
|
|
|
|
### Reschedule Policy
|
|
|
|
|
|
|
|
The `ReschedulePolicy` object supports the following keys:
|
|
|
|
|
|
|
|
- `Attempts` - `Attempts` is the number of reschedule attempts allowed
|
|
|
|
in an `Interval`.
|
|
|
|
|
|
|
|
- `Interval` - `Interval` is a time duration that is specified in nanoseconds.
|
|
|
|
The `Interval` is a sliding window within which at most `Attempts` number
|
|
|
|
of reschedule attempts are permitted.
|
|
|
|
|
2018-03-21 20:22:29 +00:00
|
|
|
- `Delay` - A duration to wait before attempting rescheduling. It is specified in
|
|
|
|
nanoseconds.
|
|
|
|
|
2018-03-27 19:09:04 +00:00
|
|
|
- `DelayFunction` - Specifies the function that is used to calculate subsequent reschedule delays.
|
|
|
|
The initial delay is specified by the `Delay` parameter. Allowed values for `DelayFunction` are listed below:
|
2018-03-21 20:22:29 +00:00
|
|
|
|
2020-02-06 23:45:31 +00:00
|
|
|
- `constant` - The delay between reschedule attempts stays at the `Delay` value.
|
|
|
|
- `exponential` - The delay between reschedule attempts doubles.
|
|
|
|
- `fibonacci` - The delay between reschedule attempts is calculated by adding the two most recent
|
|
|
|
delays applied. For example if `Delay` is set to 5 seconds, the next five reschedule attempts will be
|
|
|
|
delayed by 5 seconds, 5 seconds, 10 seconds, 15 seconds, and 25 seconds respectively.
|
|
|
|
|
|
|
|
- `MaxDelay` - `MaxDelay` is an upper bound on the delay beyond which it will not increase. This parameter is used when
|
|
|
|
`DelayFunction` is `exponential` or `fibonacci`, and is ignored when `constant` delay is used.
|
2018-03-21 20:22:29 +00:00
|
|
|
|
|
|
|
- `Unlimited` - `Unlimited` enables unlimited reschedule attempts. If this is set to true
|
|
|
|
the `Attempts` and `Interval` fields are not used.
|
|
|
|
|
2016-08-03 13:42:51 +00:00
|
|
|
<a id="restart_policy"></a>
|
|
|
|
|
2016-02-21 18:19:37 +00:00
|
|
|
### Restart Policy
|
|
|
|
|
|
|
|
The `RestartPolicy` object supports the following keys:
|
|
|
|
|
2017-05-26 23:15:35 +00:00
|
|
|
- `Attempts` - `Attempts` is the number of restarts allowed in an `Interval`.
|
2016-02-21 18:19:37 +00:00
|
|
|
|
2017-05-26 23:15:35 +00:00
|
|
|
- `Interval` - `Interval` is a time duration that is specified in nanoseconds.
|
2016-04-14 23:47:24 +00:00
|
|
|
The `Interval` begins when the first task starts and ensures that only
|
|
|
|
`Attempts` number of restarts happens within it. If more than `Attempts`
|
|
|
|
number of failures happen, behavior is controlled by `Mode`.
|
2016-02-21 18:19:37 +00:00
|
|
|
|
2017-05-26 23:15:35 +00:00
|
|
|
- `Delay` - A duration to wait before restarting a task. It is specified in
|
2016-02-21 18:19:37 +00:00
|
|
|
nanoseconds. A random jitter of up to 25% is added to the delay.
|
|
|
|
|
2020-02-06 23:45:31 +00:00
|
|
|
- `Mode` - `Mode` is given as a string and controls the behavior when the task
|
|
|
|
fails more than `Attempts` times in an `Interval`. Possible values are listed
|
|
|
|
below:
|
2016-02-21 18:19:37 +00:00
|
|
|
|
2020-02-06 23:45:31 +00:00
|
|
|
- `delay` - `delay` will delay the next restart until the next `Interval` is
|
|
|
|
reached.
|
2016-02-21 18:19:37 +00:00
|
|
|
|
2020-02-06 23:45:31 +00:00
|
|
|
- `fail` - `fail` will not restart the task again.
|
2016-02-21 18:19:37 +00:00
|
|
|
|
2017-07-26 00:18:15 +00:00
|
|
|
### Update
|
|
|
|
|
|
|
|
Specifies the task group update strategy. When omitted, rolling updates are
|
2023-01-30 14:48:43 +00:00
|
|
|
disabled. The update block can be specified at the job or task group level.
|
|
|
|
When specified at the job, the update block is inherited by all task groups.
|
|
|
|
When specified in both the job and in a task group, the blocks are merged with
|
2017-07-26 00:18:15 +00:00
|
|
|
the task group's taking precedence. The `Update` object supports the following
|
|
|
|
attributes:
|
|
|
|
|
|
|
|
- `MaxParallel` - `MaxParallel` is given as an integer value and specifies
|
2020-02-06 23:45:31 +00:00
|
|
|
the number of tasks that can be updated at the same time.
|
2017-07-26 00:18:15 +00:00
|
|
|
|
|
|
|
- `HealthCheck` - Specifies the mechanism in which allocations health is
|
2020-02-06 23:45:31 +00:00
|
|
|
determined. The potential values are:
|
2017-07-26 00:18:15 +00:00
|
|
|
|
|
|
|
- "checks" - Specifies that the allocation should be considered healthy when
|
2020-02-06 23:45:31 +00:00
|
|
|
all of its tasks are running and their associated checks are healthy,
|
2017-07-26 00:18:15 +00:00
|
|
|
and unhealthy if any of the tasks fail or not all checks become healthy.
|
|
|
|
This is a superset of "task_states" mode.
|
|
|
|
|
|
|
|
- "task_states" - Specifies that the allocation should be considered healthy
|
|
|
|
when all its tasks are running and unhealthy if tasks fail.
|
|
|
|
|
|
|
|
- "manual" - Specifies that Nomad should not automatically determine health
|
|
|
|
and that the operator will specify allocation health using the [HTTP
|
2023-01-25 17:31:14 +00:00
|
|
|
API](/nomad/api-docs/deployments#set-allocation-health-in-deployment).
|
2017-07-26 00:18:15 +00:00
|
|
|
|
|
|
|
- `MinHealthyTime` - Specifies the minimum time the allocation must be in the
|
|
|
|
healthy state before it is marked as healthy and unblocks further allocations
|
2018-04-10 23:00:52 +00:00
|
|
|
from being updated.
|
2017-07-26 00:18:15 +00:00
|
|
|
|
|
|
|
- `HealthyDeadline` - Specifies the deadline in which the allocation must be
|
|
|
|
marked as healthy after which the allocation is automatically transitioned to
|
2018-04-10 23:00:52 +00:00
|
|
|
unhealthy.
|
|
|
|
|
|
|
|
- `ProgressDeadline` - Specifies the deadline in which an allocation must be
|
|
|
|
marked as healthy. The deadline begins when the first allocation for the
|
|
|
|
deployment is created and is reset whenever an allocation as part of the
|
|
|
|
deployment transitions to a healthy state. If no allocation transitions to the
|
|
|
|
healthy state before the progress deadline, the deployment is marked as
|
|
|
|
failed. If the `progress_deadline` is set to `0`, the first allocation to be
|
|
|
|
marked as unhealthy causes the deployment to fail.
|
2017-07-26 00:18:15 +00:00
|
|
|
|
|
|
|
- `AutoRevert` - Specifies if the job should auto-revert to the last stable job
|
|
|
|
on deployment failure. A job is marked as stable if all the allocations as
|
|
|
|
part of its deployment were marked healthy.
|
|
|
|
|
|
|
|
- `Canary` - Specifies that changes to the job that would result in destructive
|
|
|
|
updates should create the specified number of canaries without stopping any
|
|
|
|
previous allocations. Once the operator determines the canaries are healthy,
|
|
|
|
they can be promoted which unblocks a rolling update of the remaining
|
|
|
|
allocations at a rate of `max_parallel`.
|
|
|
|
|
2019-06-05 15:09:22 +00:00
|
|
|
- `AutoPromote` - Specifies if the job should automatically promote to
|
2019-05-09 13:42:18 +00:00
|
|
|
the new deployment if all canaries become healthy.
|
|
|
|
|
2017-07-26 00:18:15 +00:00
|
|
|
- `Stagger` - Specifies the delay between migrating allocations off nodes marked
|
2018-04-10 23:00:52 +00:00
|
|
|
for draining.
|
2017-07-26 00:18:15 +00:00
|
|
|
|
|
|
|
An example `Update` block:
|
|
|
|
|
|
|
|
```json
|
|
|
|
{
|
|
|
|
"Update": {
|
2020-02-06 23:45:31 +00:00
|
|
|
"MaxParallel": 3,
|
|
|
|
"HealthCheck": "checks",
|
|
|
|
"MinHealthyTime": 15000000000,
|
|
|
|
"HealthyDeadline": 180000000000,
|
|
|
|
"AutoRevert": false,
|
|
|
|
"AutoPromote": false,
|
|
|
|
"Canary": 1
|
2017-07-26 00:18:15 +00:00
|
|
|
}
|
|
|
|
}
|
|
|
|
```
|
|
|
|
|
2016-02-21 18:19:37 +00:00
|
|
|
### Constraint
|
|
|
|
|
2016-04-14 23:47:24 +00:00
|
|
|
The `Constraint` object supports the following keys:
|
2016-02-21 18:19:37 +00:00
|
|
|
|
2017-05-26 23:15:35 +00:00
|
|
|
- `LTarget` - Specifies the attribute to examine for the
|
2023-01-25 17:31:14 +00:00
|
|
|
constraint. See the table of attributes [here](/nomad/docs/runtime/interpolation#interpreted_node_vars).
|
2016-02-21 18:19:37 +00:00
|
|
|
|
2017-05-26 23:15:35 +00:00
|
|
|
- `RTarget` - Specifies the value to compare the attribute against.
|
2016-04-14 23:47:24 +00:00
|
|
|
This can be a literal value, another attribute or a regular expression if
|
|
|
|
the `Operator` is in "regexp" mode.
|
2016-02-21 18:19:37 +00:00
|
|
|
|
2017-05-26 23:15:35 +00:00
|
|
|
- `Operand` - Specifies the test to be performed on the two targets. It takes on the
|
2016-07-13 22:56:42 +00:00
|
|
|
following values:
|
2016-10-03 22:23:50 +00:00
|
|
|
|
2017-05-26 23:15:35 +00:00
|
|
|
- `regexp` - Allows the `RTarget` to be a regular expression to be matched.
|
2016-02-21 18:19:37 +00:00
|
|
|
|
2017-05-26 23:15:35 +00:00
|
|
|
- `set_contains` - Allows the `RTarget` to be a comma separated list of values
|
2016-10-19 20:06:28 +00:00
|
|
|
that should be contained in the LTarget's value.
|
|
|
|
|
2017-08-11 08:29:53 +00:00
|
|
|
- `distinct_hosts` - If set, the scheduler will not co-locate any task groups on the same
|
2020-02-06 23:45:31 +00:00
|
|
|
machine. This can be specified as a job constraint which applies the
|
|
|
|
constraint to all task groups in the job, or as a task group constraint which
|
|
|
|
scopes the effect to just that group. The constraint may not be
|
|
|
|
specified at the task level.
|
2016-02-21 18:19:37 +00:00
|
|
|
|
2020-02-06 23:45:31 +00:00
|
|
|
Placing the constraint at both the job level and at the task group level is
|
|
|
|
redundant since when placed at the job level, the constraint will be applied
|
|
|
|
to all task groups. When specified, `LTarget` and `RTarget` should be
|
|
|
|
omitted.
|
2016-02-21 18:19:37 +00:00
|
|
|
|
2017-05-26 23:15:35 +00:00
|
|
|
- `distinct_property` - If set, the scheduler selects nodes that have a
|
2020-02-06 23:45:31 +00:00
|
|
|
distinct value of the specified property. The `RTarget` specifies how
|
|
|
|
many allocations are allowed to share the value of a property. The
|
|
|
|
`RTarget` must be 1 or greater and if omitted, defaults to 1. This can
|
|
|
|
be specified as a job constraint which applies the constraint to all
|
|
|
|
task groups in the job, or as a task group constraint which scopes the
|
|
|
|
effect to just that group. The constraint may not be specified at the
|
|
|
|
task level.
|
|
|
|
|
|
|
|
Placing the constraint at both the job level and at the task group level is
|
|
|
|
redundant since when placed at the job level, the constraint will be applied
|
|
|
|
to all task groups. When specified, `LTarget` should be the property
|
|
|
|
that should be distinct and `RTarget` should be omitted.
|
2017-03-12 00:18:01 +00:00
|
|
|
|
2017-05-26 23:15:35 +00:00
|
|
|
- Comparison Operators - `=`, `==`, `is`, `!=`, `not`, `>`, `>=`, `<`, `<=`. The
|
2016-04-14 23:47:24 +00:00
|
|
|
ordering is compared lexically.
|
2016-02-21 18:19:37 +00:00
|
|
|
|
2018-11-05 22:41:20 +00:00
|
|
|
### Affinity
|
|
|
|
|
2018-11-15 17:32:22 +00:00
|
|
|
Affinities allow operators to express placement preferences. More details on how they work
|
2023-01-25 17:31:14 +00:00
|
|
|
are described in [affinities](/nomad/docs/job-specification/affinity)
|
2018-11-15 17:32:22 +00:00
|
|
|
|
2018-11-05 22:41:20 +00:00
|
|
|
The `Affinity` object supports the following keys:
|
|
|
|
|
|
|
|
- `LTarget` - Specifies the attribute to examine for the
|
2023-01-25 17:31:14 +00:00
|
|
|
affinity. See the table of attributes [here](/nomad/docs/runtime/interpolation#interpreted_node_vars).
|
2018-11-05 22:41:20 +00:00
|
|
|
|
|
|
|
- `RTarget` - Specifies the value to compare the attribute against.
|
|
|
|
This can be a literal value, another attribute or a regular expression if
|
|
|
|
the `Operator` is in "regexp" mode.
|
|
|
|
|
|
|
|
- `Operand` - Specifies the test to be performed on the two targets. It takes on the
|
|
|
|
following values:
|
|
|
|
|
|
|
|
- `regexp` - Allows the `RTarget` to be a regular expression to be matched.
|
|
|
|
|
|
|
|
- `set_contains_all` - Allows the `RTarget` to be a comma separated list of values
|
|
|
|
that should be contained in the LTarget's value.
|
|
|
|
|
|
|
|
- `set_contains_any` - Allows the `RTarget` to be a comma separated list of values
|
2020-02-06 23:45:31 +00:00
|
|
|
any of which should be contained in the LTarget's value.
|
2018-11-05 22:41:20 +00:00
|
|
|
|
|
|
|
- Comparison Operators - `=`, `==`, `is`, `!=`, `not`, `>`, `>=`, `<`, `<=`. The
|
|
|
|
ordering is compared lexically.
|
|
|
|
|
|
|
|
- `Weight` - A non zero weight, valid values are from -100 to 100. Used to express
|
2020-02-06 23:45:31 +00:00
|
|
|
relative preference when there is more than one affinity.
|
2018-11-05 22:41:20 +00:00
|
|
|
|
2016-02-21 18:19:37 +00:00
|
|
|
### Log Rotation
|
|
|
|
|
|
|
|
The `LogConfig` object configures the log rotation policy for a task's `stdout` and
|
|
|
|
`stderr`. The `LogConfig` object supports the following attributes:
|
|
|
|
|
2023-05-04 20:01:18 +00:00
|
|
|
- `Disabled` - Disables log collection.
|
2023-04-24 14:00:27 +00:00
|
|
|
|
2017-05-26 23:15:35 +00:00
|
|
|
- `MaxFiles` - The maximum number of rotated files Nomad will retain for
|
2016-02-21 18:19:37 +00:00
|
|
|
`stdout` and `stderr`, each tracked individually.
|
|
|
|
|
2017-05-26 23:15:35 +00:00
|
|
|
- `MaxFileSizeMB` - The size of each rotated file. The size is specified in
|
2016-02-21 18:19:37 +00:00
|
|
|
`MB`.
|
|
|
|
|
|
|
|
If the amount of disk resource requested for the task is less than the total
|
|
|
|
amount of disk space needed to retain the rotated set of files, Nomad will return
|
|
|
|
a validation error when a job is submitted.
|
|
|
|
|
2016-10-03 22:23:50 +00:00
|
|
|
```json
|
|
|
|
{
|
|
|
|
"LogConfig": {
|
2023-05-04 20:01:18 +00:00
|
|
|
"Disabled": false,
|
2016-02-21 18:19:37 +00:00
|
|
|
"MaxFiles": 3,
|
|
|
|
"MaxFileSizeMB": 10
|
2016-10-03 22:23:50 +00:00
|
|
|
}
|
2016-02-21 18:19:37 +00:00
|
|
|
}
|
|
|
|
```
|
|
|
|
|
|
|
|
In the above example we have asked Nomad to retain 3 rotated files for both
|
2017-07-17 18:41:50 +00:00
|
|
|
`stderr` and `stdout` and size of each file is 10 MB. The minimum disk space that
|
|
|
|
would be required for the task would be 60 MB.
|
2016-02-21 18:19:37 +00:00
|
|
|
|
|
|
|
### Artifact
|
|
|
|
|
|
|
|
Nomad downloads artifacts using
|
|
|
|
[`go-getter`](https://github.com/hashicorp/go-getter). The `go-getter` library
|
|
|
|
allows downloading of artifacts from various sources using a URL as the input
|
2016-10-28 00:36:26 +00:00
|
|
|
source. The key-value pairs given in the `options` block map directly to
|
2016-07-18 14:24:30 +00:00
|
|
|
parameters appended to the supplied `source` URL. These are then used by
|
2016-02-21 18:19:37 +00:00
|
|
|
`go-getter` to appropriately download the artifact. `go-getter` also has a CLI
|
|
|
|
tool to validate its URL and can be used to check if the Nomad `artifact` is
|
|
|
|
valid.
|
|
|
|
|
|
|
|
Nomad allows downloading `http`, `https`, and `S3` artifacts. If these artifacts
|
|
|
|
are archives (zip, tar.gz, bz2, etc.), these will be unarchived before the task
|
|
|
|
is started.
|
|
|
|
|
2016-04-14 23:47:24 +00:00
|
|
|
The `Artifact` object supports the following keys:
|
2016-02-21 18:19:37 +00:00
|
|
|
|
2017-05-26 23:15:35 +00:00
|
|
|
- `GetterSource` - The path to the artifact to download.
|
2016-02-21 18:19:37 +00:00
|
|
|
|
2017-05-26 23:15:35 +00:00
|
|
|
- `RelativeDest` - An optional path to download the artifact into relative to the
|
2016-04-14 23:47:24 +00:00
|
|
|
root of the task's directory. If omitted, it will default to `local/`.
|
2016-03-19 19:35:58 +00:00
|
|
|
|
2017-05-26 23:15:35 +00:00
|
|
|
- `GetterOptions` - A `map[string]string` block of options for `go-getter`.
|
2016-03-30 22:22:04 +00:00
|
|
|
Full documentation of supported options are available
|
|
|
|
[here](https://github.com/hashicorp/go-getter/tree/ef5edd3d8f6f482b775199be2f3734fd20e04d4a#protocol-specific-options-1).
|
|
|
|
An example is given below:
|
2016-02-21 18:19:37 +00:00
|
|
|
|
2016-10-03 22:23:50 +00:00
|
|
|
```json
|
|
|
|
{
|
|
|
|
"GetterOptions": {
|
2016-02-21 18:19:37 +00:00
|
|
|
"checksum": "md5:c4aa853ad2215426eb7d70a21922e794",
|
|
|
|
|
|
|
|
"aws_access_key_id": "<id>",
|
|
|
|
"aws_access_key_secret": "<secret>",
|
|
|
|
"aws_access_token": "<token>"
|
2016-10-03 22:23:50 +00:00
|
|
|
}
|
2016-02-21 18:19:37 +00:00
|
|
|
}
|
|
|
|
```
|
|
|
|
|
2016-04-14 23:47:24 +00:00
|
|
|
An example of downloading and unzipping an archive is as simple as:
|
|
|
|
|
2016-10-03 22:23:50 +00:00
|
|
|
```json
|
|
|
|
{
|
|
|
|
"Artifacts": [
|
|
|
|
{
|
|
|
|
"GetterSource": "https://example.com/my.zip",
|
|
|
|
"GetterOptions": {
|
|
|
|
"checksum": "md5:7f4b3e3b4dd5150d4e5aaaa5efada4c3"
|
|
|
|
}
|
2016-05-09 23:23:25 +00:00
|
|
|
}
|
2016-10-03 22:23:50 +00:00
|
|
|
]
|
|
|
|
}
|
2016-04-14 23:47:24 +00:00
|
|
|
```
|
2016-06-03 21:35:43 +00:00
|
|
|
|
|
|
|
#### S3 examples
|
|
|
|
|
|
|
|
S3 has several different types of addressing and more detail can be found
|
|
|
|
[here](http://docs.aws.amazon.com/AmazonS3/latest/dev/UsingBucket.html#access-bucket-intro)
|
|
|
|
|
|
|
|
S3 region specific endpoints can be found
|
|
|
|
[here](http://docs.aws.amazon.com/general/latest/gr/rande.html#s3_region)
|
|
|
|
|
|
|
|
Path based style:
|
2016-10-03 22:23:50 +00:00
|
|
|
|
|
|
|
```json
|
|
|
|
{
|
|
|
|
"Artifacts": [
|
|
|
|
{
|
2020-02-06 23:45:31 +00:00
|
|
|
"GetterSource": "https://my-bucket-example.s3-us-west-2.amazonaws.com/my_app.tar.gz"
|
2016-10-03 22:23:50 +00:00
|
|
|
}
|
|
|
|
]
|
|
|
|
}
|
2016-06-03 21:35:43 +00:00
|
|
|
```
|
|
|
|
|
2016-07-18 14:24:30 +00:00
|
|
|
or to override automatic detection in the URL, use the S3-specific syntax
|
2016-10-03 22:23:50 +00:00
|
|
|
|
|
|
|
```json
|
|
|
|
{
|
|
|
|
"Artifacts": [
|
|
|
|
{
|
2020-02-06 23:45:31 +00:00
|
|
|
"GetterSource": "s3::https://my-bucket-example.s3-eu-west-1.amazonaws.com/my_app.tar.gz"
|
2016-10-03 22:23:50 +00:00
|
|
|
}
|
|
|
|
]
|
|
|
|
}
|
2016-06-03 21:35:43 +00:00
|
|
|
```
|
|
|
|
|
|
|
|
Virtual hosted based style
|
2016-10-03 22:23:50 +00:00
|
|
|
|
|
|
|
```json
|
|
|
|
{
|
|
|
|
"Artifacts": [
|
|
|
|
{
|
2020-02-06 23:45:31 +00:00
|
|
|
"GetterSource": "my-bucket-example.s3-eu-west-1.amazonaws.com/my_app.tar.gz"
|
2016-10-03 22:23:50 +00:00
|
|
|
}
|
|
|
|
]
|
|
|
|
}
|
2016-06-03 21:35:43 +00:00
|
|
|
```
|
2017-01-24 13:46:17 +00:00
|
|
|
|
|
|
|
### Template
|
|
|
|
|
2017-01-24 17:12:42 +00:00
|
|
|
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.
|
|
|
|
|
|
|
|
Nomad utilizes a tool called [Consul Template][ct]. Since Nomad v0.5.3, the
|
|
|
|
template can reference [Nomad's runtime environment variables][env]. For a full
|
|
|
|
list of the API template functions, please refer to the [Consul Template
|
|
|
|
README][ct].
|
|
|
|
|
2017-01-24 13:46:17 +00:00
|
|
|
`Template` object supports following attributes:
|
|
|
|
|
2017-01-24 17:12:42 +00:00
|
|
|
- `ChangeMode` - Specifies the behavior Nomad should take if the rendered
|
|
|
|
template changes. The default value is `"restart"`. The possible values are:
|
2017-01-24 13:46:17 +00:00
|
|
|
|
2017-01-24 17:12:42 +00:00
|
|
|
- `"noop"` - take no action (continue running the task)
|
|
|
|
- `"restart"` - restart the task
|
|
|
|
- `"signal"` - send a configurable signal to the task
|
2022-08-24 15:43:01 +00:00
|
|
|
- `"script"` - run a script
|
2017-01-24 13:46:17 +00:00
|
|
|
|
2017-05-26 23:15:35 +00:00
|
|
|
- `ChangeSignal` - Specifies the signal to send to the task as a string like
|
2017-01-24 17:12:42 +00:00
|
|
|
"SIGUSR1" or "SIGINT". This option is required if the `ChangeMode` is
|
|
|
|
`signal`.
|
2017-01-24 13:46:17 +00:00
|
|
|
|
2022-08-24 15:43:01 +00:00
|
|
|
- `ChangeScript` - Configures the script triggered on template change. This
|
|
|
|
option is required if the `ChangeMode` is `script`.
|
|
|
|
|
|
|
|
The `ChangeScript` object supports the following attributes:
|
|
|
|
|
|
|
|
- `Command` - Specifies the full path to a script or executable that is to be
|
|
|
|
executed on template change. Path is relative to the driver, e.g., if running
|
|
|
|
with a container driver the path must be existing in the container. This
|
|
|
|
option is required is the `change_mode` is `script`.
|
2023-01-30 14:48:43 +00:00
|
|
|
|
2022-08-24 15:43:01 +00:00
|
|
|
- `Args` - List of arguments that are passed to the script that is to be
|
2023-01-30 14:48:43 +00:00
|
|
|
executed on template change.
|
|
|
|
|
2022-08-24 15:43:01 +00:00
|
|
|
- `Timeout` - Timeout for script execution specified using a label suffix like
|
|
|
|
"30s" or "1h". Default value is `"5s"`.
|
2023-01-30 14:48:43 +00:00
|
|
|
|
2022-08-24 15:43:01 +00:00
|
|
|
- `FailOnError` - If `true`, Nomad will kill the task if the script execution
|
|
|
|
fails. If `false`, script failure will be logged but the task will continue
|
|
|
|
uninterrupted. Default value is `false`.
|
|
|
|
|
2017-05-26 23:15:35 +00:00
|
|
|
- `DestPath` - Specifies the location where the resulting template should be
|
2017-02-21 00:43:28 +00:00
|
|
|
rendered, relative to the task directory.
|
|
|
|
|
2020-02-06 23:45:31 +00:00
|
|
|
- `EmbeddedTmpl` - Specifies the raw template to execute. One of `SourcePath`
|
2017-02-21 00:43:28 +00:00
|
|
|
or `EmbeddedTmpl` must be specified, but not both. This is useful for smaller
|
|
|
|
templates, but we recommend using `SourcePath` for larger templates.
|
|
|
|
|
2017-07-26 00:18:15 +00:00
|
|
|
- `Envvars` - Specifies the template should be read back as environment
|
|
|
|
variables for the task.
|
|
|
|
|
2017-05-26 23:15:35 +00:00
|
|
|
- `LeftDelim` - Specifies the left delimiter to use in the template. The default
|
2017-02-21 00:43:28 +00:00
|
|
|
is "{{" for some templates, it may be easier to use a different delimiter that
|
|
|
|
does not conflict with the output file itself.
|
|
|
|
|
2017-05-26 23:15:35 +00:00
|
|
|
- `Perms` - Specifies the rendered template's permissions. File permissions are
|
2018-04-12 18:34:01 +00:00
|
|
|
given as octal of the Unix file permissions `rwxrwxrwx`.
|
2017-02-13 18:18:34 +00:00
|
|
|
|
2022-08-02 20:15:38 +00:00
|
|
|
- `Uid` - Specifies the rendered template owner's user ID.
|
2023-01-30 14:48:43 +00:00
|
|
|
|
2022-08-02 20:15:38 +00:00
|
|
|
~> **Caveat:** Works only on Unix-based systems. Be careful when using
|
2022-08-24 15:43:01 +00:00
|
|
|
containerized drivers, such as `docker` or `podman`, as groups and users
|
2022-08-02 20:15:38 +00:00
|
|
|
inside the container may have different IDs than on the host system. This
|
2023-01-30 14:48:43 +00:00
|
|
|
feature will also **not** work with Docker Desktop.
|
2022-08-02 20:15:38 +00:00
|
|
|
|
|
|
|
- `Gid` - Specifies the rendered template owner's group ID.
|
2023-01-30 14:48:43 +00:00
|
|
|
|
2022-08-02 20:15:38 +00:00
|
|
|
~> **Caveat:** Works only on Unix-based systems. Be careful when using
|
2022-08-24 15:43:01 +00:00
|
|
|
containerized drivers, such as `docker` or `podman`, as groups and users
|
2022-08-02 20:15:38 +00:00
|
|
|
inside the container may have different IDs than on the host system. This
|
2023-01-30 14:48:43 +00:00
|
|
|
feature will also **not** work with Docker Desktop.
|
2022-08-02 20:15:38 +00:00
|
|
|
|
2017-05-26 23:15:35 +00:00
|
|
|
- `RightDelim` - Specifies the right delimiter to use in the template. The default
|
2017-02-21 00:43:28 +00:00
|
|
|
is "}}" for some templates, it may be easier to use a different delimiter that
|
|
|
|
does not conflict with the output file itself.
|
|
|
|
|
2017-05-26 23:15:35 +00:00
|
|
|
- `SourcePath` - Specifies the path to the template to be rendered. `SourcePath`
|
2017-02-21 00:43:28 +00:00
|
|
|
is mutually exclusive with `EmbeddedTmpl` attribute. The source can be fetched
|
|
|
|
using an [`Artifact`](#artifact) resource. The 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.
|
|
|
|
|
2017-07-17 18:41:50 +00:00
|
|
|
- `Splay` - Specifies a random amount of time to wait between 0 ms and the given
|
2017-01-24 17:12:42 +00:00
|
|
|
splay value before invoking the change mode. Should be specified in
|
|
|
|
nanoseconds.
|
2017-01-24 13:46:17 +00:00
|
|
|
|
2020-02-17 17:39:47 +00:00
|
|
|
- `VaultGrace` - [Deprecated](https://github.com/hashicorp/consul-template/issues/1268)
|
2017-01-24 13:46:17 +00:00
|
|
|
|
|
|
|
```json
|
|
|
|
{
|
|
|
|
"Templates": [
|
|
|
|
{
|
|
|
|
"SourcePath": "local/config.conf.tpl",
|
|
|
|
"DestPath": "local/config.conf",
|
2017-01-24 17:12:42 +00:00
|
|
|
"EmbeddedTmpl": "",
|
2017-01-24 13:46:17 +00:00
|
|
|
"ChangeMode": "signal",
|
|
|
|
"ChangeSignal": "SIGUSR1",
|
|
|
|
"Splay": 5000000000
|
|
|
|
}
|
|
|
|
]
|
|
|
|
}
|
2017-01-24 17:12:42 +00:00
|
|
|
```
|
|
|
|
|
2019-01-04 03:59:23 +00:00
|
|
|
### Spread
|
|
|
|
|
|
|
|
Spread allow operators to target specific percentages of allocations based on
|
|
|
|
any node attribute or metadata. More details on how they work are described
|
2023-01-25 17:31:14 +00:00
|
|
|
in [spread](/nomad/docs/job-specification/spread).
|
2019-01-04 03:59:23 +00:00
|
|
|
|
|
|
|
The `Spread` object supports the following keys:
|
|
|
|
|
|
|
|
- `Attribute` - Specifies the attribute to examine for the
|
2023-01-25 17:31:14 +00:00
|
|
|
spread. See the [table of attributes](/nomad/docs/runtime/interpolation#interpreted_node_vars) for examples.
|
2019-01-04 03:59:23 +00:00
|
|
|
|
|
|
|
- `SpreadTarget` - Specifies a list of attribute values and percentages. This is an optional field, when
|
|
|
|
left empty Nomad will evenly spread allocations across values of the attribute.
|
|
|
|
|
2020-02-06 23:45:31 +00:00
|
|
|
- `Value` - The value of a specific target attribute, like "dc1" for `${node.datacenter}`.
|
|
|
|
- `Percent` - Desired percentage of allocations for this attribute value. The sum of
|
|
|
|
all spread target percentages must add up to 100.
|
2019-01-04 03:59:23 +00:00
|
|
|
|
2020-02-06 23:45:31 +00:00
|
|
|
- `Weight` - A non zero weight, valid values are from -100 to 100. Used to express
|
|
|
|
relative preference when there is more than one spread or affinity.
|
2019-01-04 03:59:23 +00:00
|
|
|
|
2020-04-13 21:33:49 +00:00
|
|
|
<a id="scaling_policy"></a>
|
|
|
|
|
|
|
|
### Scaling
|
|
|
|
|
|
|
|
Scaling policies allow operators to attach autoscaling configuration to a task group. This information
|
|
|
|
can be queried by [external autoscalers](https://github.com/hashicorp/nomad-autoscaler).
|
|
|
|
|
|
|
|
The `Scaling` object supports the following keys:
|
|
|
|
|
|
|
|
- `Min` - The minimum allowable count for the task group. This is optional; if absent, the default
|
|
|
|
is the `Count` specified in the task group. Attempts to set the task group `Count` below `Min` will
|
|
|
|
result in a 400 error during job registration.
|
|
|
|
|
|
|
|
- `Max` - The maximum allowable count for the task group. This is required if a scaling policy is provided.
|
2020-05-01 20:02:21 +00:00
|
|
|
This must be larger than `Min`. Attempts to set the task group `Count` above `Max` wil result in a 400
|
|
|
|
error during job registration.
|
2020-04-13 21:33:49 +00:00
|
|
|
|
|
|
|
- `Enabled` - An optional boolean (default: `true`). This indicates to the autoscaler that this
|
2020-05-01 20:02:21 +00:00
|
|
|
scaling policy should be ignored. It is intended to allow autoscaling to be temporarily disabled
|
|
|
|
for a task group.
|
2020-04-13 21:33:49 +00:00
|
|
|
|
|
|
|
- `Policy` - An optional JSON block. This is opaque to Nomad; see the documentation for the external
|
2020-05-01 20:02:21 +00:00
|
|
|
autoscaler (e.g., [nomad-autoscaler](https://github.com/hashicorp/nomad-autoscaler)).
|
2020-04-13 21:33:49 +00:00
|
|
|
|
2020-02-06 23:45:31 +00:00
|
|
|
[ct]: https://github.com/hashicorp/consul-template 'Consul Template by HashiCorp'
|
2023-01-25 17:31:14 +00:00
|
|
|
[drain]: /nomad/docs/commands/node/drain
|
|
|
|
[env]: /nomad/docs/runtime/environment 'Nomad Runtime Environment'
|
2023-02-02 18:59:14 +00:00
|
|
|
[Workload Identity]: /nomad/docs/concepts/workload-identity 'Nomad Workload Identity'
|