luxolus/open-nomad
2
0
Fork 0
Code Issues 1 Pull requests Packages Releases Wiki Activity

Migrate allocations APIs

Browse source
This commit is contained in:
Seth Vargo 2017-05-26 19:13:42 -04:00
parent 8883972d70
commit e0ec7787a2
No known key found for this signature in database
GPG key ID: C921994F9C27E0FF
3 changed files with 526 additions and 367 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

526
website/source/api/allocations.html.md Normal file
View file

@ -0,0 +1,526 @@
---
layout: api
page_title: Allocations - HTTP API
sidebar_current: api-allocations
description: |-
The /allocation endpoints are used to query for and interact with allocations.
---
# Allocations HTTP API
The `/allocation` endpoints are used to query for and interact with allocations.
## List Allocations
This endpoint lists all allocations.
| Method | Path | Produces |
| ------ | ------------------------- | -------------------------- |
| `GET` | `/v1/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
- `prefix` `(string: "")`- Specifies a string to filter allocations on based on
an index prefix. This is specified as a querystring parameter.
### Sample Request
```text
$ curl \
https://nomad.rocks/v1/allocations
```
```text
$ curl \
https://nomad.rocks/v1/allocations?prefix=a8198d79
```
### Sample Response
```json
[
{
"ID": "a8198d79-cfdb-6593-a999-1e9adabcba2e",
"EvalID": "5456bd7a-9fc0-c0dd-6131-cbee77f57577",
"Name": "example.cache[0]",
"NodeID": "fb2170a8-257d-3c64-b14d-bc06cc94e34c",
"JobID": "example",
"TaskGroup": "cache",
"DesiredStatus": "run",
"DesiredDescription": "",
"ClientStatus": "running",
"ClientDescription": "",
"TaskStates": {
"redis": {
"State": "running",
"Failed": false,
"Events": [
{
"Type": "Received",
"Time": 1495747371795703800,
"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": "Driver",
"Time": 1495747371798867200,
"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": 1495747379525667800,
"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": 54,
"ModifyIndex": 57,
"CreateTime": 1495747371794276400
}
]
```
## Read Allocation
This endpoint reads information about a specific allocation.
| Method | Path | Produces |
| ------ | -------------------------- | -------------------------- |
| `GET` | `/v1/allocation/:alloc_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
- `:alloc_id` `(string: <required>)`- Specifies the UUID of the allocation. This
must be the full UUID, not the short 8-character one. This is specified as
part of the path.
### Sample Request
```text
$ curl \
https://nomad.rocks/v1/allocation/5456bd7a-9fc0-c0dd-6131-cbee77f57577
```
### Sample Response
```json
{
"ID": "a8198d79-cfdb-6593-a999-1e9adabcba2e",
"EvalID": "5456bd7a-9fc0-c0dd-6131-cbee77f57577",
"Name": "example.cache[0]",
"NodeID": "fb2170a8-257d-3c64-b14d-bc06cc94e34c",
"JobID": "example",
"Job": {
"Region": "global",
"ID": "example",
"ParentID": "",
"Name": "example",
"Type": "service",
"Priority": 50,
"AllAtOnce": false,
"Datacenters": [
"dc1"
],
"Constraints": null,
"TaskGroups": [
{
"Name": "cache",
"Count": 1,
"Constraints": null,
"RestartPolicy": {
"Attempts": 10,
"Interval": 300000000000,
"Delay": 25000000000,
"Mode": "delay"
},
"Tasks": [
{
"Name": "redis",
"Driver": "docker",
"User": "",
"Config": {
"port_map": [
{
"db": 6379
}
],
"image": "redis:3.2"
},
"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": ""
}
]
}
],
"Vault": null,
"Templates": null,
"Constraints": null,
"Resources": {
"CPU": 500,
"MemoryMB": 10,
"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": 0
},
"Periodic": null,
"ParameterizedJob": null,
"Payload": null,
"Meta": null,
"VaultToken": "",
"Status": "pending",
"StatusDescription": "",
"CreateIndex": 52,
"ModifyIndex": 52,
"JobModifyIndex": 52
},
"TaskGroup": "cache",
"Resources": {
"CPU": 500,
"MemoryMB": 10,
"DiskMB": 300,
"IOPS": 0,
"Networks": [
{
"Device": "lo0",
"CIDR": "",
"IP": "127.0.0.1",
"MBits": 10,
"ReservedPorts": null,
"DynamicPorts": [
{
"Label": "db",
"Value": 23116
}
]
}
]
},
"SharedResources": {
"CPU": 0,
"MemoryMB": 0,
"DiskMB": 300,
"IOPS": 0,
"Networks": null
},
"TaskResources": {
"redis": {
"CPU": 500,
"MemoryMB": 10,
"DiskMB": 0,
"IOPS": 0,
"Networks": [
{
"Device": "lo0",
"CIDR": "",
"IP": "127.0.0.1",
"MBits": 10,
"ReservedPorts": null,
"DynamicPorts": [
{
"Label": "db",
"Value": 23116
}
]
}
]
}
},
"Metrics": {
"NodesEvaluated": 1,
"NodesFiltered": 0,
"NodesAvailable": {
"dc1": 1
},
"ClassFiltered": null,
"ConstraintFiltered": null,
"NodesExhausted": 0,
"ClassExhausted": null,
"DimensionExhausted": null,
"Scores": {
"fb2170a8-257d-3c64-b14d-bc06cc94e34c.binpack": 0.6205732522109244
},
"AllocationTime": 31729,
"CoalescedFailures": 0
},
"DesiredStatus": "run",
"DesiredDescription": "",
"ClientStatus": "running",
"ClientDescription": "",
"TaskStates": {
"redis": {
"State": "running",
"Failed": false,
"Events": [
{
"Type": "Received",
"Time": 1495747371795703800,
"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": "Driver",
"Time": 1495747371798867200,
"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": 1495747379525667800,
"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": ""
}
]
}
},
"PreviousAllocation": "",
"CreateIndex": 54,
"ModifyIndex": 57,
"AllocModifyIndex": 54,
"CreateTime": 1495747371794276400
}
```
#### Field Reference
- `TaskStates` - A map of tasks to their current state and the latest events
that have effected the state.
A task can be in the following states:
- `TaskStatePending` - The task is waiting to be run, either for the first
time or due to a restart.
- `TaskStateRunning` - The task is currently running.
- `TaskStateDead` - The task is dead and will not run again.
Further the state contains the `StartedAt` and `FinishedAt` times of the
task. `StartedAt` can be updated multiple times if the task restarts but
`FinishedAt` is set only when the task transitions to `TaskStateDead`
- `Events` - An event contains metadata about the event. The latest 10 events
are stored per task. Each event is timestamped (unix nano-seconds) and has one
of the following types:
- `Setup Failure` - The task could not be started because there was a
failure setting up the task prior to it running.
- `Driver Failure` - The task could not be started due to a failure in the
driver.
- `Started` - The task was started; either for the first time or due to a
restart.
- `Terminated` - The task was started and exited.
- `Killing` - The task has been sent the kill signal.
- `Killed` - The task was killed by an user.
- `Received` - The task has been pulled by the client at the given timestamp.
- `Failed Validation` - The task was invalid and as such it didn't run.
- `Restarting` - The task terminated and is being restarted.
- `Not Restarting` - the task has failed and is not being restarted because
it has exceeded its restart policy.
- `Downloading Artifacts` - The task is downloading the artifact(s)
- specified in the task.
- `Failed Artifact Download` - Artifact(s) specified in the task failed to
download.
- `Restart Signaled` - The task was singled to be restarted.
- `Signaling` - The task was is being sent a signal.
- `Sibling Task Failed` - A task in the same task group failed.
- `Leader Task Dead` - The group's leader task is dead.
- `Driver` - A message from the driver.
- `Task Setup` - Task setup messages.
Depending on the type the event will have applicable annotations.

281
website/source/docs/http/alloc.html.md
View file

@ -1,281 +0,0 @@
---
layout: "http"
page_title: "HTTP API: /v1/allocation"
sidebar_current: "docs-http-alloc-"
description: |-
The '/1/allocation' endpoint is used to query a specific allocation.
---
# /v1/allocation
The `allocation` endpoint is used to query a specific allocation.
By default, the agent's local region is used; another region can
be specified using the `?region=` query parameter.
## GET
<dl>
<dt>Description</dt>
<dd>
Query a specific allocation.
</dd>
<dt>Method</dt>
<dd>GET</dd>
<dt>URL</dt>
<dd>`/v1/allocation/<ID>`</dd>
<dt>Parameters</dt>
<dd>
None
</dd>
<dt>Blocking Queries</dt>
<dd>
[Supported](/docs/http/index.html#blocking-queries)
</dd>
<dt>Returns</dt>
<dd>
```javascript
{
"ID": "203266e5-e0d6-9486-5e05-397ed2b184af",
"EvalID": "e68125ed-3fba-fb46-46cc-291addbc4455",
"Name": "example.cache[0]",
"NodeID": "e02b6169-83bd-9df6-69bd-832765f333eb",
"JobID": "example",
"ModifyIndex": 9,
"Resources": {
"Networks": [
{
"DynamicPorts": [
{
"Value": 20802,
"Label": "db"
}
],
"ReservedPorts": null,
"MBits": 10,
"IP": "",
"CIDR": "",
"Device": ""
}
],
"IOPS": 0,
"DiskMB": 0,
"MemoryMB": 256,
"CPU": 500
},
"TaskGroup": "cache",
"Job": {
"ModifyIndex": 5,
"CreateIndex": 5,
"StatusDescription": "",
"Status": "",
"Meta": null,
"Update": {
"MaxParallel": 1,
"Stagger": 1e+10
},
"TaskGroups": [
{
"Meta": null,
"Tasks": [
{
"Meta": null,
"Resources": {
"Networks": [
{
"DynamicPorts": [
{
"Value": 20802,
"Label": "db"
}
],
"ReservedPorts": null,
"MBits": 0,
"IP": "127.0.0.1",
"CIDR": "",
"Device": "lo"
}
],
"IOPS": 0,
"DiskMB": 0,
"MemoryMB": 256,
"CPU": 500
},
"Constraints": null,
"Services": [
{
"Checks": [
{
"Timeout": 2e+09,
"Interval": 1e+10,
"Protocol": "",
"Http": "",
"Script": "",
"Type": "tcp",
"Name": "alive",
"Id": ""
}
],
"PortLabel": "db",
"Tags": [
"global",
"cache"
],
"Name": "example-cache-redis",
"Id": ""
}
],
"Env": null,
"Config": {
"port_map": [
{
"db": 6379
}
],
"image": "redis:latest"
},
"Driver": "docker",
"Name": "redis"
}
],
"RestartPolicy": {
"Delay": 2.5e+10,
"Interval": 3e+11,
"Attempts": 10
},
"Constraints": null,
"Count": 1,
"Name": "cache"
}
],
"Region": "global",
"ID": "example",
"Name": "example",
"Type": "service",
"Priority": 50,
"AllAtOnce": false,
"Datacenters": [
"dc1"
],
"Constraints": [
{
"Operand": "=",
"RTarget": "linux",
"LTarget": "${attr.kernel.name}"
}
]
},
"TaskResources": {
"redis": {
"Networks": [
{
"DynamicPorts": [
{
"Value": 20802,
"Label": "db"
}
],
"ReservedPorts": null,
"MBits": 0,
"IP": "127.0.0.1",
"CIDR": "",
"Device": "lo"
}
],
"IOPS": 0,
"DiskMB": 0,
"MemoryMB": 256,
"CPU": 500
}
},
"Metrics": {
"CoalescedFailures": 0,
"AllocationTime": 1590406,
"NodesEvaluated": 1,
"NodesFiltered": 0,
"ClassFiltered": null,
"ConstraintFiltered": null,
"NodesExhausted": 0,
"ClassExhausted": null,
"DimensionExhausted": null,
"Scores": {
"e02b6169-83bd-9df6-69bd-832765f333eb.binpack": 6.133651487695705
}
},
"DesiredStatus": "run",
"DesiredDescription": "",
"ClientStatus": "running",
"ClientDescription": "",
"TaskStates": {
"redis": {
"Events": [
{
"KillError": "",
"Message": "",
"Signal": 0,
"ExitCode": 0,
"DriverError": "",
"Time": 1447806038427841000,
"Type": "Started"
}
],
"State": "running"
"FinishedAt": "0001-01-01T00:00:00Z",
"StartedAt": "2017-03-31T22:51:40.248633594Z",
"Failed": false,
}
},
"CreateIndex": 7
}
```
</dd>
</dl>
### Field Reference
* `TaskStates` - `TaskStates` is a map of tasks to their current state and the
latest events that have effected the state.
A task can be in the following states:
* `TaskStatePending` - The task is waiting to be run, either for the first
time or due to a restart.
* `TaskStateRunning` - The task is currently running.
* `TaskStateDead` - The task is dead and will not run again.
Further the state contains the `StartedAt` and `FinishedAt` times of the
task. `StartedAt` can be updated multiple times if the task restarts but
`FinishedAt` is set only when the task transistions to `TaskStateDead`
<p>The latest 10 events are stored per task. Each event is timestamped (unix nano-seconds)
and has one of the following types:</p>
* `Setup Failure` - The task could not be started because there was a
failure setting up the task prior to it running.
* `Driver Failure` - The task could not be started due to a failure in the
driver.
* `Started` - The task was started; either for the first time or due to a
restart.
* `Terminated` - The task was started and exited.
* `Killing` - The task has been sent the kill signal.
* `Killed` - The task was killed by an user.
* `Received` - The task has been pulled by the client at the given timestamp.
* `Failed Validation` - The task was invalid and as such it didn't run.
* `Restarting` - The task terminated and is being restarted.
* `Not Restarting` - the task has failed and is not being restarted because it has exceeded its restart policy.
* `Downloading Artifacts` - The task is downloading the artifact(s) specified in the task.
* `Failed Artifact Download` - Artifact(s) specified in the task failed to download.
* `Restart Signaled` - The task was signalled to be restarted.
* `Signaling` - The task was is being sent a signal.
* `Sibling Task Failed` - A task in the same task group failed.
* `Leader Task Dead` - The group's leader task is dead.
* `Driver` - A message from the driver.
* `Task Setup` - Task setup messages.
Depending on the type the event will have applicable annotations.

86
website/source/docs/http/allocs.html.md
View file

@ -1,86 +0,0 @@
---
layout: "http"
page_title: "HTTP API: /v1/allocations"
sidebar_current: "docs-http-allocs"
description: |-
The '/1/allocations' endpoint is used to list the allocations.
---
# /v1/allocations
The `allocations` endpoint is used to query the status of allocations.
By default, the agent's local region is used; another region can
be specified using the `?region=` query parameter.
## GET
<dl>
<dt>Description</dt>
<dd>
Lists all the allocations.
</dd>
<dt>Method</dt>
<dd>GET</dd>
<dt>URL</dt>
<dd>`/v1/allocations`</dd>
<dt>Parameters</dt>
<dd>
<ul>
<li>
<span class="param">prefix</span>
<span class="param-flags">optional</span>
<span class="param-flags">even-length</span>
Filter allocations based on an identifier prefix.
</li>
</ul>
</dd>
<dt>Blocking Queries</dt>
<dd>
[Supported](/docs/http/index.html#blocking-queries)
</dd>
<dt>Returns</dt>
<dd>
```javascript
[
{
"ID": "203266e5-e0d6-9486-5e05-397ed2b184af",
"EvalID": "e68125ed-3fba-fb46-46cc-291addbc4455",
"Name": "example.cache[0]",
"NodeID": "e02b6169-83bd-9df6-69bd-832765f333eb",
"JobID": "example",
"TaskGroup": "cache",
"DesiredStatus": "run",
"DesiredDescription": ""
"ClientDescription": "",
"ClientStatus": "running",
"TaskStates": {
"redis": {
"Events": [
{
"KillError": "",
"Message": "",
"Signal": 0,
"ExitCode": 0,
"DriverError": "",
"Time": 1447806038427841000,
"Type": "Started"
}
],
"State": "running"
}
},
"CreateIndex": 7,
"ModifyIndex": 9,
}
...
]
```
</dd>
</dl>