luxolus
/
open-nomad
2
0
Fork 0
Code Issues 1 Pull Requests Packages Releases Wiki Activity
open-nomad/website/source/api/jobs.html.md

1250 lines
31 KiB
Markdown
Raw Normal View History

Migrate jobs APIs
2017-05-26 23:15:28 +00:00
---
layout: api
page_title: Jobs - HTTP API
sidebar_current: api-jobs
description: |-
The /jobs endpoints are used to query for and interact with jobs.
---
# 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.
| Method | Path | Produces |
| ------ | ------------------------- | -------------------------- |
| `GET` | `/v1/jobs` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/index.html#blocking-queries),
[consistency modes](/api/index.html#consistency-modes), and
[required ACLs](/api/index.html#acls).
| Blocking Queries | Consistency Modes | ACL Required |
| ---------------- | ----------------- | ------------ |
| `YES` | `all` | `none` |
### Parameters
- `prefix` `(string: "")`- Specifies a string to filter jobs on based on
an index prefix. This is specified as a querystring parameter.
### Sample Request
```text
$ curl \
https://nomad.rocks/v1/jobs
```
```text
$ curl \
https://nomad.rocks/v1/jobs?prefix=team
```
### Sample Response
```json
[
{
"ID": "example",
"ParentID": "",
"Name": "example",
"Type": "service",
"Priority": 50,
"Status": "pending",
"StatusDescription": "",
"JobSummary": {
"JobID": "example",
"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.
| Method | Path | Produces |
| ------- | ------------------------- | -------------------------- |
| `POST` | `/v1/jobs` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/index.html#blocking-queries),
[consistency modes](/api/index.html#consistency-modes), and
[required ACLs](/api/index.html#acls).
| Blocking Queries | Consistency Modes | ACL Required |
| ---------------- | ----------------- | ------------ |
| `NO` | `all` | `none` |
### Parameters
There are no parameters, but the request _body_ contains the entire job file.
### Sample Payload
```text
(any valid nomad job IN JSON FORMAT)
```
### Sample Request
```text
$ curl \
--request POST \
--data @my-job.nomad \
https://nomad.rocks/v1/jobs
```
### Sample Response
```json
{
"EvalID": "",
"EvalCreateIndex": 0,
"JobModifyIndex": 109,
"Index": 0,
"LastContact": 0,
"KnownLeader": false
}
```
## Read Job
This endpoint reads information about a single job for its specification and
status.
| Method | Path | Produces |
| ------ | ------------------------- | -------------------------- |
| `GET` | `/v1/job/:job_id` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/index.html#blocking-queries),
[consistency modes](/api/index.html#consistency-modes), and
[required ACLs](/api/index.html#acls).
| Blocking Queries | Consistency Modes | ACL Required |
| ---------------- | ----------------- | ------------ |
| `YES` | `all` | `none` |
### 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.
### Sample Request
```text
$ curl \
https://nomad.rocks/v1/job/my-job
```
### Sample Response
```json
{
"Region": "global",
"ID": "example",
"ParentID": "",
"Name": "example",
"Type": "batch",
"Priority": 50,
"AllAtOnce": false,
"Datacenters": [
"dc1"
],
"Constraints": [
{
"LTarget": "${attr.kernel.name}",
"RTarget": "linux",
"Operand": "="
}
],
"TaskGroups": [
{
"Name": "cache",
"Count": 1,
"Constraints": [
{
"LTarget": "${attr.os.signals}",
"RTarget": "SIGUSR1",
"Operand": "set_contains"
}
],
"RestartPolicy": {
"Attempts": 10,
"Interval": 300000000000,
"Delay": 25000000000,
"Mode": "delay"
},
"Tasks": [
{
"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",
"Tags": [
"global",
"cache"
],
"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,
"Resources": {
"CPU": 500,
"MemoryMB": 256,
"DiskMB": 0,
"IOPS": 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": {
"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",
"MetaRequired": [
"foo"
],
"MetaOptional": [
"bar"
]
},
"Payload": null,
"Meta": {
"foo": "bar",
"baz": "pipe"
},
"VaultToken": "",
"Status": "running",
"StatusDescription": "",
"CreateIndex": 7,
"ModifyIndex": 7,
"JobModifyIndex": 7
}
```
## List Job Versions
This endpoint reads information about all versions of a job.
| Method | Path | Produces |
| ------ | -------------------------- | -------------------------- |
| `GET` | `/v1/job/:job_id/versions` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/index.html#blocking-queries),
[consistency modes](/api/index.html#consistency-modes), and
[required ACLs](/api/index.html#acls).
| Blocking Queries | Consistency Modes | ACL Required |
| ---------------- | ----------------- | ------------ |
| `YES` | `all` | `none` |
### 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.
### Sample Request
```text
$ curl \
https://nomad.rocks/v1/job/my-job/versions
```
### Sample Response
```json
[
{
"Stop": false,
"Region": "global",
"ID": "example",
"ParentID": "",
"Name": "example",
"Type": "service",
"Priority": 50,
"AllAtOnce": false,
"Datacenters": [
"dc1"
],
"Constraints": null,
"TaskGroups": [
{
"Name": "cache",
"Count": 1,
"Update": {
"Stagger": 0,
"MaxParallel": 1,
"HealthCheck": "checks",
"MinHealthyTime": 10000000000,
"HealthyDeadline": 300000000000,
"AutoRevert": false,
"Canary": 0
},
"Constraints": null,
"RestartPolicy": {
"Attempts": 10,
"Interval": 300000000000,
"Delay": 25000000000,
"Mode": "delay"
},
"Tasks": [
{
"Name": "redis",
"Driver": "docker",
"User": "",
"Config": {
"image": "redis:3.2",
"port_map": [
{
"db": 6379
}
]
},
"Env": null,
"Services": [
{
"Name": "global-redis-check",
"PortLabel": "db",
"Tags": [
"global",
"cache"
],
"Checks": [
{
"Name": "alive",
"Type": "tcp",
"Command": "",
"Args": null,
"Path": "",
"Protocol": "",
"PortLabel": "",
"Interval": 10000000000,
"Timeout": 2000000000,
"InitialStatus": "",
"TLSSkipVerify": false
}
]
}
],
"Vault": null,
"Templates": null,
"Constraints": null,
"Resources": {
"CPU": 500,
"MemoryMB": 256,
"DiskMB": 0,
"IOPS": 0,
"Networks": [
{
"Device": "",
"CIDR": "",
"IP": "",
"MBits": 10,
"ReservedPorts": null,
"DynamicPorts": [
{
"Label": "db",
"Value": 0
}
]
}
]
},
"DispatchPayload": null,
"Meta": null,
"KillTimeout": 5000000000,
"LogConfig": {
"MaxFiles": 10,
"MaxFileSizeMB": 10
},
"Artifacts": null,
"Leader": false
}
],
"EphemeralDisk": {
"Sticky": false,
"SizeMB": 300,
"Migrate": false
},
"Meta": null
}
],
"Update": {
"Stagger": 10000000000,
"MaxParallel": 1,
"HealthCheck": "",
"MinHealthyTime": 0,
"HealthyDeadline": 0,
"AutoRevert": false,
"Canary": 0
},
"Periodic": null,
"ParameterizedJob": null,
"Payload": null,
"Meta": null,
"VaultToken": "",
"Status": "pending",
"StatusDescription": "",
"Stable": false,
"Version": 0,
"CreateIndex": 7,
"ModifyIndex": 7,
"JobModifyIndex": 7
}
]
```
## List Job Allocations
This endpoint reads information about a single job's allocations.
| Method | Path | Produces |
| ------ | ----------------------------- | -------------------------- |
| `GET` | `/v1/job/:job_id/allocations` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/index.html#blocking-queries),
[consistency modes](/api/index.html#consistency-modes), and
[required ACLs](/api/index.html#acls).
| Blocking Queries | Consistency Modes | ACL Required |
| ---------------- | ----------------- | ------------ |
| `YES` | `all` | `none` |
### 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.
### Sample Request
```text
$ curl \
https://nomad.rocks/v1/job/my-job/allocations
```
### 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",
"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": "",
"DriverMessage": "Downloading image redis:3.2"
},
{
"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,
"CreateTime": 1495755675944527600
}
]
```
## List Job Evaluations
This endpoint reads information about a single job's evaluations
| Method | Path | Produces |
| ------ | ----------------------------- | -------------------------- |
| `GET` | `/v1/job/:job_id/evaluations` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/index.html#blocking-queries),
[consistency modes](/api/index.html#consistency-modes), and
[required ACLs](/api/index.html#acls).
| Blocking Queries | Consistency Modes | ACL Required |
| ---------------- | ----------------- | ------------ |
| `YES` | `all` | `none` |
### 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.
### Sample Request
```text
$ curl \
https://nomad.rocks/v1/job/my-job/evaluations
```
### 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
}
]
```
## Read Job Summary
This endpoint reads summary information about a job.
| Method | Path | Produces |
| ------ | -------------------------- | -------------------------- |
| `GET` | `/v1/job/:job_id/summary` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/index.html#blocking-queries),
[consistency modes](/api/index.html#consistency-modes), and
[required ACLs](/api/index.html#acls).
| Blocking Queries | Consistency Modes | ACL Required |
| ---------------- | ----------------- | ------------ |
| `YES` | `all` | `none` |
### 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.
### Sample Request
```text
$ curl \
https://nomad.rocks/v1/job/my-job/summary
```
### 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.
| Method | Path | Produces |
| ------- | -------------------------- | -------------------------- |
| `POST` | `/v1/job/:job_id` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/index.html#blocking-queries),
[consistency modes](/api/index.html#consistency-modes), and
[required ACLs](/api/index.html#acls).
| Blocking Queries | Consistency Modes | ACL Required |
| ---------------- | ----------------- | ------------ |
| `NO` | `all` | `none` |
### 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.
- `Job` `(Job: <required>)` - Specifies the JSON definition of the job.
- `EnforceIndex` `(int: 0)` - 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.
- `JobModifyIndex` `(int: 0)` - Specifies the `JobModifyIndex` to enforce the
current job is at.
### Sample Payload
```javascript
{
"Job": {
// ...
},
"EnforceIndex": 1,
"JobModifyIndex": 4
}
```
### Sample Request
```text
$ curl \
--request POST \
--data @payload.json \
https://nomad.rocks/v1/job/my-job
```
### Sample Response
```json
{
"EvalID": "d092fdc0-e1fd-2536-67d8-43af8ca798ac",
"EvalCreateIndex": 35,
"JobModifyIndex": 34,
}
```
## Dispatch Job
This endpoint dispatches a new instance of a parameterized job.
| Method | Path | Produces |
| ------- | -------------------------- | -------------------------- |
| `POST` | `/v1/job/:job_id/dispatch` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/index.html#blocking-queries),
[consistency modes](/api/index.html#consistency-modes), and
[required ACLs](/api/index.html#acls).
| Blocking Queries | Consistency Modes | ACL Required |
| ---------------- | ----------------- | ------------ |
| `NO` | `all` | `none` |
### 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.
- `Payload` `(string: "")` - Specifies a base64 encoded string containing the
payload. This is limited to 15 KB.
- `Meta` `(meta<string|string>: nil)` - Specifies arbitrary metadata to pass to
the job.
### Sample Payload
```json
{
"Payload": "A28C3==",
"Meta": {
"key": "Value"
}
}
```
### Sample Request
```text
$ curl \
https://nomad.rocks/v1/job/my-job/summary
```
### Sample Response
```json
{
"Index": 13,
"JobCreateIndex": 12,
"EvalCreateIndex": 13,
"EvalID": "e5f55fac-bc69-119d-528a-1fc7ade5e02c",
"DispatchedJobID": "example/dispatch-1485408778-81644024"
}
```
## Create Job Evaluation
This endpoint creates a new evaluation for the given job. This can be used to
force run the scheduling logic if necessary.
| Method | Path | Produces |
| ------- | -------------------------- | -------------------------- |
| `POST` | `/v1/job/:job_id/evaluate` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/index.html#blocking-queries),
[consistency modes](/api/index.html#consistency-modes), and
[required ACLs](/api/index.html#acls).
| Blocking Queries | Consistency Modes | ACL Required |
| ---------------- | ----------------- | ------------ |
| `NO` | `all` | `none` |
### 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.
### Sample Request
```text
$ curl \
--request POST \
https://nomad.rocks/v1/job/my-job/evaluate
```
### Sample Response
```json
{
"EvalID": "d092fdc0-e1fd-2536-67d8-43af8ca798ac",
"EvalCreateIndex": 35,
"JobModifyIndex": 34,
}
```
## Create Job Plan
This endpoint invokes a dry-run of the scheduler for the job.
| Method | Path | Produces |
| ------- | -------------------------- | -------------------------- |
| `POST` | `/v1/job/:job_id/plan` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/index.html#blocking-queries),
[consistency modes](/api/index.html#consistency-modes), and
[required ACLs](/api/index.html#acls).
| Blocking Queries | Consistency Modes | ACL Required |
| ---------------- | ----------------- | ------------ |
| `NO` | `all` | `none` |
### 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.
- `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.
### Sample Payload
```json
{
"Job": "...",
"Diff": true
}
```
### Sample Request
```text
$ curl \
--request POST \
--payload @payload.json \
https://nomad.rocks/v1/job/my-job/plan
```
### Sample Response
```json
{
"Index": 0,
"NextPeriodicLaunch": "0001-01-01T00:00:00Z",
"Diff": {
"Type": "Added",
"TaskGroups": [
{
"Updates": {
"create": 1
},
"Type": "Added",
"Tasks": [
{
"Type": "Added",
"Objects": [
"..."
],
"Name": "redis",
"Fields": [
{
"Type": "Added",
"Old": "",
"New": "docker",
"Name": "Driver",
"Annotations": null
},
{
"Type": "Added",
"Old": "",
"New": "5000000000",
"Name": "KillTimeout",
"Annotations": null
}
],
"Annotations": [
"forces create"
]
}
],
"Objects": [
"..."
],
"Name": "cache",
"Fields": [
"..."
]
}
],
"Objects": [
{
"Type": "Added",
"Objects": null,
"Name": "Datacenters",
"Fields": [
"..."
]
},
{
"Type": "Added",
"Objects": null,
"Name": "Constraint",
"Fields": [
"..."
]
},
{
"Type": "Added",
"Objects": null,
"Name": "Update",
"Fields": [
"..."
]
}
],
"ID": "example",
"Fields": [
"..."
]
},
"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": {
"cpu exhausted": 1
}
}
},
"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.
- `NextPeriodicLaunch`- If the job being planned is periodic, this field will
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.
- `JobModifyIndex`- The `JobModifyIndex` of the server side version of this job.
- `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
[`prohibit_overlap`](/docs/job-specification/periodic.html#prohibit_overlap)
settings. As such, this should be only used to immediately run a periodic job.
| Method | Path | Produces |
| ------- | -------------------------------- | -------------------------- |
| `POST` | `/v1/job/:job_id/periodic/force` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/index.html#blocking-queries),
[consistency modes](/api/index.html#consistency-modes), and
[required ACLs](/api/index.html#acls).
| Blocking Queries | Consistency Modes | ACL Required |
| ---------------- | ----------------- | ------------ |
| `NO` | `all` | `none` |
### 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.
### Sample Request
```text
$ curl \
--request POST \
https://nomad.rocks/v1/job/my-job/periodic/force
```
### Sample Response
```json
{
"EvalCreateIndex": 7,
"EvalID": "57983ddd-7fcf-3e3a-fd24-f699ccfb36f4"
}
```
## Delete a Job
This endpoint deregisters a job, and stops all allocations part of it.
| Method | Path | Produces |
| -------- | -------------------------- | -------------------------- |
| `DELETE` | `/v1/job/:job_id` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api/index.html#blocking-queries),
[consistency modes](/api/index.html#consistency-modes), and
[required ACLs](/api/index.html#acls).
| Blocking Queries | Consistency Modes | ACL Required |
| ---------------- | ----------------- | ------------ |
| `NO` | `all` | `none` |
### 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.
### Sample Request
```text
$ curl \
--request DELETE \
https://nomad.rocks/v1/job/my-job
```
### Sample Response
```json
{
"EvalID": "d092fdc0-e1fd-2536-67d8-43af8ca798ac",
"EvalCreateIndex": 35,
"JobModifyIndex": 34,
}
```