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 and required ACLs.

Blocking Queries	ACL Required
`YES`	`namespace:read-job`

Parameters

prefix (string: "")- Specifies a string to filter allocations based on an ID prefix. Because the value is decoded to bytes, the prefix must have an even number of hexadecimal characters (0-9a-f). This is specified as a query string parameter.

Sample Request

$ curl \    https://localhost:4646/v1/allocations

$ curl \    https://localhost:4646/v1/allocations?prefix=a8198d79

Sample Response

[  {    "ID": "a8198d79-cfdb-6593-a999-1e9adabcba2e",    "EvalID": "5456bd7a-9fc0-c0dd-6131-cbee77f57577",    "Name": "example.cache[0]",    "NodeID": "fb2170a8-257d-3c64-b14d-bc06cc94e34c",    "PreviousAllocation": "516d2753-0513-cfc7-57ac-2d6fac18b9dc",    "NextAllocation": "cd13d9b9-4f97-7184-c88b-7b451981616b",    "RescheduleTracker": {      "Events": [        {          "PrevAllocID": "516d2753-0513-cfc7-57ac-2d6fac18b9dc",          "PrevNodeID": "9230cd3b-3bda-9a3f-82f9-b2ea8dedb20e",          "RescheduleTime": 1517434161192946200,          "Delay": "5000000000"        }      ]    },    "JobID": "example",    "TaskGroup": "cache",    "DesiredStatus": "run",    "DesiredDescription": "",    "ClientStatus": "running",    "ClientDescription": "",    "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": [          {            "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,    "ModifyTime": 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 and required ACLs.

Blocking Queries	ACL Required
`YES`	`namespace:read-job`

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

$ curl \    https://localhost:4646/v1/allocation/5456bd7a-9fc0-c0dd-6131-cbee77f57577

Sample Response

{  "ID": "a8198d79-cfdb-6593-a999-1e9adabcba2e",  "EvalID": "5456bd7a-9fc0-c0dd-6131-cbee77f57577",  "Name": "example.cache[0]",  "NodeID": "fb2170a8-257d-3c64-b14d-bc06cc94e34c",  "PreviousAllocation": "516d2753-0513-cfc7-57ac-2d6fac18b9dc",  "NextAllocation": "cd13d9b9-4f97-7184-c88b-7b451981616b",  "RescheduleTracker": {    "Events": [      {        "PrevAllocID": "516d2753-0513-cfc7-57ac-2d6fac18b9dc",        "PrevNodeID": "9230cd3b-3bda-9a3f-82f9-b2ea8dedb20e",        "RescheduleTime": 1517434161192946200,        "Delay": "5000000000"      }    ]  },  "JobID": "example",  "Job": {    "Region": "global",    "ID": "example",    "ParentID": "",    "Name": "example",    "Type": "service",    "Priority": 50,    "AllAtOnce": false,    "Datacenters": ["dc1"],    "Constraints": null,    "Affinities": null,    "TaskGroups": [      {        "Name": "cache",        "Count": 1,        "Constraints": null,        "Affinities": null,        "RestartPolicy": {          "Attempts": 10,          "Interval": 300000000000,          "Delay": 25000000000,          "Mode": "delay"        },        "Spreads": null,        "Tasks": [          {            "Name": "redis",            "Driver": "docker",            "User": "",            "Config": {              "port_map": [                {                  "db": 6379                }              ],              "image": "redis:3.2"            },            "Env": null,            "Services": [              {                "Name": "redis-cache",                "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,            "Affinities": null,            "Resources": {              "CPU": 500,              "MemoryMB": 10,              "DiskMB": 0,              "Networks": [                {                  "Device": "",                  "CIDR": "",                  "IP": "",                  "MBits": 10,                  "ReservedPorts": null,                  "DynamicPorts": [                    {                      "Label": "db",                      "Value": 0                    }                  ]                }              ]            },            "Spreads": null,            "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,    "Spreads": null,    "Meta": null,    "VaultToken": "",    "Status": "pending",    "StatusDescription": "",    "CreateIndex": 52,    "ModifyIndex": 52,    "JobModifyIndex": 52  },  "TaskGroup": "cache",  "Resources": {    "CPU": 500,    "MemoryMB": 10,    "DiskMB": 300,    "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,    "Networks": null  },  "TaskResources": {    "redis": {      "CPU": 500,      "MemoryMB": 10,      "DiskMB": 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,      "FinishedAt": "0001-01-01T00:00:00Z",      "LastRestart": "0001-01-01T00:00:00Z",      "Restarts": 0,      "StartedAt": "2017-07-25T23:36:26.106431265Z",      "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,  "ModifyTime": 1495747371794276400}

Field Reference

TaskStates - A map of tasks to their current state and the latest events that have effected the state. TaskState objects contain the following fields:
- State: The task's current state. It can have one of the following values:
  - 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.
- StartedAt: The time the task was last started at. Can be updated through restarts.
- FinishedAt: The time the task was finished at.
- LastRestart: The last time the task was restarted.
- Restarts: The number of times the task has restarted.
- Events - An event contains metadata about the event. The latest 10 events are stored per task. Each event is timestamped (Unix nanoseconds) 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 a 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.
  - Building Task Directory - Task is building its file system.
  Depending on the type the event will have applicable annotations.

Stop Allocation

This endpoint stops and reschedules a specific allocation.

Method	Path	Produces
`POST` / `PUT`	`/v1/allocation/:alloc_id/stop`	`application/json`

The table below shows this endpoint's support for blocking queries and required ACLs.

Blocking Queries	ACL Required
`NO`	`namespace:alloc-lifecycle`

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

$ curl -X POST \    https://localhost:4646/v1/allocation/5456bd7a-9fc0-c0dd-6131-cbee77f57577/stop

Sample Response

{  "EvalID": "5456bd7a-9fc0-c0dd-6131-cbee77f57577",  "Index": 54}

Signal Allocation

This endpoint sends a signal to an allocation or task.

Method	Path	Produces
`POST` / `PUT`	`/v1/client/allocation/:alloc_id/signal`	`application/json`

The table below shows this endpoint's support for blocking queries and required ACLs.

Blocking Queries	ACL Required
`NO`	`namespace:alloc-lifecycle`

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 Payload

{  "Signal": "SIGUSR1",  "Task": "FOO"}

Sample Request

$ curl -X POST -d '{"Signal": "SIGUSR1" }' \    https://localhost:4646/v1/client/allocation/5456bd7a-9fc0-c0dd-6131-cbee77f57577/signal

Sample Response

{}

Restart Allocation

This endpoint restarts an allocation or task in-place.

Method	Path	Produces
`POST` / `PUT`	`/v1/client/allocation/:alloc_id/restart`	`application/json`

The table below shows this endpoint's support for blocking queries and required ACLs.

Blocking Queries	ACL Required
`NO`	`namespace:alloc-lifecycle`

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 Payload

{  "Task": "FOO"}

Sample Request

$ curl -X POST -d '{"Task": "redis" }' \    https://localhost:4646/v1/client/allocation/5456bd7a-9fc0-c0dd-6131-cbee77f57577/restart

Sample Response

{}