2017-05-26 23:15:28 +00:00
---
layout: api
page_title: Jobs - HTTP API
2020-02-06 23:45:31 +00:00
description: The /jobs endpoints are used to query for and interact with jobs.
2017-05-26 23:15:28 +00:00
---
# Jobs HTTP API
The `/jobs` endpoints are used to query for and interact with jobs.
## List Jobs
This endpoint lists all known jobs in the system registered with Nomad.
2020-02-06 23:45:31 +00:00
| Method | Path | Produces |
| ------ | ---------- | ------------------ |
| `GET` | `/v1/jobs` | `application/json` |
2017-05-26 23:15:28 +00:00
The table below shows this endpoint's support for
2023-01-25 17:31:14 +00:00
[blocking queries](/nomad/api-docs#blocking-queries) and
[required ACLs](/nomad/api-docs#acls).
2017-05-26 23:15:28 +00:00
2020-02-06 23:45:31 +00:00
| Blocking Queries | ACL Required |
| ---------------- | --------------------- |
| `YES` | `namespace:list-jobs` |
2017-05-26 23:15:28 +00:00
### Parameters
2017-07-06 20:21:56 +00:00
- `prefix` `(string: "")` - Specifies a string to filter jobs on based on
2019-05-08 19:14:31 +00:00
an index prefix. This is specified as a query string parameter.
2017-05-26 23:15:28 +00:00
2022-03-14 14:58:42 +00:00
- `next_token` `(string: "")` - This endpoint supports paging. The `next_token`
parameter accepts a string which identifies the next expected job. This value
can be obtained from the `X-Nomad-NextToken` header from the previous
response.
- `per_page` `(int: 0)` - Specifies a maximum number of jobs to return for this
request. If omitted, the response is not paginated. The value of the
`X-Nomad-NextToken` header of the last response can be used as the
`next_token` of the next request to fetch additional pages.
2023-01-25 17:31:14 +00:00
- `filter` `(string: "")` - Specifies the [expression](/nomad/api-docs#filtering)
2022-03-14 14:58:42 +00:00
used to filter the results. Consider using pagination or a query parameter to
reduce resource used to serve the request.
2020-07-01 19:15:01 +00:00
- `namespace` `(string: "default")` - Specifies the target namespace. Specifying
`*` would return all jobs across all the authorized namespaces.
2023-01-25 17:31:14 +00:00
- `meta` `(bool: false)` - If set, jobs returned will include a [meta](/nomad/docs/job-specification/meta) field containing key-value pairs provided in the job specification's `meta` block.
2022-11-02 20:58:24 +00:00
2017-05-26 23:15:28 +00:00
### Sample Request
2020-05-18 20:53:06 +00:00
```shell-session
$ curl https://localhost:4646/v1/jobs
2017-05-26 23:15:28 +00:00
```
2020-05-18 20:53:06 +00:00
```shell-session
$ curl https://localhost:4646/v1/jobs?prefix=team
2017-05-26 23:15:28 +00:00
```
2020-07-01 19:15:01 +00:00
```shell-session
$ curl https://localhost:4646/v1/jobs?namespace=*&prefix=team
```
2017-05-26 23:15:28 +00:00
### Sample Response
```json
[
{
"ID": "example",
"ParentID": "",
"Name": "example",
"Type": "service",
"Priority": 50,
"Status": "pending",
"StatusDescription": "",
"JobSummary": {
"JobID": "example",
2020-05-19 14:06:43 +00:00
"Namespace": "default",
2017-05-26 23:15:28 +00:00
"Summary": {
"cache": {
"Queued": 1,
"Complete": 1,
"Failed": 0,
"Running": 0,
"Starting": 0,
"Lost": 0
}
},
"Children": {
"Pending": 0,
"Running": 0,
"Dead": 0
},
"CreateIndex": 52,
"ModifyIndex": 96
},
"CreateIndex": 52,
"ModifyIndex": 93,
"JobModifyIndex": 52
}
]
```
## Create Job
This endpoint creates (aka "registers") a new job in the system.
2020-02-06 23:45:31 +00:00
| Method | Path | Produces |
| ------ | ---------- | ------------------ |
| `POST` | `/v1/jobs` | `application/json` |
2017-05-26 23:15:28 +00:00
The table below shows this endpoint's support for
2023-01-25 17:31:14 +00:00
[blocking queries](/nomad/api-docs#blocking-queries) and
[required ACLs](/nomad/api-docs#acls).
2017-05-26 23:15:28 +00:00
2020-02-06 23:45:31 +00:00
| Blocking Queries | ACL Required |
| ---------------- | --------------------------------------------------------------------------------- |
| `NO` | `namespace:submit-job`<br />`namespace:sentinel-override` if `PolicyOverride` set |
2017-05-26 23:15:28 +00:00
### Parameters
2017-09-19 14:47:10 +00:00
- `Job` `(Job: <required>)` - Specifies the JSON definition of the job.
2023-04-11 13:45:08 +00:00
- `Submission` `(JobSubmission: <optional>)` - Specifies the original HCL/HCL2/JSON
definition of the job. This data is useful for reference only, it is not considered
for the actual scheduling of `Job`.
2017-09-19 14:47:10 +00:00
- `EnforceIndex` `(bool: false)` - If set, the job will only be registered if the
passed `JobModifyIndex` matches the current job's index. If the index is zero,
the register only occurs if the job is new. This paradigm allows check-and-set
style job updating.
2021-11-23 08:23:31 +00:00
- `EvalPriority` `(int: 0)` - Override the priority of the evaluations produced
as a result of this job registration. By default, this is set to the priority
of the job.
2017-09-19 14:47:10 +00:00
- `JobModifyIndex` `(int: 0)` - Specifies the `JobModifyIndex` to enforce the
current job is at.
2021-01-05 18:41:38 +00:00
- `PolicyOverride` `(bool: false)` - If set, any soft mandatory Sentinel
policies will be overridden. This allows a job to be registered when it would
be denied by policy.
2020-12-18 19:54:39 +00:00
- `PreserveCounts` `(bool: false)` - If set, existing task group counts are
preserved, over those specified in the new job spec.
2017-05-26 23:15:28 +00:00
### Sample Payload
2017-07-29 01:04:30 +00:00
```json
{
2020-02-06 23:45:31 +00:00
"Job": {
2021-03-31 13:43:17 +00:00
"Datacenters": ["dc1"],
2021-03-08 18:06:28 +00:00
"ID": "cache",
2020-02-06 23:45:31 +00:00
"TaskGroups": [
{
"Name": "cache",
2021-03-08 18:06:28 +00:00
"Networks": [
{
"DynamicPorts": [
{
"Label": "db",
"To": 6379
}
]
}
],
"Services": [
{
"Name": "redis-cache",
"PortLabel": "db"
}
],
2020-02-06 23:45:31 +00:00
"Tasks": [
{
"Config": {
2022-05-17 15:24:19 +00:00
"image": "redis:7",
2021-03-31 13:43:17 +00:00
"ports": ["db"]
2020-02-06 23:45:31 +00:00
},
2021-03-08 18:06:28 +00:00
"Driver": "docker",
"Name": "redis"
2020-02-06 23:45:31 +00:00
}
2021-03-08 18:06:28 +00:00
]
2020-02-06 23:45:31 +00:00
}
2021-03-08 18:06:28 +00:00
]
2020-02-06 23:45:31 +00:00
}
2017-07-29 01:04:30 +00:00
}
2017-05-26 23:15:28 +00:00
```
### Sample Request
2020-05-18 20:53:06 +00:00
```shell-session
$ curl \
2017-05-26 23:15:28 +00:00
--request POST \
2019-08-15 18:06:21 +00:00
--data @payload.json \
2018-01-29 16:27:52 +00:00
https://localhost:4646/v1/jobs
2017-05-26 23:15:28 +00:00
```
### Sample Response
```json
{
"EvalID": "",
"EvalCreateIndex": 0,
"JobModifyIndex": 109,
2017-07-26 00:18:15 +00:00
"Warnings": "",
2017-05-26 23:15:28 +00:00
"Index": 0,
"LastContact": 0,
"KnownLeader": false
}
```
2018-04-12 19:35:39 +00:00
## Parse Job
2018-04-17 14:18:36 +00:00
This endpoint will parse a HCL jobspec and produce the equivalent JSON encoded
2018-04-12 19:35:39 +00:00
job.
2020-02-06 23:45:31 +00:00
| Method | Path | Produces |
| ------ | ---------------- | ------------------ |
| `POST` | `/v1/jobs/parse` | `application/json` |
2018-04-12 19:35:39 +00:00
2018-04-16 23:19:02 +00:00
The table below shows this endpoint's support for
2023-01-25 17:31:14 +00:00
[blocking queries](/nomad/api-docs#blocking-queries) and
[required ACLs](/nomad/api-docs#acls).
2018-04-16 23:19:02 +00:00
2022-02-10 20:35:16 +00:00
| Blocking Queries | ACL Required |
| ---------------- | ------------------------------------------------- |
| `NO` | `namespace:parse-job`<br />`namespace:submit-job` |
2018-04-16 23:19:02 +00:00
2018-04-12 19:35:39 +00:00
### Parameters
2022-03-10 21:35:07 +00:00
- `namespace` `(string: "default")` - Specifies the target namespace. If ACL is
enabled, this value must match a namespace that the token is allowed to
access. This is specified as a query string parameter.
2018-04-12 19:35:39 +00:00
- `JobHCL` `(string: <required>)` - Specifies the HCL definition of the job
encoded in a JSON string.
2022-03-10 21:35:07 +00:00
2018-04-12 19:35:39 +00:00
- `Canonicalize` `(bool: false)` - Flag to enable setting any unset fields to
their default values.
2023-04-11 13:45:08 +00:00
- `Variables` `(string: "")` - Specifies HCL2 variables to use during parsing of
the job in the var file format.
- `VariableFlags` `(map[string]string: nil)` - Specifies HCL2 variables to use
during parsing of the job in key = value format.
2022-11-25 17:46:53 +00:00
- `HCLv1` `(bool: false)` - Use the legacy v1 HCL parser.
2023-03-16 16:42:46 +00:00
### Sample Payload
2018-04-12 19:35:39 +00:00
```json
{
2022-11-25 17:46:53 +00:00
"JobHCL": "job \"example\" {\n type = \"service\"\n group \"cache\" {}\n}",
2020-02-06 23:45:31 +00:00
"Canonicalize": true
2018-04-12 19:35:39 +00:00
}
```
2022-11-25 17:46:53 +00:00
You can use a tool such as [`jq`](https://stedolan.github.io/jq/) to generate
the payload from a local HCL file:
```shell-session
2023-02-02 17:47:47 +00:00
$ jq -Rsc '{ JobHCL: ., Canonicalize: true }' example.nomad.hcl > payload.json
2022-11-25 17:46:53 +00:00
```
2018-04-12 19:35:39 +00:00
### Sample Request
2020-05-18 20:53:06 +00:00
```shell-session
$ curl \
2018-04-12 19:35:39 +00:00
--request POST \
2019-08-15 18:06:21 +00:00
--data @payload.json \
2018-04-12 19:35:39 +00:00
https://localhost:4646/v1/jobs/parse
```
### Sample Response
```json
{
2020-02-06 23:45:31 +00:00
"AllAtOnce": false,
"Constraints": null,
"Affinities": null,
"CreateIndex": 0,
"Datacenters": null,
"ID": "my-job",
"JobModifyIndex": 0,
"Meta": null,
"Migrate": null,
"ModifyIndex": 0,
"Name": "my-job",
"Namespace": "default",
"ParameterizedJob": null,
"ParentID": "",
"Payload": null,
"Periodic": null,
"Priority": 50,
"Region": "global",
"Reschedule": null,
"Stable": false,
"Status": "",
"StatusDescription": "",
"Stop": false,
"SubmitTime": null,
"TaskGroups": null,
"Type": "service",
"Update": null,
"VaultToken": "",
"Version": 0
2018-04-12 19:35:39 +00:00
}
```
2017-05-26 23:15:28 +00:00
## Read Job
This endpoint reads information about a single job for its specification and
status.
2020-02-06 23:45:31 +00:00
| Method | Path | Produces |
| ------ | ----------------- | ------------------ |
| `GET` | `/v1/job/:job_id` | `application/json` |
2017-05-26 23:15:28 +00:00
The table below shows this endpoint's support for
2023-01-25 17:31:14 +00:00
[blocking queries](/nomad/api-docs#blocking-queries) and
[required ACLs](/nomad/api-docs#acls).
2017-05-26 23:15:28 +00:00
2020-02-06 23:45:31 +00:00
| Blocking Queries | ACL Required |
| ---------------- | -------------------- |
| `YES` | `namespace:read-job` |
2017-05-26 23:15:28 +00:00
### Parameters
2017-07-06 20:21:56 +00:00
- `:job_id` `(string: <required>)` - Specifies the ID of the job (as specified in
2017-05-26 23:15:28 +00:00
the job file during submission). This is specified as part of the path.
2021-03-24 13:31:39 +00:00
- `namespace` `(string: "default")` - Specifies the namespace of the job. If not specified,
defaults to "default". This is specified as a URL query parameter.
2017-05-26 23:15:28 +00:00
### Sample Request
2020-05-18 20:53:06 +00:00
```shell-session
$ curl \
2018-01-29 16:27:52 +00:00
https://localhost:4646/v1/job/my-job
2017-05-26 23:15:28 +00:00
```
2021-03-24 13:31:39 +00:00
```shell-session
$ curl \
https://localhost:4646/v1/job/my-job?namespace=apps
```
2017-05-26 23:15:28 +00:00
### Sample Response
```json
{
"Region": "global",
2021-03-24 13:31:39 +00:00
"Namespace": "apps",
2017-05-26 23:15:28 +00:00
"ID": "example",
"ParentID": "",
"Name": "example",
"Type": "batch",
"Priority": 50,
"AllAtOnce": false,
2020-02-06 23:45:31 +00:00
"Datacenters": ["dc1"],
2017-05-26 23:15:28 +00:00
"Constraints": [
{
"LTarget": "${attr.kernel.name}",
"RTarget": "linux",
"Operand": "="
}
],
"TaskGroups": [
{
"Name": "cache",
"Count": 1,
"Constraints": [
{
"LTarget": "${attr.os.signals}",
"RTarget": "SIGUSR1",
"Operand": "set_contains"
}
],
2018-11-05 22:41:20 +00:00
"Affinities": [
2020-02-06 23:45:31 +00:00
{
2018-11-05 22:41:20 +00:00
"LTarget": "${meta.datacenter}",
"RTarget": "dc1",
"Operand": "=",
2020-02-06 23:45:31 +00:00
"Weight": 50
}
],
2017-05-26 23:15:28 +00:00
"RestartPolicy": {
"Attempts": 10,
"Interval": 300000000000,
"Delay": 25000000000,
"Mode": "delay"
},
"Tasks": [
2020-12-18 22:26:30 +00:00
{
"Config": {
"command": "env",
"image": "alpine"
},
"Driver": "docker",
"Lifecycle": {
"Hook": "prestart",
"Sidecar": false
},
"Name": "init",
"Resources": {
"CPU": 100,
2021-03-31 13:43:17 +00:00
"MemoryMB": 300
}
2020-12-18 22:26:30 +00:00
},
2017-05-26 23:15:28 +00:00
{
"Name": "redis",
"Driver": "docker",
"User": "foo-user",
"Config": {
"image": "redis:latest",
"port_map": [
{
"db": 6379
}
]
},
"Env": {
"foo": "bar",
"baz": "pipe"
},
"Services": [
{
"Name": "cache-redis",
"PortLabel": "db",
2020-02-06 23:45:31 +00:00
"Tags": ["global", "cache"],
2017-05-26 23:15:28 +00:00
"Checks": [
{
"Name": "alive",
"Type": "tcp",
"Command": "",
"Args": null,
"Path": "",
"Protocol": "",
"PortLabel": "",
"Interval": 10000000000,
"Timeout": 2000000000,
"InitialStatus": ""
}
]
}
],
"Vault": null,
"Templates": [
{
"SourcePath": "local/config.conf.tpl",
"DestPath": "local/config.conf",
"EmbeddedTmpl": "",
"ChangeMode": "signal",
"ChangeSignal": "SIGUSR1",
"Splay": 5000000000,
"Perms": ""
}
],
"Constraints": null,
2020-02-06 23:45:31 +00:00
"Affinities": null,
2017-05-26 23:15:28 +00:00
"Resources": {
"CPU": 500,
"MemoryMB": 256,
"DiskMB": 0,
"Networks": [
{
"Device": "",
"CIDR": "",
"IP": "",
"MBits": 10,
"ReservedPorts": [
{
"Label": "rpc",
"Value": 25566
}
],
"DynamicPorts": [
{
"Label": "db",
"Value": 0
}
]
}
]
},
"DispatchPayload": {
"File": "config.json"
},
"Meta": {
"foo": "bar",
"baz": "pipe"
},
"KillTimeout": 5000000000,
"LogConfig": {
2023-04-24 14:00:27 +00:00
"Enabled": true,
2017-05-26 23:15:28 +00:00
"MaxFiles": 10,
"MaxFileSizeMB": 10
},
"Artifacts": [
{
"GetterSource": "http://foo.com/artifact.tar.gz",
"GetterOptions": {
"checksum": "md5:c4aa853ad2215426eb7d70a21922e794"
},
"RelativeDest": "local/"
}
],
"Leader": false
}
],
"EphemeralDisk": {
"Sticky": false,
"SizeMB": 300,
"Migrate": false
},
"Meta": {
"foo": "bar",
"baz": "pipe"
}
}
],
"Update": {
"Stagger": 10000000000,
"MaxParallel": 1
},
"Periodic": {
"Enabled": true,
"Spec": "* * * * *",
"SpecType": "cron",
"ProhibitOverlap": true
},
"ParameterizedJob": {
"Payload": "required",
2020-02-06 23:45:31 +00:00
"MetaRequired": ["foo"],
"MetaOptional": ["bar"]
2017-05-26 23:15:28 +00:00
},
"Payload": null,
"Meta": {
"foo": "bar",
"baz": "pipe"
},
"VaultToken": "",
"Status": "running",
"StatusDescription": "",
"CreateIndex": 7,
"ModifyIndex": 7,
"JobModifyIndex": 7
}
```
2020-12-18 20:14:50 +00:00
#### Field Reference
- `Status`: The job's current state. It can have one of the following values:
- `pending`: The job is currently waiting on scheduling.
- `running`: The job has non-terminal allocations.
- `dead`: All of the job's allocations and evaluations are terminal.
- `Type`: The type of job in terms of scheduling. It can have one of the following values:
- `service`: Allocations are intended to remain alive.
- `batch`: Allocations are intended to exit.
- `system`: Each client gets an allocation.
2023-04-11 13:45:08 +00:00
## Read Job Submission
This endpoint reads original source information about a specific version of a single
job. The data this endpoint provides is only available if it was provided with the
original job during job registration. Only the most recent 6 job source files are
retained.
| Method | Path | Produces |
| ------ | ------------------------------ | ------------------ |
|`GET` | `/v1/job/:job_id/submission` | `application/json` |
### Parameters
- `:job_id` `(string: <required>)` - Specifies the ID of the job. This is
specified as part of the path.
- `version` `(int: <required>)` - Specifies the version number of the job for which
to retrieve the original source information. This is specified as a query string
parameter.
- `namespace` `(string: "default")` - Specifies the target namespace. If ACL is
enabled, this value must match a namespace that the token is allowed to access.
This is specified as a query string parameter.
### Sample Request
```shell-session
nomad operator api /v1/job/my-job/submission?version=42
```
### Sample Response
```json
{
"Format": "hcl2",
"JobIndex": 11,
"JobID": "myjob",
"Namespace": "default",
"Source": "variable \"X\" {\n type = string\n}\n\nvariable \"Y\" {\n type = number\n}\n\nvariable \"Z\" {\n type = bool\n}\n \njob \"myjob\" {\n type = \"sysbatch\"\n \n meta {\n nomad_discard_job_source = false\n }\n\n group \"group\" {\n task \"task\" {\n driver = \"raw_exec\"\n\n config {\n command = \"echo\"\n args = [\"X ${var.X}, Y ${var.Y}, Z ${var.Z}\"]\n }\n\n resources {\n cpu = 10\n memory = 16\n }\n }\n }\n}\n",
"VariableFlags": {
"Z": "true",
"X": "x",
"Y": "2"
},
"Variables": "",
"Version": 0
}
```
#### Field Reference
- `JobID`: The ID of the job associated with the original job file.
- `Format`: The file format of the original job file. One of `hcl2`, `hcl1`, or `json`.
- `Source`: The literal content of the original job file.
- `VariableFlags`: The key-value pairs of HCL variables as submitted via `-var` command
line arguments when submitting the job via CLI.
- `Variables`: The content of the variables form when submitting the job via the WebUI.
- `Version`: The version of the job this submission source is associated with.
2017-05-26 23:15:28 +00:00
## List Job Versions
This endpoint reads information about all versions of a job.
2020-02-06 23:45:31 +00:00
| Method | Path | Produces |
| ------ | -------------------------- | ------------------ |
| `GET` | `/v1/job/:job_id/versions` | `application/json` |
2017-05-26 23:15:28 +00:00
The table below shows this endpoint's support for
2023-01-25 17:31:14 +00:00
[blocking queries](/nomad/api-docs#blocking-queries) and
[required ACLs](/nomad/api-docs#acls).
2017-05-26 23:15:28 +00:00
2020-02-06 23:45:31 +00:00
| Blocking Queries | ACL Required |
| ---------------- | -------------------- |
| `YES` | `namespace:read-job` |
2017-05-26 23:15:28 +00:00
### Parameters
2020-12-18 19:54:39 +00:00
- `diffs` `(bool: false)` - Specifies if the Diffs field should be populated,
containing the structured diff between the current and last job version.
2017-07-06 20:21:56 +00:00
- `:job_id` `(string: <required>)` - Specifies the ID of the job (as specified in
2017-05-26 23:15:28 +00:00
the job file during submission). This is specified as part of the path.
2023-02-22 16:28:32 +00:00
- `namespace` `(string: "default")` - Specifies the target namespace. If ACL is
enabled, this value must match a namespace that the token is allowed to
access. This is specified as a query string parameter.
2017-05-26 23:15:28 +00:00
### Sample Request
2020-05-18 20:53:06 +00:00
```shell-session
$ curl \
2018-01-29 16:27:52 +00:00
https://localhost:4646/v1/job/my-job/versions
2017-05-26 23:15:28 +00:00
```
### Sample Response
```json
2020-12-18 19:54:39 +00:00
{
"Diffs": null,
"Index": 51,
"KnownLeader": true,
"LastContact": 0,
"Versions": [
{
"Affinities": null,
"AllAtOnce": false,
"Constraints": null,
"ConsulToken": "",
"CreateIndex": 44,
2020-12-18 20:14:50 +00:00
"Datacenters": ["dc1"],
2020-12-18 19:54:39 +00:00
"Dispatched": false,
"ID": "example",
"JobModifyIndex": 44,
"Meta": null,
"ModifyIndex": 51,
"Multiregion": null,
"Name": "example",
"Namespace": "default",
"NomadTokenID": "",
"ParameterizedJob": null,
"ParentID": "",
"Payload": null,
"Periodic": null,
"Priority": 50,
"Region": "global",
"Spreads": null,
"Stable": true,
"Status": "running",
"StatusDescription": "",
"Stop": false,
"SubmitTime": 1608304897537638400,
"TaskGroups": [
{
"Affinities": null,
"Constraints": null,
"Count": 1,
"EphemeralDisk": {
"Migrate": false,
"SizeMB": 300,
"Sticky": false
},
2022-03-04 16:28:47 +00:00
"MaxClientDisconnect": 300000000000,
2020-12-18 19:54:39 +00:00
"Meta": null,
"Migrate": {
"HealthCheck": "checks",
"HealthyDeadline": 300000000000,
"MaxParallel": 1,
"MinHealthyTime": 10000000000
},
"Name": "cache",
"Networks": [
{
"CIDR": "",
"DNS": null,
"Device": "",
"DynamicPorts": [
2017-05-26 23:15:28 +00:00
{
2020-12-18 19:54:39 +00:00
"HostNetwork": "default",
"Label": "db",
"To": 6379,
"Value": 0
2017-05-26 23:15:28 +00:00
}
2020-12-18 19:54:39 +00:00
],
"IP": "",
"MBits": 0,
"Mode": "",
"ReservedPorts": null
}
],
"ReschedulePolicy": {
"Attempts": 0,
"Delay": 30000000000,
"DelayFunction": "exponential",
"Interval": 0,
"MaxDelay": 3600000000000,
"Unlimited": true
},
"RestartPolicy": {
"Attempts": 2,
"Delay": 15000000000,
"Interval": 1800000000000,
"Mode": "fail"
},
"Scaling": null,
"Services": null,
"ShutdownDelay": null,
"Spreads": null,
"StopAfterClientDisconnect": null,
"Tasks": [
{
"Affinities": null,
"Artifacts": null,
"CSIPluginConfig": null,
"Config": {
2022-05-17 15:24:19 +00:00
"image": "redis:7",
2020-12-18 20:14:50 +00:00
"ports": ["db"]
2020-12-18 19:54:39 +00:00
},
"Constraints": null,
"DispatchPayload": null,
"Driver": "docker",
"Env": null,
"KillSignal": "",
"KillTimeout": 5000000000,
"Kind": "",
"Leader": false,
"Lifecycle": null,
"LogConfig": {
2023-04-24 14:00:27 +00:00
"Enabled": true,
2020-12-18 19:54:39 +00:00
"MaxFileSizeMB": 10,
"MaxFiles": 10
},
"Meta": null,
"Name": "redis",
"Resources": {
"CPU": 500,
"Devices": null,
"DiskMB": 0,
"IOPS": 0,
"MemoryMB": 256,
"Networks": null
},
"RestartPolicy": {
"Attempts": 2,
"Delay": 15000000000,
"Interval": 1800000000000,
"Mode": "fail"
},
"ScalingPolicies": null,
"Services": null,
"ShutdownDelay": 0,
"Templates": null,
"User": "",
"Vault": null,
"VolumeMounts": null
}
],
"Update": {
"AutoPromote": false,
"AutoRevert": false,
"Canary": 0,
"HealthCheck": "checks",
"HealthyDeadline": 300000000000,
"MaxParallel": 1,
"MinHealthyTime": 10000000000,
"ProgressDeadline": 600000000000,
"Stagger": 30000000000
},
"Volumes": null
}
],
"Type": "service",
"Update": {
"AutoPromote": false,
"AutoRevert": false,
"Canary": 0,
"HealthCheck": "",
"HealthyDeadline": 0,
"MaxParallel": 1,
"MinHealthyTime": 0,
"ProgressDeadline": 0,
"Stagger": 30000000000
},
"VaultNamespace": "",
"VaultToken": "",
"Version": 0
}
]
}
```
```shell-session
$ curl \
https://localhost:4646/v1/job/my-job/versions?diffs=true
```
2023-04-11 13:45:08 +00:00
```json
2020-12-18 19:54:39 +00:00
{
"Diffs": [
{
"Fields": null,
"ID": "example",
"Objects": null,
"TaskGroups": [
{
"Fields": null,
"Name": "cache",
"Objects": null,
"Tasks": [
{
"Annotations": null,
"Fields": [
2017-05-26 23:15:28 +00:00
{
2020-12-18 19:54:39 +00:00
"Annotations": null,
"Name": "Env[foo]",
"New": "bar",
"Old": "",
"Type": "Added"
2017-05-26 23:15:28 +00:00
}
2020-12-18 19:54:39 +00:00
],
"Name": "redis",
"Objects": null,
"Type": "Edited"
}
],
"Type": "Edited",
"Updates": null
}
],
"Type": "Edited"
}
],
"Index": 26,
"KnownLeader": true,
"LastContact": 0,
"Versions": [
{
"Affinities": null,
"AllAtOnce": false,
"Constraints": null,
"ConsulToken": "",
"CreateIndex": 10,
"Datacenters": [
"dc1"
],
"Dispatched": false,
"ID": "example",
"JobModifyIndex": 16,
"Meta": null,
"ModifyIndex": 26,
"Multiregion": null,
"Name": "example",
"Namespace": "default",
"NomadTokenID": "",
"ParameterizedJob": null,
"ParentID": "",
"Payload": null,
"Periodic": null,
"Priority": 50,
"Region": "global",
"Spreads": null,
"Stable": true,
"Status": "running",
"StatusDescription": "",
"Stop": false,
"SubmitTime": 1608316675000588800,
"TaskGroups": [
{
"Affinities": null,
"Constraints": null,
"Count": 1,
"EphemeralDisk": {
"Migrate": false,
"SizeMB": 300,
"Sticky": false
},
2022-03-04 16:28:47 +00:00
"MaxClientDisconnect": null,
2020-12-18 19:54:39 +00:00
"Meta": null,
"Migrate": {
"HealthCheck": "checks",
"HealthyDeadline": 300000000000,
"MaxParallel": 1,
"MinHealthyTime": 10000000000
},
"Name": "cache",
"Networks": [
{
"CIDR": "",
"DNS": null,
"Device": "",
"DynamicPorts": [
{
"HostNetwork": "default",
"Label": "db",
"To": 6379,
"Value": 0
}
],
"IP": "",
"MBits": 0,
"Mode": "",
"ReservedPorts": null
}
],
"ReschedulePolicy": {
"Attempts": 0,
"Delay": 30000000000,
"DelayFunction": "exponential",
"Interval": 0,
"MaxDelay": 3600000000000,
"Unlimited": true
},
"RestartPolicy": {
"Attempts": 2,
"Delay": 15000000000,
"Interval": 1800000000000,
"Mode": "fail"
},
"Scaling": null,
"Services": null,
"ShutdownDelay": null,
"Spreads": null,
"StopAfterClientDisconnect": null,
"Tasks": [
{
"Affinities": null,
"Artifacts": null,
"CSIPluginConfig": null,
"Config": {
2022-05-17 15:24:19 +00:00
"image": "redis:7",
2020-12-18 19:54:39 +00:00
"ports": [
"db"
]
},
"Constraints": null,
"DispatchPayload": null,
"Driver": "docker",
"Env": {
"foo": "bar"
},
"KillSignal": "",
"KillTimeout": 5000000000,
"Kind": "",
"Leader": false,
"Lifecycle": null,
"LogConfig": {
2023-04-24 14:00:27 +00:00
"Enabled": true,
2020-12-18 19:54:39 +00:00
"MaxFileSizeMB": 10,
"MaxFiles": 10
},
"Meta": null,
"Name": "redis",
"Resources": {
"CPU": 500,
"Devices": null,
"DiskMB": 0,
"IOPS": 0,
"MemoryMB": 256,
"Networks": null
},
"RestartPolicy": {
"Attempts": 2,
"Delay": 15000000000,
"Interval": 1800000000000,
"Mode": "fail"
},
"ScalingPolicies": null,
"Services": null,
"ShutdownDelay": 0,
"Templates": null,
"User": "",
"Vault": null,
"VolumeMounts": null
}
],
"Update": {
"AutoPromote": false,
"AutoRevert": false,
"Canary": 0,
"HealthCheck": "checks",
"HealthyDeadline": 300000000000,
"MaxParallel": 1,
"MinHealthyTime": 10000000000,
"ProgressDeadline": 600000000000,
"Stagger": 30000000000
},
"Volumes": null
}
],
"Type": "service",
"Update": {
"AutoPromote": false,
"AutoRevert": false,
"Canary": 0,
"HealthCheck": "",
"HealthyDeadline": 0,
"MaxParallel": 1,
"MinHealthyTime": 0,
"ProgressDeadline": 0,
"Stagger": 30000000000
},
"VaultNamespace": "",
"VaultToken": "",
"Version": 1
2017-05-26 23:15:28 +00:00
},
2020-12-18 19:54:39 +00:00
{
"Affinities": null,
"AllAtOnce": false,
"Constraints": null,
"ConsulToken": "",
"CreateIndex": 10,
"Datacenters": [
"dc1"
],
"Dispatched": false,
"ID": "example",
"JobModifyIndex": 10,
"Meta": null,
"ModifyIndex": 10,
"Multiregion": null,
"Name": "example",
"Namespace": "default",
"NomadTokenID": "",
"ParameterizedJob": null,
"ParentID": "",
"Payload": null,
"Periodic": null,
"Priority": 50,
"Region": "global",
"Spreads": null,
"Stable": false,
"Status": "pending",
"StatusDescription": "",
"Stop": false,
"SubmitTime": 1608316662268190500,
"TaskGroups": [
{
"Affinities": null,
"Constraints": null,
"Count": 1,
"EphemeralDisk": {
"Migrate": false,
"SizeMB": 300,
"Sticky": false
},
2022-03-04 16:28:47 +00:00
"MaxClientDisconnect": null,
2020-12-18 19:54:39 +00:00
"Meta": null,
"Migrate": {
"HealthCheck": "checks",
"HealthyDeadline": 300000000000,
"MaxParallel": 1,
"MinHealthyTime": 10000000000
},
"Name": "cache",
"Networks": [
{
"CIDR": "",
"DNS": null,
"Device": "",
"DynamicPorts": [
{
"HostNetwork": "default",
"Label": "db",
"To": 6379,
"Value": 0
}
],
"IP": "",
"MBits": 0,
"Mode": "",
"ReservedPorts": null
}
],
"ReschedulePolicy": {
"Attempts": 0,
"Delay": 30000000000,
"DelayFunction": "exponential",
"Interval": 0,
"MaxDelay": 3600000000000,
"Unlimited": true
},
"RestartPolicy": {
"Attempts": 2,
"Delay": 15000000000,
"Interval": 1800000000000,
"Mode": "fail"
},
"Scaling": null,
"Services": null,
"ShutdownDelay": null,
"Spreads": null,
"StopAfterClientDisconnect": null,
"Tasks": [
{
"Affinities": null,
"Artifacts": null,
"CSIPluginConfig": null,
"Config": {
2022-05-17 15:24:19 +00:00
"image": "redis:7",
2020-12-18 19:54:39 +00:00
"ports": [
"db"
]
},
"Constraints": null,
"DispatchPayload": null,
"Driver": "docker",
"Env": null,
"KillSignal": "",
"KillTimeout": 5000000000,
"Kind": "",
"Leader": false,
"Lifecycle": null,
"LogConfig": {
2023-04-24 14:00:27 +00:00
"Enabled": true,
2020-12-18 19:54:39 +00:00
"MaxFileSizeMB": 10,
"MaxFiles": 10
},
"Meta": null,
"Name": "redis",
"Resources": {
"CPU": 500,
"Devices": null,
"DiskMB": 0,
"IOPS": 0,
"MemoryMB": 256,
"Networks": null
},
"RestartPolicy": {
"Attempts": 2,
"Delay": 15000000000,
"Interval": 1800000000000,
"Mode": "fail"
},
"ScalingPolicies": null,
"Services": null,
"ShutdownDelay": 0,
"Templates": null,
"User": "",
"Vault": null,
"VolumeMounts": null
}
],
"Update": {
"AutoPromote": false,
"AutoRevert": false,
"Canary": 0,
"HealthCheck": "checks",
"HealthyDeadline": 300000000000,
"MaxParallel": 1,
"MinHealthyTime": 10000000000,
"ProgressDeadline": 600000000000,
"Stagger": 30000000000
},
"Volumes": null
}
],
"Type": "service",
"Update": {
"AutoPromote": false,
"AutoRevert": false,
"Canary": 0,
"HealthCheck": "",
"HealthyDeadline": 0,
"MaxParallel": 1,
"MinHealthyTime": 0,
"ProgressDeadline": 0,
"Stagger": 30000000000
},
"VaultNamespace": "",
"VaultToken": "",
"Version": 0
}
]
}
2017-05-26 23:15:28 +00:00
```
## List Job Allocations
This endpoint reads information about a single job's allocations.
2020-02-06 23:45:31 +00:00
| Method | Path | Produces |
| ------ | ----------------------------- | ------------------ |
| `GET` | `/v1/job/:job_id/allocations` | `application/json` |
2017-05-26 23:15:28 +00:00
The table below shows this endpoint's support for
2023-01-25 17:31:14 +00:00
[blocking queries](/nomad/api-docs#blocking-queries) and
[required ACLs](/nomad/api-docs#acls).
2017-05-26 23:15:28 +00:00
2020-02-06 23:45:31 +00:00
| Blocking Queries | ACL Required |
| ---------------- | -------------------- |
| `YES` | `namespace:read-job` |
2017-05-26 23:15:28 +00:00
### Parameters
2017-07-06 20:21:56 +00:00
- `:job_id` `(string: <required>)` - Specifies the ID of the job (as specified in
2017-05-26 23:15:28 +00:00
the job file during submission). This is specified as part of the path.
2017-08-25 00:01:24 +00:00
- `all` `(bool: false)` - Specifies whether the list of allocations should
include allocations from a previously registered job with the same ID. This is
2023-02-22 16:28:32 +00:00
possible if the job is deregistered and re-registered.
- `namespace` `(string: "default")` - Specifies the target namespace. If ACL is
enabled, this value must match a namespace that the token is allowed to
access. This is specified as a query string parameter.
2017-08-25 00:01:24 +00:00
2017-05-26 23:15:28 +00:00
### Sample Request
2020-05-18 20:53:06 +00:00
```shell-session
$ curl \
2018-01-29 16:27:52 +00:00
https://localhost:4646/v1/job/my-job/allocations
2017-05-26 23:15:28 +00:00
```
### Sample Response
```json
[
{
"ID": "ed344e0a-7290-d117-41d3-a64f853ca3c2",
"EvalID": "a9c5effc-2242-51b2-f1fe-054ee11ab189",
"Name": "example.cache[0]",
"NodeID": "cb1f6030-a220-4f92-57dc-7baaabdc3823",
2018-01-31 21:54:10 +00:00
"PreviousAllocation": "516d2753-0513-cfc7-57ac-2d6fac18b9dc",
2020-02-06 23:45:31 +00:00
"NextAllocation": "cd13d9b9-4f97-7184-c88b-7b451981616b",
"RescheduleTracker": {
"Events": [
{
"PrevAllocID": "516d2753-0513-cfc7-57ac-2d6fac18b9dc",
"PrevNodeID": "9230cd3b-3bda-9a3f-82f9-b2ea8dedb20e",
"RescheduleTime": 1517434161192946200,
"Delay": 5000000000
}
]
2018-01-31 21:54:10 +00:00
},
2017-05-26 23:15:28 +00:00
"JobID": "example",
"TaskGroup": "cache",
"DesiredStatus": "run",
"DesiredDescription": "",
"ClientStatus": "running",
"ClientDescription": "",
"TaskStates": {
"redis": {
"State": "running",
"Failed": false,
"StartedAt": "2017-05-25T23:41:23.240184101Z",
"FinishedAt": "0001-01-01T00:00:00Z",
"Events": [
{
"Type": "Received",
"Time": 1495755675956923000,
"FailsTask": false,
"RestartReason": "",
"SetupError": "",
"DriverError": "",
"ExitCode": 0,
"Signal": 0,
"Message": "",
"KillTimeout": 0,
"KillError": "",
"KillReason": "",
"StartDelay": 0,
"DownloadError": "",
"ValidationError": "",
"DiskLimit": 0,
"FailedSibling": "",
"VaultError": "",
"TaskSignalReason": "",
"TaskSignal": "",
"DriverMessage": ""
},
{
"Type": "Task Setup",
"Time": 1495755675957466400,
"FailsTask": false,
"RestartReason": "",
"SetupError": "",
"DriverError": "",
"ExitCode": 0,
"Signal": 0,
"Message": "Building Task Directory",
"KillTimeout": 0,
"KillError": "",
"KillReason": "",
"StartDelay": 0,
"DownloadError": "",
"ValidationError": "",
"DiskLimit": 0,
"FailedSibling": "",
"VaultError": "",
"TaskSignalReason": "",
"TaskSignal": "",
"DriverMessage": ""
},
{
"Type": "Driver",
"Time": 1495755675970286800,
"FailsTask": false,
"RestartReason": "",
"SetupError": "",
"DriverError": "",
"ExitCode": 0,
"Signal": 0,
"Message": "",
"KillTimeout": 0,
"KillError": "",
"KillReason": "",
"StartDelay": 0,
"DownloadError": "",
"ValidationError": "",
"DiskLimit": 0,
"FailedSibling": "",
"VaultError": "",
"TaskSignalReason": "",
"TaskSignal": "",
2022-05-17 15:24:19 +00:00
"DriverMessage": "Downloading image redis:7"
2017-05-26 23:15:28 +00:00
},
{
"Type": "Started",
"Time": 1495755683227522000,
"FailsTask": false,
"RestartReason": "",
"SetupError": "",
"DriverError": "",
"ExitCode": 0,
"Signal": 0,
"Message": "",
"KillTimeout": 0,
"KillError": "",
"KillReason": "",
"StartDelay": 0,
"DownloadError": "",
"ValidationError": "",
"DiskLimit": 0,
"FailedSibling": "",
"VaultError": "",
"TaskSignalReason": "",
"TaskSignal": "",
"DriverMessage": ""
}
]
}
},
"CreateIndex": 9,
"ModifyIndex": 13,
2017-10-30 17:23:24 +00:00
"CreateTime": 1495755675944527600,
"ModifyTime": 1495755675944527600
2017-05-26 23:15:28 +00:00
}
]
```
## List Job Evaluations
This endpoint reads information about a single job's evaluations
2020-02-06 23:45:31 +00:00
| Method | Path | Produces |
| ------ | ----------------------------- | ------------------ |
| `GET` | `/v1/job/:job_id/evaluations` | `application/json` |
2017-05-26 23:15:28 +00:00
The table below shows this endpoint's support for
2023-01-25 17:31:14 +00:00
[blocking queries](/nomad/api-docs#blocking-queries) and
[required ACLs](/nomad/api-docs#acls).
2017-05-26 23:15:28 +00:00
2020-02-06 23:45:31 +00:00
| Blocking Queries | ACL Required |
| ---------------- | -------------------- |
| `YES` | `namespace:read-job` |
2017-05-26 23:15:28 +00:00
### Parameters
2017-07-06 20:21:56 +00:00
- `:job_id` `(string: <required>)` - Specifies the ID of the job (as specified in
2017-05-26 23:15:28 +00:00
the job file during submission). This is specified as part of the path.
2023-02-22 16:28:32 +00:00
- `namespace` `(string: "default")` - Specifies the target namespace. If ACL is
enabled, this value must match a namespace that the token is allowed to
access. This is specified as a query string parameter.
2017-05-26 23:15:28 +00:00
### Sample Request
2020-05-18 20:53:06 +00:00
```shell-session
$ curl \
2018-01-29 16:27:52 +00:00
https://localhost:4646/v1/job/my-job/evaluations
2017-05-26 23:15:28 +00:00
```
### Sample Response
```json
[
{
"ID": "a9c5effc-2242-51b2-f1fe-054ee11ab189",
"Priority": 50,
"Type": "service",
"TriggeredBy": "job-register",
"JobID": "example",
"JobModifyIndex": 7,
"NodeID": "",
"NodeModifyIndex": 0,
"Status": "complete",
"StatusDescription": "",
"Wait": 0,
"NextEval": "",
"PreviousEval": "",
"BlockedEval": "",
"FailedTGAllocs": null,
"ClassEligibility": null,
"EscapedComputedClass": false,
"AnnotatePlan": false,
"QueuedAllocations": {
"cache": 0
},
"SnapshotIndex": 8,
"CreateIndex": 8,
"ModifyIndex": 10
}
]
```
2017-07-06 20:21:56 +00:00
## List Job Deployments
This endpoint lists a single job's deployments
2020-02-06 23:45:31 +00:00
| Method | Path | Produces |
| ------ | ----------------------------- | ------------------ |
| `GET` | `/v1/job/:job_id/deployments` | `application/json` |
2017-07-06 20:21:56 +00:00
The table below shows this endpoint's support for
2023-01-25 17:31:14 +00:00
[blocking queries](/nomad/api-docs#blocking-queries) and
[required ACLs](/nomad/api-docs#acls).
2017-07-06 20:21:56 +00:00
2020-02-06 23:45:31 +00:00
| Blocking Queries | ACL Required |
| ---------------- | -------------------- |
| `YES` | `namespace:read-job` |
2017-07-06 20:21:56 +00:00
### Parameters
- `:job_id` `(string: <required>)` - Specifies the ID of the job (as specified in
the job file during submission). This is specified as part of the path.
2019-06-05 15:09:22 +00:00
- `all` `(bool: false)` - Specifies whether the list of deployments should
2019-05-14 21:13:59 +00:00
include deployments from a previously registered job with the same ID. This is
2023-02-22 16:28:32 +00:00
possible if the job is deregistered and re-registered.
- `namespace` `(string: "default")` - Specifies the target namespace. If ACL is
enabled, this value must match a namespace that the token is allowed to
access. This is specified as a query string parameter.
2019-05-14 21:13:59 +00:00
2017-07-06 20:21:56 +00:00
### Sample Request
2020-05-18 20:53:06 +00:00
```shell-session
$ curl \
2018-01-29 16:27:52 +00:00
https://localhost:4646/v1/job/my-job/deployments
2017-07-06 20:21:56 +00:00
```
### Sample Response
```json
[
{
"ID": "85ee4a9a-339f-a921-a9ef-0550d20b2c61",
"JobID": "my-job",
"JobVersion": 1,
"JobModifyIndex": 19,
"JobCreateIndex": 7,
"TaskGroups": {
"cache": {
"AutoRevert": true,
"Promoted": false,
"PlacedCanaries": [
"d0ad0808-2765-abf6-1e15-79fb7fe5a416",
"38c70cd8-81f2-1489-a328-87bb29ec0e0f"
],
"DesiredCanaries": 2,
"DesiredTotal": 3,
"PlacedAllocs": 2,
"HealthyAllocs": 2,
"UnhealthyAllocs": 0
}
},
"Status": "running",
"StatusDescription": "Deployment is running",
"CreateIndex": 21,
"ModifyIndex": 25
},
{
"ID": "fb6070fb-4a44-e255-4e6f-8213eba3871a",
"JobID": "my-job",
"JobVersion": 0,
"JobModifyIndex": 7,
"JobCreateIndex": 7,
"TaskGroups": {
"cache": {
"AutoRevert": true,
"Promoted": false,
"PlacedCanaries": null,
"DesiredCanaries": 0,
"DesiredTotal": 3,
"PlacedAllocs": 3,
"HealthyAllocs": 3,
"UnhealthyAllocs": 0
}
},
"Status": "successful",
"StatusDescription": "Deployment completed successfully",
"CreateIndex": 9,
"ModifyIndex": 17
}
]
```
## Read Job's Most Recent Deployment
This endpoint returns a single job's most recent deployment.
2020-02-06 23:45:31 +00:00
| Method | Path | Produces |
| ------ | ---------------------------- | ------------------ |
| `GET` | `/v1/job/:job_id/deployment` | `application/json` |
2017-07-06 20:21:56 +00:00
The table below shows this endpoint's support for
2023-01-25 17:31:14 +00:00
[blocking queries](/nomad/api-docs#blocking-queries) and
[required ACLs](/nomad/api-docs#acls).
2017-07-06 20:21:56 +00:00
2020-02-06 23:45:31 +00:00
| Blocking Queries | ACL Required |
| ---------------- | -------------------- |
| `YES` | `namespace:read-job` |
2017-07-06 20:21:56 +00:00
### Parameters
- `:job_id` `(string: <required>)` - Specifies the ID of the job (as specified in
the job file during submission). This is specified as part of the path.
2023-02-22 16:28:32 +00:00
- `namespace` `(string: "default")` - Specifies the target namespace. If ACL is
enabled, this value must match a namespace that the token is allowed to
access. This is specified as a query string parameter.
2017-07-06 20:21:56 +00:00
### Sample Request
2020-05-18 20:53:06 +00:00
```shell-session
$ curl \
2018-01-29 16:27:52 +00:00
https://localhost:4646/v1/job/my-job/deployment
2017-07-06 20:21:56 +00:00
```
### Sample Response
```json
{
"ID": "85ee4a9a-339f-a921-a9ef-0550d20b2c61",
"JobID": "my-job",
"JobVersion": 1,
"JobModifyIndex": 19,
"JobCreateIndex": 7,
"TaskGroups": {
"cache": {
"AutoRevert": true,
"Promoted": false,
"PlacedCanaries": [
"d0ad0808-2765-abf6-1e15-79fb7fe5a416",
"38c70cd8-81f2-1489-a328-87bb29ec0e0f"
],
"DesiredCanaries": 2,
"DesiredTotal": 3,
"PlacedAllocs": 2,
"HealthyAllocs": 2,
"UnhealthyAllocs": 0
}
},
"Status": "running",
"StatusDescription": "Deployment is running",
"CreateIndex": 21,
"ModifyIndex": 25
}
```
2017-05-26 23:15:28 +00:00
## Read Job Summary
This endpoint reads summary information about a job.
2020-02-06 23:45:31 +00:00
| Method | Path | Produces |
| ------ | ------------------------- | ------------------ |
| `GET` | `/v1/job/:job_id/summary` | `application/json` |
2017-05-26 23:15:28 +00:00
The table below shows this endpoint's support for
2023-01-25 17:31:14 +00:00
[blocking queries](/nomad/api-docs#blocking-queries) and
[required ACLs](/nomad/api-docs#acls).
2017-05-26 23:15:28 +00:00
2020-02-06 23:45:31 +00:00
| Blocking Queries | ACL Required |
| ---------------- | -------------------- |
| `YES` | `namespace:read-job` |
2017-05-26 23:15:28 +00:00
### Parameters
2017-07-06 20:21:56 +00:00
- `:job_id` `(string: <required>)` - Specifies the ID of the job (as specified in
2017-05-26 23:15:28 +00:00
the job file during submission). This is specified as part of the path.
2023-02-22 16:28:32 +00:00
- `namespace` `(string: "default")` - Specifies the target namespace. If ACL is
enabled, this value must match a namespace that the token is allowed to
access. This is specified as a query string parameter.
2017-05-26 23:15:28 +00:00
### Sample Request
2020-05-18 20:53:06 +00:00
```shell-session
$ curl \
2018-01-29 16:27:52 +00:00
https://localhost:4646/v1/job/my-job/summary
2017-05-26 23:15:28 +00:00
```
### Sample Response
```json
{
"JobID": "example",
"Summary": {
"cache": {
"Queued": 0,
"Complete": 0,
"Failed": 0,
"Running": 1,
"Starting": 0,
"Lost": 0
}
},
"Children": {
"Pending": 0,
"Running": 0,
"Dead": 0
},
"CreateIndex": 7,
"ModifyIndex": 13
}
```
## Update Existing Job
This endpoint registers a new job or updates an existing job.
2020-02-06 23:45:31 +00:00
| Method | Path | Produces |
| ------ | ----------------- | ------------------ |
| `POST` | `/v1/job/:job_id` | `application/json` |
2017-05-26 23:15:28 +00:00
The table below shows this endpoint's support for
2023-01-25 17:31:14 +00:00
[blocking queries](/nomad/api-docs#blocking-queries) and
[required ACLs](/nomad/api-docs#acls).
2017-05-26 23:15:28 +00:00
2020-02-06 23:45:31 +00:00
| Blocking Queries | ACL Required |
| ---------------- | --------------------------------------------------------------------------------- |
| `NO` | `namespace:submit-job`<br />`namespace:sentinel-override` if `PolicyOverride` set |
2017-05-26 23:15:28 +00:00
### Parameters
2017-07-06 20:21:56 +00:00
- `:job_id` `(string: <required>)` - Specifies the ID of the job (as specified in
2017-05-26 23:15:28 +00:00
the job file during submission). This is specified as part of the path.
- `Job` `(Job: <required>)` - Specifies the JSON definition of the job.
2017-09-19 14:47:10 +00:00
- `EnforceIndex` `(bool: false)` - If set, the job will only be registered if the
2017-05-26 23:15:28 +00:00
passed `JobModifyIndex` matches the current job's index. If the index is zero,
the register only occurs if the job is new. This paradigm allows check-and-set
style job updating.
2021-11-23 08:23:31 +00:00
- `EvalPriority` `(int: 0)` - Override the priority of the evaluations produced
as a result of this job update. By default, this is set to the priority of
the job.
2017-05-26 23:15:28 +00:00
- `JobModifyIndex` `(int: 0)` - Specifies the `JobModifyIndex` to enforce the
current job is at.
2017-09-19 14:47:10 +00:00
- `PolicyOverride` `(bool: false)` - If set, any soft mandatory Sentinel policies
2017-09-27 18:14:37 +00:00
will be overridden. This allows a job to be registered when it would be denied
2017-09-19 14:47:10 +00:00
by policy.
2023-02-22 16:28:32 +00:00
- `namespace` `(string: "default")` - Specifies the target namespace. If ACL is
enabled, this value must match a namespace that the token is allowed to
access. This is specified as a query string parameter.
2017-05-26 23:15:28 +00:00
### Sample Payload
```javascript
{
"Job": {
// ...
},
2017-09-19 14:47:10 +00:00
"EnforceIndex": true,
2017-05-26 23:15:28 +00:00
"JobModifyIndex": 4
}
2017-09-19 14:47:10 +00:00
```
2017-05-26 23:15:28 +00:00
### Sample Request
2020-05-18 20:53:06 +00:00
```shell-session
$ curl \
2017-05-26 23:15:28 +00:00
--request POST \
--data @payload.json \
2018-01-29 16:27:52 +00:00
https://localhost:4646/v1/job/my-job
2017-05-26 23:15:28 +00:00
```
### Sample Response
```json
{
"EvalID": "d092fdc0-e1fd-2536-67d8-43af8ca798ac",
"EvalCreateIndex": 35,
2020-02-06 23:45:31 +00:00
"JobModifyIndex": 34
2017-05-26 23:15:28 +00:00
}
```
## Dispatch Job
This endpoint dispatches a new instance of a parameterized job.
2020-02-06 23:45:31 +00:00
| Method | Path | Produces |
| ------ | -------------------------- | ------------------ |
| `POST` | `/v1/job/:job_id/dispatch` | `application/json` |
2017-05-26 23:15:28 +00:00
The table below shows this endpoint's support for
2023-01-25 17:31:14 +00:00
[blocking queries](/nomad/api-docs#blocking-queries) and
[required ACLs](/nomad/api-docs#acls).
2017-05-26 23:15:28 +00:00
2020-02-06 23:45:31 +00:00
| Blocking Queries | ACL Required |
| ---------------- | ------------------------ |
| `NO` | `namespace:dispatch-job` |
2017-05-26 23:15:28 +00:00
### Parameters
2017-07-06 20:21:56 +00:00
- `:job_id` `(string: <required>)` - Specifies the ID of the job (as specified
in the job file during submission). This is specified as part of the path.
2017-05-26 23:15:28 +00:00
2021-10-22 16:39:05 +00:00
- `idempotency_token` `(string: "")` - Optional identifier used to prevent more
than one instance of the job from being dispatched. This is specified as a
URL query parameter.
2017-05-26 23:15:28 +00:00
- `Payload` `(string: "")` - Specifies a base64 encoded string containing the
2023-01-31 18:32:36 +00:00
payload. This is limited to 65536 bytes (64KiB).
2017-05-26 23:15:28 +00:00
- `Meta` `(meta<string|string>: nil)` - Specifies arbitrary metadata to pass to
the job.
2023-02-22 16:28:32 +00:00
- `namespace` `(string: "default")` - Specifies the target namespace. If ACL is
enabled, this value must match a namespace that the token is allowed to
access. This is specified as a query string parameter.
2017-05-26 23:15:28 +00:00
### Sample Payload
```json
{
"Payload": "A28C3==",
"Meta": {
"key": "Value"
}
}
```
### Sample Request
2020-05-18 20:53:06 +00:00
```shell-session
$ curl \
2017-06-29 23:15:13 +00:00
--request POST \
2019-08-15 18:06:21 +00:00
--data @payload.json \
2018-01-29 16:27:52 +00:00
https://localhost:4646/v1/job/my-job/dispatch
2017-05-26 23:15:28 +00:00
```
### Sample Response
```json
{
"Index": 13,
"JobCreateIndex": 12,
"EvalCreateIndex": 13,
"EvalID": "e5f55fac-bc69-119d-528a-1fc7ade5e02c",
"DispatchedJobID": "example/dispatch-1485408778-81644024"
}
```
2017-07-06 20:21:56 +00:00
## Revert to older Job Version
This endpoint reverts the job to an older version.
2020-02-06 23:45:31 +00:00
| Method | Path | Produces |
| ------ | ------------------------ | ------------------ |
| `POST` | `/v1/job/:job_id/revert` | `application/json` |
2017-07-06 20:21:56 +00:00
The table below shows this endpoint's support for
2023-01-25 17:31:14 +00:00
[blocking queries](/nomad/api-docs#blocking-queries) and
[required ACLs](/nomad/api-docs#acls).
2017-07-06 20:21:56 +00:00
2020-02-06 23:45:31 +00:00
| Blocking Queries | ACL Required |
| ---------------- | ---------------------- |
| `NO` | `namespace:submit-job` |
2017-07-06 20:21:56 +00:00
### Parameters
- `JobID` `(string: <required>)` - Specifies the ID of the job (as specified
in the job file during submission). This is specified as part of the path.
2017-07-06 22:19:07 +00:00
- `JobVersion` `(integer: 0)` - Specifies the job version to revert to.
2017-07-06 20:21:56 +00:00
- `EnforcePriorVersion` `(integer: nil)` - Optional value specifying the current
job's version. This is checked and acts as a check-and-set value before
reverting to the specified job.
2023-01-25 17:31:14 +00:00
- `ConsulToken` `(string:"")` - Optional value specifying the [consul token](/nomad/docs/commands/job/revert)
used for Consul [service identity polity authentication checking](/nomad/docs/configuration/consul#allow_unauthenticated).
2019-11-18 21:05:06 +00:00
2023-01-25 17:31:14 +00:00
- `VaultToken` `(string: "")` - Optional value specifying the [vault token](/nomad/docs/commands/job/revert)
used for Vault [policy authentication checking](/nomad/docs/configuration/vault#allow_unauthenticated).
2019-03-27 15:47:57 +00:00
2023-02-22 16:28:32 +00:00
- `namespace` `(string: "default")` - Specifies the target namespace. If ACL is
enabled, this value must match a namespace that the token is allowed to
access. This is specified as a query string parameter.
2017-07-06 20:21:56 +00:00
### Sample Payload
```json
{
"JobID": "my-job",
2020-02-06 23:45:31 +00:00
"JobVersion": 2
2017-07-06 20:21:56 +00:00
}
```
### Sample Request
2020-05-18 20:53:06 +00:00
```shell-session
$ curl \
2017-07-06 20:21:56 +00:00
--request POST \
2019-08-15 18:06:21 +00:00
--data @payload.json \
2018-01-29 16:27:52 +00:00
https://localhost:4646/v1/job/my-job/revert
2017-07-06 20:21:56 +00:00
```
### Sample Response
```json
{
"EvalID": "d092fdc0-e1fd-2536-67d8-43af8ca798ac",
"EvalCreateIndex": 35,
2020-02-06 23:45:31 +00:00
"JobModifyIndex": 34
2017-07-06 20:21:56 +00:00
}
```
## Set Job Stability
This endpoint sets the job's stability.
2020-02-06 23:45:31 +00:00
| Method | Path | Produces |
| ------ | ------------------------ | ------------------ |
| `POST` | `/v1/job/:job_id/stable` | `application/json` |
2017-07-06 20:21:56 +00:00
The table below shows this endpoint's support for
2023-01-25 17:31:14 +00:00
[blocking queries](/nomad/api-docs#blocking-queries) and
[required ACLs](/nomad/api-docs#acls).
2017-07-06 20:21:56 +00:00
2020-02-06 23:45:31 +00:00
| Blocking Queries | ACL Required |
| ---------------- | ---------------------- |
| `NO` | `namespace:submit-job` |
2017-07-06 20:21:56 +00:00
### Parameters
- `JobID` `(string: <required>)` - Specifies the ID of the job (as specified
in the job file during submission). This is specified as part of the path.
2017-07-06 22:19:07 +00:00
- `JobVersion` `(integer: 0)` - Specifies the job version to set the stability on.
2017-07-06 20:21:56 +00:00
- `Stable` `(bool: false)` - Specifies whether the job should be marked as
stable or not.
2023-02-22 16:28:32 +00:00
- `namespace` `(string: "default")` - Specifies the target namespace. If ACL is
enabled, this value must match a namespace that the token is allowed to
access. This is specified as a query string parameter.
2017-07-06 20:21:56 +00:00
### Sample Payload
```json
{
"JobID": "my-job",
"JobVersion": 2,
"Stable": true
}
```
### Sample Request
2020-05-18 20:53:06 +00:00
```shell-session
$ curl \
2017-07-06 20:21:56 +00:00
--request POST \
2019-08-15 18:06:21 +00:00
--data @payload.json \
2018-01-29 16:27:52 +00:00
https://localhost:4646/v1/job/my-job/stable
2017-07-06 20:21:56 +00:00
```
### Sample Response
```json
{
2020-02-06 23:45:31 +00:00
"JobModifyIndex": 34
2017-07-06 20:21:56 +00:00
}
```
2017-05-26 23:15:28 +00:00
## Create Job Evaluation
This endpoint creates a new evaluation for the given job. This can be used to
2018-05-09 21:51:58 +00:00
force run the scheduling logic if necessary. Since Nomad 0.8.4, this endpoint
supports a JSON payload with additional options. Support for calling this end point
without a JSON payload will be removed in Nomad 0.9.
2017-05-26 23:15:28 +00:00
2020-02-06 23:45:31 +00:00
| Method | Path | Produces |
| ------ | -------------------------- | ------------------ |
| `POST` | `/v1/job/:job_id/evaluate` | `application/json` |
2017-05-26 23:15:28 +00:00
The table below shows this endpoint's support for
2023-01-25 17:31:14 +00:00
[blocking queries](/nomad/api-docs#blocking-queries) and
[required ACLs](/nomad/api-docs#acls).
2017-05-26 23:15:28 +00:00
2023-03-13 21:13:54 +00:00
| Blocking Queries | ACL Required |
| ---------------- | ---------------------- |
| `NO` | `namespace:submit-job` |
2017-05-26 23:15:28 +00:00
### Parameters
2017-07-06 20:21:56 +00:00
- `:job_id` `(string: <required>)` - Specifies the ID of the job (as specified in
2017-05-26 23:15:28 +00:00
the job file during submission). This is specified as part of the path.
2018-05-09 21:51:58 +00:00
- `JobID` `(string: <required>)` - Specify the ID of the job in the JSON payload
- `EvalOptions` `(<optional>)` - Specify additional options to be used during the forced evaluation.
2020-02-06 23:45:31 +00:00
- `ForceReschedule` `(bool: false)` - If set, failed allocations of the job are rescheduled
2018-05-09 21:51:58 +00:00
immediately. This is useful for operators to force immediate placement even if the failed allocations are past
2023-02-22 16:28:32 +00:00
their rescheduling limit, or are delayed by several hours because the allocation's reschedule policy has exponential delay.
- `namespace` `(string: "default")` - Specifies the target namespace. If ACL is
enabled, this value must match a namespace that the token is allowed to
access. This is specified as a query string parameter.
2018-05-09 21:51:58 +00:00
### Sample Payload
```json
{
"JobID": "my-job",
"EvalOptions": {
2020-02-06 23:45:31 +00:00
"ForceReschedule": true
2018-05-09 21:51:58 +00:00
}
}
```
2017-05-26 23:15:28 +00:00
### Sample Request
2020-05-18 20:53:06 +00:00
```shell-session
$ curl \
2017-05-26 23:15:28 +00:00
--request POST \
2018-05-10 19:42:24 +00:00
-d @sample.json \
2018-01-29 16:27:52 +00:00
https://localhost:4646/v1/job/my-job/evaluate
2017-05-26 23:15:28 +00:00
```
### Sample Response
```json
{
"EvalID": "d092fdc0-e1fd-2536-67d8-43af8ca798ac",
"EvalCreateIndex": 35,
2020-02-06 23:45:31 +00:00
"JobModifyIndex": 34
2017-05-26 23:15:28 +00:00
}
```
## Create Job Plan
This endpoint invokes a dry-run of the scheduler for the job.
2020-02-06 23:45:31 +00:00
| Method | Path | Produces |
| ------ | ---------------------- | ------------------ |
| `POST` | `/v1/job/:job_id/plan` | `application/json` |
2017-05-26 23:15:28 +00:00
The table below shows this endpoint's support for
2023-01-25 17:31:14 +00:00
[blocking queries](/nomad/api-docs#blocking-queries) and
[required ACLs](/nomad/api-docs#acls).
2017-05-26 23:15:28 +00:00
2020-02-06 23:45:31 +00:00
| Blocking Queries | ACL Required |
| ---------------- | --------------------------------------------------------------------------------- |
| `NO` | `namespace:submit-job`<br />`namespace:sentinel-override` if `PolicyOverride` set |
2017-05-26 23:15:28 +00:00
### Parameters
2017-07-06 20:21:56 +00:00
- `:job_id` `(string: <required>)` - Specifies the ID of the job (as specified in
2017-05-26 23:15:28 +00:00
- the job file during submission). This is specified as part of the path.
- `Job` `(string: <required>)` - Specifies the JSON definition of the job.
- `Diff` `(bool: false)` - Specifies whether the diff structure between the
submitted and server side version of the job should be included in the
response.
2017-09-19 14:47:10 +00:00
- `PolicyOverride` `(bool: false)` - If set, any soft mandatory Sentinel policies
2017-09-27 18:14:37 +00:00
will be overridden. This allows a job to be registered when it would be denied
2017-09-19 14:47:10 +00:00
by policy.
2023-02-22 16:28:32 +00:00
- `namespace` `(string: "default")` - Specifies the target namespace. If ACL is
enabled, this value must match a namespace that the token is allowed to
access. This is specified as a query string parameter.
2017-05-26 23:15:28 +00:00
### Sample Payload
```json
{
2020-10-22 14:17:47 +00:00
"Job": {
// ...
},
2017-09-19 14:47:10 +00:00
"Diff": true,
"PolicyOverride": false
2017-05-26 23:15:28 +00:00
}
```
### Sample Request
2020-05-18 20:53:06 +00:00
```shell-session
$ curl \
2017-05-26 23:15:28 +00:00
--request POST \
2019-08-15 18:06:21 +00:00
--data @payload.json \
2018-01-29 16:27:52 +00:00
https://localhost:4646/v1/job/my-job/plan
2017-05-26 23:15:28 +00:00
```
### Sample Response
```json
{
"Index": 0,
"NextPeriodicLaunch": "0001-01-01T00:00:00Z",
2017-07-26 00:18:15 +00:00
"Warnings": "",
2017-05-26 23:15:28 +00:00
"Diff": {
"Type": "Added",
"TaskGroups": [
{
"Updates": {
"create": 1
},
"Type": "Added",
"Tasks": [
{
"Type": "Added",
2020-02-06 23:45:31 +00:00
"Objects": ["..."],
2017-05-26 23:15:28 +00:00
"Name": "redis",
"Fields": [
{
"Type": "Added",
"Old": "",
"New": "docker",
"Name": "Driver",
"Annotations": null
},
{
"Type": "Added",
"Old": "",
"New": "5000000000",
"Name": "KillTimeout",
"Annotations": null
}
],
2020-02-06 23:45:31 +00:00
"Annotations": ["forces create"]
2017-05-26 23:15:28 +00:00
}
],
2020-02-06 23:45:31 +00:00
"Objects": ["..."],
2017-05-26 23:15:28 +00:00
"Name": "cache",
2020-02-06 23:45:31 +00:00
"Fields": ["..."]
2017-05-26 23:15:28 +00:00
}
],
"Objects": [
{
"Type": "Added",
"Objects": null,
"Name": "Datacenters",
2020-02-06 23:45:31 +00:00
"Fields": ["..."]
2017-05-26 23:15:28 +00:00
},
{
"Type": "Added",
"Objects": null,
"Name": "Constraint",
2020-02-06 23:45:31 +00:00
"Fields": ["..."]
2017-05-26 23:15:28 +00:00
},
{
"Type": "Added",
"Objects": null,
"Name": "Update",
2020-02-06 23:45:31 +00:00
"Fields": ["..."]
2017-05-26 23:15:28 +00:00
}
],
"ID": "example",
2020-02-06 23:45:31 +00:00
"Fields": ["..."]
2017-05-26 23:15:28 +00:00
},
"CreatedEvals": [
{
"ModifyIndex": 0,
"CreateIndex": 0,
"SnapshotIndex": 0,
"AnnotatePlan": false,
"EscapedComputedClass": false,
"NodeModifyIndex": 0,
"NodeID": "",
"JobModifyIndex": 0,
"JobID": "example",
"TriggeredBy": "job-register",
"Type": "batch",
"Priority": 50,
"ID": "312e6a6d-8d01-0daf-9105-14919a66dba3",
"Status": "blocked",
"StatusDescription": "created to place remaining allocations",
"Wait": 0,
"NextEval": "",
"PreviousEval": "80318ae4-7eda-e570-e59d-bc11df134817",
"BlockedEval": "",
"FailedTGAllocs": null,
"ClassEligibility": {
"v1:7968290453076422024": true
}
}
],
"JobModifyIndex": 0,
"FailedTGAllocs": {
"cache": {
"CoalescedFailures": 3,
"AllocationTime": 46415,
"Scores": null,
"NodesEvaluated": 1,
"NodesFiltered": 0,
"NodesAvailable": {
"dc1": 1
},
"ClassFiltered": null,
"ConstraintFiltered": null,
"NodesExhausted": 1,
"ClassExhausted": null,
"DimensionExhausted": {
2017-11-29 04:15:32 +00:00
"cpu": 1
2017-05-26 23:15:28 +00:00
}
}
},
"Annotations": {
"DesiredTGUpdates": {
"cache": {
"DestructiveUpdate": 0,
"InPlaceUpdate": 0,
"Stop": 0,
"Migrate": 0,
"Place": 11,
"Ignore": 0
}
}
}
}
```
#### Field Reference
- `Diff` - A diff structure between the submitted job and the server side
version. The top-level object is a Job Diff which contains Task Group Diffs,
which in turn contain Task Diffs. Each of these objects then has Object and
Field Diff structures embedded.
2017-07-06 20:21:56 +00:00
- `NextPeriodicLaunch` - If the job being planned is periodic, this field will
2017-05-26 23:15:28 +00:00
include the next launch time for the job.
- `CreatedEvals` - A set of evaluations that were created as a result of the
dry-run. These evaluations can signify a follow-up rolling update evaluation
or a blocked evaluation.
2017-07-06 20:21:56 +00:00
- `JobModifyIndex` - The `JobModifyIndex` of the server side version of this job.
2017-05-26 23:15:28 +00:00
- `FailedTGAllocs` - A set of metrics to understand any allocation failures that
occurred for the Task Group.
- `Annotations` - Annotations include the `DesiredTGUpdates`, which tracks what
- the scheduler would do given enough resources for each Task Group.
## Force New Periodic Instance
This endpoint forces a new instance of the periodic job. A new instance will be
created even if it violates the job's
2023-01-25 17:31:14 +00:00
[`prohibit_overlap`](/nomad/docs/job-specification/periodic#prohibit_overlap)
2017-05-26 23:15:28 +00:00
settings. As such, this should be only used to immediately run a periodic job.
2020-02-06 23:45:31 +00:00
| Method | Path | Produces |
| ------ | -------------------------------- | ------------------ |
| `POST` | `/v1/job/:job_id/periodic/force` | `application/json` |
2017-05-26 23:15:28 +00:00
The table below shows this endpoint's support for
2023-01-25 17:31:14 +00:00
[blocking queries](/nomad/api-docs#blocking-queries) and
[required ACLs](/nomad/api-docs#acls).
2017-05-26 23:15:28 +00:00
2020-11-02 17:42:57 +00:00
| Blocking Queries | ACL Required |
| ---------------- | -------------------------------------------------- |
| `NO` | `namespace:dispatch-job` or `namespace:submit-job` |
2017-05-26 23:15:28 +00:00
### Parameters
2017-07-06 20:21:56 +00:00
- `:job_id` `(string: <required>)` - Specifies the ID of the job (as specified in
2017-05-26 23:15:28 +00:00
the job file during submission). This is specified as part of the path.
### Sample Request
2020-05-18 20:53:06 +00:00
```shell-session
$ curl \
2017-05-26 23:15:28 +00:00
--request POST \
2018-01-29 16:27:52 +00:00
https://localhost:4646/v1/job/my-job/periodic/force
2017-05-26 23:15:28 +00:00
```
### Sample Response
```json
{
"EvalCreateIndex": 7,
"EvalID": "57983ddd-7fcf-3e3a-fd24-f699ccfb36f4"
}
```
2017-07-31 21:03:35 +00:00
## Stop a Job
2017-05-26 23:15:28 +00:00
This endpoint deregisters a job, and stops all allocations part of it.
2020-02-06 23:45:31 +00:00
| Method | Path | Produces |
| -------- | ----------------- | ------------------ |
| `DELETE` | `/v1/job/:job_id` | `application/json` |
2017-05-26 23:15:28 +00:00
The table below shows this endpoint's support for
2023-01-25 17:31:14 +00:00
[blocking queries](/nomad/api-docs#blocking-queries) and
[required ACLs](/nomad/api-docs#acls).
2017-05-26 23:15:28 +00:00
2020-02-06 23:45:31 +00:00
| Blocking Queries | ACL Required |
| ---------------- | ---------------------- |
| `NO` | `namespace:submit-job` |
2017-05-26 23:15:28 +00:00
### Parameters
2017-07-06 20:21:56 +00:00
- `:job_id` `(string: <required>)` - Specifies the ID of the job (as specified in
2017-05-26 23:15:28 +00:00
the job file during submission). This is specified as part of the path.
2021-11-23 08:23:31 +00:00
- `eval_priority` `(int: 0)` - Override the priority of the evaluations produced
as a result of this job deregistration. By default, this is set to the priority
of the job.
2021-11-19 12:45:24 +00:00
- `global` `(bool: false)` - Stop a multi-region job in all its regions. By default,
job stop will stop only a single region at a time. Ignored for single-region jobs.
- `purge` `(bool: false)` - Specifies that the job should be stopped and purged
2017-07-31 21:03:35 +00:00
immediately. This means the job will not be queryable after being stopped. If
not set, the job will be purged by the garbage collector.
2023-02-22 16:28:32 +00:00
- `namespace` `(string: "default")` - Specifies the target namespace. If ACL is
enabled, this value must match a namespace that the token is allowed to
access. This is specified as a query string parameter.
2017-05-26 23:15:28 +00:00
### Sample Request
2020-05-18 20:53:06 +00:00
```shell-session
$ curl \
2017-05-26 23:15:28 +00:00
--request DELETE \
2018-01-29 16:27:52 +00:00
https://localhost:4646/v1/job/my-job?purge=true
2017-05-26 23:15:28 +00:00
```
### Sample Response
```json
{
"EvalID": "d092fdc0-e1fd-2536-67d8-43af8ca798ac",
"EvalCreateIndex": 35,
2020-02-06 23:45:31 +00:00
"JobModifyIndex": 34
2017-05-26 23:15:28 +00:00
}
```
2020-03-24 22:08:34 +00:00
2020-12-08 14:39:25 +00:00
## Read Job Scale Status
2020-03-24 22:08:34 +00:00
This endpoint reads scale information about a job.
| Method | Path | Produces |
| ------ | ----------------------- | ------------------ |
| `GET` | `/v1/job/:job_id/scale` | `application/json` |
The table below shows this endpoint's support for
2023-01-25 17:31:14 +00:00
[blocking queries](/nomad/api-docs#blocking-queries) and
[required ACLs](/nomad/api-docs#acls).
2020-03-24 22:08:34 +00:00
2020-05-01 20:02:21 +00:00
| Blocking Queries | ACL Required |
| ---------------- | ---------------------------------------------------- |
| `YES` | `namespace:read-job-scaling` or `namespace:read-job` |
2020-03-24 22:08:34 +00:00
### Parameters
- `:job_id` `(string: <required>)` - Specifies the ID of the job (as specified in
the job file during submission). This is specified as part of the path.
2023-02-22 16:28:32 +00:00
- `namespace` `(string: "default")` - Specifies the target namespace. If ACL is
enabled, this value must match a namespace that the token is allowed to
access. This is specified as a query string parameter.
2020-03-24 22:08:34 +00:00
### Sample Request
2020-05-18 20:53:06 +00:00
```shell-session
$ curl \
2020-03-24 22:08:34 +00:00
https://localhost:4646/v1/job/my-job/scale
```
### Sample Response
```json
{
2020-05-01 20:02:21 +00:00
"JobCreateIndex": 10,
"JobID": "example",
2020-07-24 12:45:50 +00:00
"Namespace": "default",
2020-05-01 20:02:21 +00:00
"JobModifyIndex": 18,
"JobStopped": false,
"TaskGroups": {
"cache": {
"Desired": 1,
"Events": null,
"Healthy": 1,
"Placed": 1,
"Running": 0,
"Unhealthy": 0
2020-03-24 22:08:34 +00:00
}
2020-05-01 20:02:21 +00:00
}
2020-03-24 22:08:34 +00:00
}
```
2020-05-01 20:02:21 +00:00
2020-12-08 14:39:25 +00:00
## Scale Task Group
2020-03-24 22:08:34 +00:00
This endpoint performs a scaling action against a job.
Currently, this endpoint supports scaling the count for a task group.
2020-06-17 17:44:58 +00:00
This will return a 400 error if the job has an active deployment.
2020-03-24 22:08:34 +00:00
| Method | Path | Produces |
| ------ | ----------------------- | ------------------ |
| `POST` | `/v1/job/:job_id/scale` | `application/json` |
The table below shows this endpoint's support for
2023-01-25 17:31:14 +00:00
[blocking queries](/nomad/api-docs#blocking-queries) and
[required ACLs](/nomad/api-docs#acls).
2020-03-24 22:08:34 +00:00
2020-05-01 20:02:21 +00:00
| Blocking Queries | ACL Required |
| ---------------- | ---------------------------------------------------------------------------------------------------------- |
2020-03-24 22:08:34 +00:00
| `NO` | `namespace:scale-job` or `namespace:submit-job`<br />`namespace:sentinel-override` if `PolicyOverride` set |
### Parameters
- `:job_id` `(string: <required>)` - Specifies the ID of the job (as specified in
the job file during submission). This is specified as part of the path.
- `Count` `(int: <optional>)` - Specifies the new task group count.
- `Target` `(json: required)` - JSON map containing the target of the scaling operation.
2020-05-01 20:02:21 +00:00
Must contain a field `Group` with the name of the task group that is the target of this scaling action.
2020-03-24 22:08:34 +00:00
2020-07-30 16:06:08 +00:00
- `Message` `(string: <optional>)` - Description of the scale action, persisted as part of the scaling event.
Indicates information or reason for scaling; one of `Message` or `Error` must be provided.
2020-03-24 22:08:34 +00:00
- `Error` `(string: <optional>)` - Description of the scale action, persisted as part of the scaling event.
2020-07-30 16:06:08 +00:00
Indicates an error state preventing scaling; one of `Message` or `Error` must be provided.
2020-03-24 22:08:34 +00:00
2020-05-01 20:02:21 +00:00
- `Meta` `(json: <optional>)` - JSON block that is persisted as part of the scaling event.
2020-03-24 22:08:34 +00:00
- `PolicyOverride` `(bool: false)` - If set, any soft mandatory Sentinel policies
will be overridden. This allows a job to be scaled when it would be denied
by policy.
2023-02-22 16:28:32 +00:00
- `namespace` `(string: "default")` - Specifies the target namespace. If ACL is
enabled, this value must match a namespace that the token is allowed to
access. This is specified as a query string parameter.
2020-03-24 22:08:34 +00:00
### Sample Payload
```javascript
{
"Count": 5,
"Meta": {
"metrics": [
"cpu",
"memory"
]
},
2020-07-30 16:06:08 +00:00
"Message": "metric did not satisfy SLA",
2020-03-24 22:08:34 +00:00
"Target": {
"Group": "cache"
}
}
```
### Sample Request
2020-05-18 20:53:06 +00:00
```shell-session
$ curl \
2020-03-24 22:08:34 +00:00
--request POST \
--data @payload.json \
https://localhost:4646/v1/job/example/scale
```
### Sample Response
This is the same payload as returned by job update.
`EvalCreateIndex` and `EvalID` will only be present if the scaling operation resulted in the creation of an evaluation.
```json
{
2020-05-01 20:02:21 +00:00
"EvalCreateIndex": 45,
"EvalID": "116f3ede-f6a5-f6e7-2d0e-1fda136390f0",
"Index": 45,
"JobModifyIndex": 44,
"KnownLeader": false,
"LastContact": 0,
"Warnings": ""
2020-03-24 22:08:34 +00:00
}
```
2022-05-30 14:15:09 +00:00
## Job Services
The endpoint is used to read all services registered within Nomad belonging to the passed job ID.
| Method | Path | Produces |
| ------ | ----------------------- | ------------------ |
| `GET` | `/job/:job_id/services` | `application/json` |
The table below shows this endpoint's support for
2023-01-25 17:31:14 +00:00
[blocking queries](/nomad/api-docs#blocking-queries), [consistency modes](/nomad/api-docs#consistency-modes) and
[required ACLs](/nomad/api-docs#acls).
2022-05-30 14:15:09 +00:00
| Blocking Queries | Consistency Modes | ACL Required |
| ---------------- | ----------------- | -------------------- |
| `YES` | `all` | `namespace:read-job` |
### Parameters
- `:job_id` `(string: <required>)` - Specifies the ID of the job (as specified in
the job file during submission). This is specified as part of the path.
- `namespace` `(string: "default")` - Specifies the target namespace.
### Sample Request
```shell-session
$ curl \
https://localhost:4646/v1/job/example/services
```
### Sample Response
```json
[
{
"Address": "127.0.0.1",
"AllocID": "177160af-26f6-619f-9c9f-5e46d1104395",
"CreateIndex": 14,
"Datacenter": "dc1",
"ID": "_nomad-task-177160af-26f6-619f-9c9f-5e46d1104395-redis-example-cache-redis-db",
"JobID": "example",
"ModifyIndex": 24,
"Namespace": "default",
"NodeID": "7406e90b-de16-d118-80fe-60d0f2730cb3",
"Port": 29702,
"ServiceName": "example-cache-redis",
"Tags": [
"db",
"cache"
]
}
]
```