mirror of
https://github.com/kemko/nomad.git
synced 2026-01-03 08:55:43 +03:00
Update API and JSON Job Documentation
This PR updates the api documentation to reflect 0.6 HTTP API and the JSON job specification as well.
This commit is contained in:
Alex Dadgar
@@ -61,6 +61,10 @@ $ curl \
|
||||
"TaskStates": {
|
||||
"redis": {
|
||||
"State": "running",
|
||||
"FinishedAt": "0001-01-01T00:00:00Z",
|
||||
"LastRestart": "0001-01-01T00:00:00Z",
|
||||
"Restarts": 0,
|
||||
"StartedAt": "2017-07-25T23:36:26.106431265Z",
|
||||
"Failed": false,
|
||||
"Events": [
|
||||
{
|
||||
@@ -376,6 +380,10 @@ $ curl \
|
||||
"redis": {
|
||||
"State": "running",
|
||||
"Failed": false,
|
||||
"FinishedAt": "0001-01-01T00:00:00Z",
|
||||
"LastRestart": "0001-01-01T00:00:00Z",
|
||||
"Restarts": 0,
|
||||
"StartedAt": "2017-07-25T23:36:26.106431265Z",
|
||||
"Events": [
|
||||
{
|
||||
"Type": "Received",
|
||||
|
||||
@@ -124,6 +124,7 @@ $ curl \
|
||||
"EvalID": "",
|
||||
"EvalCreateIndex": 0,
|
||||
"JobModifyIndex": 109,
|
||||
"Warnings": "",
|
||||
"Index": 0,
|
||||
"LastContact": 0,
|
||||
"KnownLeader": false
|
||||
@@ -1250,6 +1251,7 @@ $ curl \
|
||||
{
|
||||
"Index": 0,
|
||||
"NextPeriodicLaunch": "0001-01-01T00:00:00Z",
|
||||
"Warnings": "",
|
||||
"Diff": {
|
||||
"Type": "Added",
|
||||
"TaskGroups": [
|
||||
|
||||
@@ -85,6 +85,15 @@ Below is an example of a JSON object that submits a `periodic` job to Nomad:
|
||||
]
|
||||
}
|
||||
],
|
||||
"Update": {
|
||||
"Stagger": 10000000000,
|
||||
"MaxParallel": 3,
|
||||
"HealthCheck": "checks",
|
||||
"MinHealthyTime": 15000000000,
|
||||
"HealthyDeadline": 180000000000,
|
||||
"AutoRevert": false,
|
||||
"Canary": 1
|
||||
},
|
||||
"Vault": {
|
||||
"Policies": [
|
||||
"policy-name"
|
||||
@@ -159,10 +168,6 @@ Below is an example of a JSON object that submits a `periodic` job to Nomad:
|
||||
}
|
||||
}
|
||||
],
|
||||
"Update": {
|
||||
"Stagger": 10000000000,
|
||||
"MaxParallel": 1
|
||||
},
|
||||
"Periodic": {
|
||||
"Enabled": true,
|
||||
"Spec": "- *",
|
||||
@@ -241,25 +246,10 @@ The `Job` object supports the following keys:
|
||||
and defaults to `service`. To learn more about each scheduler type visit
|
||||
[here](/docs/runtime/schedulers.html)
|
||||
|
||||
- `Update` - Specifies the task's update strategy. When omitted, rolling
|
||||
updates are disabled. The `Update` object supports the following attributes:
|
||||
|
||||
- `MaxParallel` - `MaxParallel` is given as an integer value and specifies
|
||||
the number of tasks that can be updated at the same time.
|
||||
|
||||
- `Stagger` - `Stagger` introduces a delay between sets of task updates and
|
||||
is given in nanoseconds.
|
||||
|
||||
An example `Update` block:
|
||||
|
||||
```json
|
||||
{
|
||||
"Update": {
|
||||
"MaxParallel" : 3,
|
||||
"Stagger" : 10000000000
|
||||
}
|
||||
}
|
||||
```
|
||||
- `Update` - Specifies an update strategy to be applied to all task groups
|
||||
within the job. When specified both at the job level and the task group level,
|
||||
the update blocks are merged with the task group's taking precedence. For more
|
||||
details on the update stanza, please see below.
|
||||
|
||||
- `Periodic` - `Periodic` allows the job to be scheduled at fixed times, dates
|
||||
or intervals. The periodic expression is always evaluated in the UTC
|
||||
@@ -323,6 +313,11 @@ attributes:
|
||||
- `EphemeralDisk` - Specifies the group's ephemeral disk requirements. See the
|
||||
[ephemeral disk reference](#ephemeral_disk) for more details.
|
||||
|
||||
- `Update` - Specifies an update strategy to be applied to all task groups
|
||||
within the job. When specified both at the job level and the task group level,
|
||||
the update blocks are merged with the task group's taking precedence. For more
|
||||
details on the update stanza, please see below.
|
||||
|
||||
- `Tasks` - A list of `Task` object that are part of the task group.
|
||||
|
||||
### Task
|
||||
@@ -520,6 +515,70 @@ The `RestartPolicy` object supports the following keys:
|
||||
|
||||
- `fail` - `fail` will not restart the task again.
|
||||
|
||||
### Update
|
||||
|
||||
Specifies the task group update strategy. When omitted, rolling updates are
|
||||
disabled. The update stanza can be specified at the job or task group level.
|
||||
When specified at the job, the update stanza is inherited by all task groups.
|
||||
When specified in both the job and in a task group, the stanzas are merged with
|
||||
the task group's taking precedence. The `Update` object supports the following
|
||||
attributes:
|
||||
|
||||
- `MaxParallel` - `MaxParallel` is given as an integer value and specifies
|
||||
the number of tasks that can be updated at the same time.
|
||||
|
||||
- `HealthCheck` - Specifies the mechanism in which allocations health is
|
||||
determined. The potential values are:
|
||||
|
||||
- "checks" - Specifies that the allocation should be considered healthy when
|
||||
all of its tasks are running and their associated [checks][] are healthy,
|
||||
and unhealthy if any of the tasks fail or not all checks become healthy.
|
||||
This is a superset of "task_states" mode.
|
||||
|
||||
- "task_states" - Specifies that the allocation should be considered healthy
|
||||
when all its tasks are running and unhealthy if tasks fail.
|
||||
|
||||
- "manual" - Specifies that Nomad should not automatically determine health
|
||||
and that the operator will specify allocation health using the [HTTP
|
||||
API](/api/deployments.html#set-allocation-health-in-deployment).
|
||||
|
||||
- `MinHealthyTime` - Specifies the minimum time the allocation must be in the
|
||||
healthy state before it is marked as healthy and unblocks further allocations
|
||||
from being updated. This is specified using a label suffix like "30s" or
|
||||
"15m".
|
||||
|
||||
- `HealthyDeadline` - Specifies the deadline in which the allocation must be
|
||||
marked as healthy after which the allocation is automatically transitioned to
|
||||
unhealthy. This is specified using a label suffix like "2m" or "1h".
|
||||
|
||||
- `AutoRevert` - Specifies if the job should auto-revert to the last stable job
|
||||
on deployment failure. A job is marked as stable if all the allocations as
|
||||
part of its deployment were marked healthy.
|
||||
|
||||
- `Canary` - Specifies that changes to the job that would result in destructive
|
||||
updates should create the specified number of canaries without stopping any
|
||||
previous allocations. Once the operator determines the canaries are healthy,
|
||||
they can be promoted which unblocks a rolling update of the remaining
|
||||
allocations at a rate of `max_parallel`.
|
||||
|
||||
- `Stagger` - Specifies the delay between migrating allocations off nodes marked
|
||||
for draining. This is specified using a label suffix like "30s" or "1h".
|
||||
|
||||
An example `Update` block:
|
||||
|
||||
```json
|
||||
{
|
||||
"Update": {
|
||||
"MaxParallel": 3,
|
||||
"HealthCheck": "checks",
|
||||
"MinHealthyTime": 15000000000,
|
||||
"HealthyDeadline": 180000000000,
|
||||
"AutoRevert": false,
|
||||
"Canary": 1
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Constraint
|
||||
|
||||
The `Constraint` object supports the following keys:
|
||||
@@ -724,6 +783,9 @@ README][ct].
|
||||
or `EmbeddedTmpl` must be specified, but not both. This is useful for smaller
|
||||
templates, but we recommend using `SourcePath` for larger templates.
|
||||
|
||||
- `Envvars` - Specifies the template should be read back as environment
|
||||
variables for the task.
|
||||
|
||||
- `LeftDelim` - Specifies the left delimiter to use in the template. The default
|
||||
is "{{" for some templates, it may be easier to use a different delimiter that
|
||||
does not conflict with the output file itself.
|
||||
@@ -759,7 +821,6 @@ README][ct].
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
[ct]: https://github.com/hashicorp/consul-template "Consul Template by HashiCorp"
|
||||
|
||||
@@ -58,6 +58,7 @@ $ curl \
|
||||
"ValidationErrors": [
|
||||
"Task group cache validation failed: 1 error(s) occurred:\n\n* Task redis validation failed: 1 error(s) occurred:\n\n* 1 error(s) occurred:\n\n* minimum CPU value is 20; got 1"
|
||||
],
|
||||
"Warnings": "1 warning(s):\n\n* Group \"cache\" has warnings: 1 error(s) occurred:\n\n* Update max parallel count is greater than task group count (13 > 1). A destructive change would result in the simultaneous replacement of all allocations.",
|
||||
"Error": "1 error(s) occurred:\n\n* Task group cache validation failed: 1 error(s) occurred:\n\n* Task redis validation failed: 1 error(s) occurred:\n\n* 1 error(s) occurred:\n\n* minimum CPU value is 20; got 1"
|
||||
}
|
||||
```
|
||||
|
||||
@@ -57,81 +57,116 @@ web running Started 29/03/16 03:04:53 UTC
|
||||
Full status of an alloc, which shows one of the tasks dying and then being restarted:
|
||||
|
||||
```
|
||||
$ nomad alloc-status a7365fe4
|
||||
ID = a7365fe4
|
||||
Eval ID = c3c9a1db
|
||||
Name = example.cache[0]
|
||||
Node ID = 1f029d38
|
||||
Job ID = example
|
||||
Client Status = running
|
||||
Created At = 29/03/16 03:04:53 UTC
|
||||
$ nomad alloc-status cfe85e72
|
||||
ID = cfe85e72
|
||||
Eval ID = cdc88569
|
||||
Name = example.cache[0]
|
||||
Node ID = bfd3aa86
|
||||
Job ID = example
|
||||
Job Version = 1
|
||||
Client Status = running
|
||||
Client Description = <none>
|
||||
Desired Status = run
|
||||
Desired Description = <none>
|
||||
Created At = 07/25/17 23:42:01 UTC
|
||||
Deployment ID = dd162708
|
||||
Deployment Health = unset
|
||||
Canary = true
|
||||
|
||||
==> Task Resources
|
||||
Task: "redis"
|
||||
CPU Memory MB Disk MB IOPS Addresses
|
||||
500 256 300 0 db: 127.0.0.1:46321
|
||||
Task "redis" is "running"
|
||||
Task Resources
|
||||
CPU Memory Disk IOPS Addresses
|
||||
4/500 MHz 6.3 MiB/256 MiB 300 MiB 0 db: 127.0.0.1:20055
|
||||
|
||||
Task: "web"
|
||||
CPU Memory MB Disk MB IOPS Addresses
|
||||
500 256 300 0 db: 127.0.0.1:38537
|
||||
Task Events:
|
||||
Started At = 07/25/17 23:42:02 UTC
|
||||
Finished At = N/A
|
||||
Total Restarts = 0
|
||||
Last Restart = N/A
|
||||
|
||||
==> Task "redis" is "running"
|
||||
Recent Events:
|
||||
Time Type Description
|
||||
29/03/16 03:04:53 UTC Started Task started by client
|
||||
29/03/16 03:04:51 UTC Received Task received by client
|
||||
|
||||
==> Task "web" is "pending"
|
||||
Recent Events:
|
||||
Time Type Description
|
||||
29/03/16 03:07:18 UTC Restarting Task restarting in 18.580059474s
|
||||
29/03/16 03:07:18 UTC Terminated Exit Code: 137, Exit Message: "Docker container exited with non-zero exit code: 137"
|
||||
29/03/16 03:04:53 UTC Started Task started by client
|
||||
29/03/16 03:04:51 UTC Received Task received by client
|
||||
07/25/17 23:42:02 UTC Started Task started by client
|
||||
07/25/17 23:42:01 UTC Task Setup Building Task Directory
|
||||
07/25/17 23:42:01 UTC Received Task received by client
|
||||
|
||||
Task "web" is "running"
|
||||
Task Resources
|
||||
CPU Memory Disk IOPS Addresses
|
||||
5/500 MHz 6.3 MiB/256 MiB 300 MiB 0 db: 127.0.0.1:28235
|
||||
|
||||
Task Events:
|
||||
Started At = 07/25/17 23:42:02 UTC
|
||||
Finished At = N/A
|
||||
Total Restarts = 0
|
||||
Last Restart = N/A
|
||||
|
||||
Recent Events:
|
||||
Time Type Description
|
||||
07/25/17 23:42:02 UTC Started Task started by client
|
||||
07/25/17 23:42:01 UTC Task Setup Building Task Directory
|
||||
07/25/17 23:42:01 UTC Received Task received by client
|
||||
```
|
||||
|
||||
Verbose status can also be accessed:
|
||||
|
||||
```
|
||||
$ nomad alloc-status --verbose a7365fe4
|
||||
ID = a7365fe4-cb28-a6e9-f3d4-f99e49c89776
|
||||
Eval ID = c3c9a1db-dbeb-8afa-0a83-4f1b8b5a03f5
|
||||
Name = example.cache[0]
|
||||
Node ID = 1f029d38-8d4b-a552-261f-e457b60f9b4b
|
||||
Job ID = example
|
||||
Client Status = running
|
||||
Created At = 29/03/16 03:04:53 UTC
|
||||
Evaluated Nodes = 1
|
||||
Filtered Nodes = 0
|
||||
Exhausted Nodes = 0
|
||||
Allocation Time = 1.085001ms
|
||||
Failures = 0
|
||||
$ nomad alloc-status --verbose cfe85e72
|
||||
ID = cfe85e72-220e-cb14-edfc-432602ac0981
|
||||
Eval ID = cdc88569-bbc3-5549-855f-c0db59d4d4d3
|
||||
Name = example.cache[0]
|
||||
Node ID = bfd3aa86-ecbf-0f6c-b234-0f4d35792543
|
||||
Job ID = example
|
||||
Job Version = 1
|
||||
Client Status = running
|
||||
Client Description = <none>
|
||||
Desired Status = run
|
||||
Desired Description = <none>
|
||||
Created At = 07/25/17 23:42:01 UTC
|
||||
Deployment ID = dd162708-d810-a761-53b9-cfb1dc8637e8
|
||||
Deployment Health = healthy
|
||||
Canary = true
|
||||
Evaluated Nodes = 1
|
||||
Filtered Nodes = 0
|
||||
Exhausted Nodes = 0
|
||||
Allocation Time = 152.016µs
|
||||
Failures = 0
|
||||
|
||||
==> Task Resources
|
||||
Task: "web"
|
||||
CPU Memory MB Disk MB IOPS Addresses
|
||||
500 256 300 0 db: 127.0.0.1:38537
|
||||
Task "redis" is "running"
|
||||
Task Resources
|
||||
CPU Memory Disk IOPS Addresses
|
||||
2/500 MHz 6.3 MiB/256 MiB 300 MiB 0 db: 127.0.0.1:20055
|
||||
|
||||
Task: "redis"
|
||||
CPU Memory MB Disk MB IOPS Addresses
|
||||
500 256 300 0 db: 127.0.0.1:46321
|
||||
Task Events:
|
||||
Started At = 07/25/17 23:42:02 UTC
|
||||
Finished At = N/A
|
||||
Total Restarts = 0
|
||||
Last Restart = N/A
|
||||
|
||||
==> Task "redis" is "running"
|
||||
Recent Events:
|
||||
Time Type Description
|
||||
29/03/16 03:04:53 UTC Started Task started by client
|
||||
29/03/16 03:04:51 UTC Received Task received by client
|
||||
|
||||
==> Task "web" is "running"
|
||||
Recent Events:
|
||||
Time Type Description
|
||||
29/03/16 03:07:38 UTC Started Task started by client
|
||||
29/03/16 03:07:18 UTC Restarting Task restarting in 18.580059474s
|
||||
29/03/16 03:07:18 UTC Terminated Exit Code: 137, Exit Message: "Docker container exited with non-zero exit code: 137"
|
||||
29/03/16 03:04:53 UTC Started Task started by client
|
||||
29/03/16 03:04:51 UTC Received Task received by client
|
||||
07/25/17 23:42:02 UTC Started Task started by client
|
||||
07/25/17 23:42:01 UTC Task Setup Building Task Directory
|
||||
07/25/17 23:42:01 UTC Received Task received by client
|
||||
|
||||
==> Status
|
||||
Allocation "13901f26-cb28-a6e9-f3d4-f99e49c89776" status "running" (0/1 nodes filtered)
|
||||
* Score "1f029d38-8d4b-a552-261f-e457b60f9b4b.binpack" = 10.334026
|
||||
Task "web" is "running"
|
||||
Task Resources
|
||||
CPU Memory Disk IOPS Addresses
|
||||
4/500 MHz 6.3 MiB/256 MiB 300 MiB 0 db: 127.0.0.1:28235
|
||||
|
||||
Task Events:
|
||||
Started At = 07/25/17 23:42:02 UTC
|
||||
Finished At = N/A
|
||||
Total Restarts = 0
|
||||
Last Restart = N/A
|
||||
|
||||
Recent Events:
|
||||
Time Type Description
|
||||
07/25/17 23:42:02 UTC Started Task started by client
|
||||
07/25/17 23:42:01 UTC Task Setup Building Task Directory
|
||||
07/25/17 23:42:01 UTC Received Task received by client
|
||||
|
||||
Placement Metrics
|
||||
* Score "bfd3aa86-ecbf-0f6c-b234-0f4d35792543.binpack" = 9.142490
|
||||
* Score "bfd3aa86-ecbf-0f6c-b234-0f4d35792543.job-anti-affinity" = -20.000000
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user