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

542 lines
14 KiB
Markdown
Raw Normal View History

Migrate allocations APIs
2017-05-26 23:13:42 +00:00
---
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
Remove links to consistency modes
2017-05-31 01:08:23 +00:00
[blocking queries](/api/index.html#blocking-queries) and
Migrate allocations APIs
2017-05-26 23:13:42 +00:00
[required ACLs](/api/index.html#acls).
Alloc.List ACL enforcement
2017-09-15 00:24:51 +00:00
| Blocking Queries | ACL Required |
| ---------------- | -------------------- |
| `YES` | `namespace:read-job` |
Migrate allocations APIs
2017-05-26 23:13:42 +00:00
### 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",
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.
2017-07-26 00:18:15 +00:00
"FinishedAt": "0001-01-01T00:00:00Z",
"LastRestart": "0001-01-01T00:00:00Z",
"Restarts": 0,
"StartedAt": "2017-07-25T23:36:26.106431265Z",
Migrate allocations APIs
2017-05-26 23:13:42 +00:00
"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
Remove links to consistency modes
2017-05-31 01:08:23 +00:00
[blocking queries](/api/index.html#blocking-queries) and
Migrate allocations APIs
2017-05-26 23:13:42 +00:00
[required ACLs](/api/index.html#acls).
Remove consistency modes
2017-05-31 00:31:16 +00:00
| Blocking Queries | ACL Required |
| ---------------- | ------------ |
| `YES` | `none` |
Migrate allocations APIs
2017-05-26 23:13:42 +00:00
### 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,
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.
2017-07-26 00:18:15 +00:00
"FinishedAt": "0001-01-01T00:00:00Z",
"LastRestart": "0001-01-01T00:00:00Z",
"Restarts": 0,
"StartedAt": "2017-07-25T23:36:26.106431265Z",
Migrate allocations APIs
2017-05-26 23:13:42 +00:00
"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
events
2017-07-07 06:04:42 +00:00
that have effected the state. `TaskState` objects contain the following
fields:
Migrate allocations APIs
2017-05-26 23:13:42 +00:00
events
2017-07-07 06:04:42 +00:00
- `State`: The task's current state. It can have one of the following
values:
Migrate allocations APIs
2017-05-26 23:13:42 +00:00
events
2017-07-07 06:04:42 +00:00
- `TaskStatePending` - The task is waiting to be run, either for the first
time or due to a restart.
Migrate allocations APIs
2017-05-26 23:13:42 +00:00
events
2017-07-07 06:04:42 +00:00
- `TaskStateRunning` - The task is currently running.
Migrate allocations APIs
2017-05-26 23:13:42 +00:00
events
2017-07-07 06:04:42 +00:00
- `TaskStateDead` - The task is dead and will not run again.
Migrate allocations APIs
2017-05-26 23:13:42 +00:00
events
2017-07-07 06:04:42 +00:00
- `StartedAt`: The time the task was last started at. Can be updated through
restarts.
Migrate allocations APIs
2017-05-26 23:13:42 +00:00
events
2017-07-07 06:04:42 +00:00
- `FinishedAt`: The time the task was finished at.
Migrate allocations APIs
2017-05-26 23:13:42 +00:00
events
2017-07-07 06:04:42 +00:00
- `LastRestart`: The last time the task was restarted.
Migrate allocations APIs
2017-05-26 23:13:42 +00:00
events
2017-07-07 06:04:42 +00:00
- `Restarts`: The number of times the task has restarted.
Migrate allocations APIs
2017-05-26 23:13:42 +00:00
events
2017-07-07 06:04:42 +00:00
- `Events` - An event contains metadata about the event. The latest 10 events
Spellcheck sweep of website directory Caught some typos. Made units separate from the numbers 1GHz -> 1 GHz after talking to Nick about questions of style (this has the side effect of making future spell checking easier).
2017-07-17 18:41:50 +00:00
are stored per task. Each event is timestamped (Unix nanoseconds) and has one
events
2017-07-07 06:04:42 +00:00
of the following types:
Migrate allocations APIs
2017-05-26 23:13:42 +00:00
events
2017-07-07 06:04:42 +00:00
- `Setup Failure` - The task could not be started because there was a
failure setting up the task prior to it running.
Migrate allocations APIs
2017-05-26 23:13:42 +00:00
events
2017-07-07 06:04:42 +00:00
- `Driver Failure` - The task could not be started due to a failure in the
driver.
Migrate allocations APIs
2017-05-26 23:13:42 +00:00
events
2017-07-07 06:04:42 +00:00
- `Started` - The task was started; either for the first time or due to a
restart.
Migrate allocations APIs
2017-05-26 23:13:42 +00:00
events
2017-07-07 06:04:42 +00:00
- `Terminated` - The task was started and exited.
Migrate allocations APIs
2017-05-26 23:13:42 +00:00
events
2017-07-07 06:04:42 +00:00
- `Killing` - The task has been sent the kill signal.
Migrate allocations APIs
2017-05-26 23:13:42 +00:00
an user -> a user
2017-07-07 18:04:18 +00:00
- `Killed` - The task was killed by a user.
Migrate allocations APIs
2017-05-26 23:13:42 +00:00
events
2017-07-07 06:04:42 +00:00
- `Received` - The task has been pulled by the client at the given timestamp.
Migrate allocations APIs
2017-05-26 23:13:42 +00:00
events
2017-07-07 06:04:42 +00:00
- `Failed Validation` - The task was invalid and as such it didn't run.
Migrate allocations APIs
2017-05-26 23:13:42 +00:00
events
2017-07-07 06:04:42 +00:00
- `Restarting` - The task terminated and is being restarted.
Migrate allocations APIs
2017-05-26 23:13:42 +00:00
events
2017-07-07 06:04:42 +00:00
- `Not Restarting` - the task has failed and is not being restarted because
it has exceeded its restart policy.
Migrate allocations APIs
2017-05-26 23:13:42 +00:00
events
2017-07-07 06:04:42 +00:00
- `Downloading Artifacts` - The task is downloading the artifact(s)
- specified in the task.
Migrate allocations APIs
2017-05-26 23:13:42 +00:00
events
2017-07-07 06:04:42 +00:00
- `Failed Artifact Download` - Artifact(s) specified in the task failed to
download.
Migrate allocations APIs
2017-05-26 23:13:42 +00:00
events
2017-07-07 06:04:42 +00:00
- `Restart Signaled` - The task was singled to be restarted.
Migrate allocations APIs
2017-05-26 23:13:42 +00:00
events
2017-07-07 06:04:42 +00:00
- `Signaling` - The task was is being sent a signal.
Migrate allocations APIs
2017-05-26 23:13:42 +00:00
events
2017-07-07 06:04:42 +00:00
- `Sibling Task Failed` - A task in the same task group failed.
Migrate allocations APIs
2017-05-26 23:13:42 +00:00
events
2017-07-07 06:04:42 +00:00
- `Leader Task Dead` - The group's leader task is dead.
- `Driver` - A message from the driver.
- `Task Setup` - Task setup messages.
- `Building Task Directory` - Task is building its file system.
Depending on the type the event will have applicable annotations.