HashiCorp Developer AI Private beta now available Sign up today
Nomad
Nomad Home

Allocations HTTP API

The /allocation endpoints are used to query for and interact with allocations.

List Allocations

This endpoint lists all allocations.

MethodPathProduces
GET/v1/allocationsapplication/json

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

Blocking QueriesACL Required
YESnamespace: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.

  • next_token (string: "") - This endpoint supports paging. The next_token parameter accepts a string which identifies the next expected allocation. This value can be obtained from the X-Nomad-NextToken header from the previous response.

  • per_page (int: 0) - Specifies a maximum number of allocations to return for this request. If omitted, the response is not paginated. The value of the X-Nomad-NextToken header of the last response can be used as the next_token of the next request to fetch additional pages.

  • filter (string: "") - Specifies the expression used to filter the results. Consider using pagination or a query parameter to reduce resource used to serve the request.

  • namespace (string: "default") - Specifies the namespace to search. Specifying * would return all allocations across all the authorized namespaces.

  • resources (bool: false) - Specifies whether or not to include the AllocatedResources field in the response.

  • task_states (bool: true) - Specifies whether or not to include the TaskStates field in the response. TaskStates are included by default but can represent a large percentage of the overall response size. Clusters with a large number of allocations may set task_states=false to significantly reduce the size of the response.

  • reverse (bool: false) - Specifies the list of returned allocations should be sorted in the reverse order. By default allocations are returned sorted in chronological order (older evaluations first), or in lexicographical order by their ID if the prefix query parameter is used.

Sample Request

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

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

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

Sample Response

[
  {
    "ClientDescription": "Tasks are running",
    "ClientStatus": "running",
    "CreateIndex": 10,
    "CreateTime": 1636017249798459000,
    "DeploymentStatus": {
      "Canary": false,
      "Healthy": true,
      "ModifyIndex": 15,
      "Timestamp": "2021-11-04T10:14:22.054814+01:00"
    },
    "DesiredDescription": "",
    "DesiredStatus": "run",
    "DesiredTransition": {
      "ForceReschedule": null,
      "Migrate": null,
      "Reschedule": null
    },
    "EvalID": "cb20d15d-861f-8d8d-8253-e93932beea2e",
    "FollowupEvalID": "",
    "ID": "5457f16d-0f87-8e6b-5e91-0c7da3a41eb7",
    "JobID": "example",
    "JobType": "service",
    "JobVersion": 0,
    "ModifyIndex": 15,
    "ModifyTime": 1636017262190928000,
    "Name": "example.cache[0]",
    "Namespace": "default",
    "NodeID": "f476d2b4-02dc-c216-d031-273396727347",
    "NodeName": "linux",
    "PreemptedAllocations": null,
    "PreemptedByAllocation": "",
    "RescheduleTracker": null,
    "TaskGroup": "cache",
    "TaskStates": {
      "redis": {
        "Events": [
          {
            "Details": {},
            "DiskLimit": 0,
            "DisplayMessage": "Task received by client",
            "DownloadError": "",
            "DriverError": "",
            "DriverMessage": "",
            "ExitCode": 0,
            "FailedSibling": "",
            "FailsTask": false,
            "GenericSource": "",
            "KillError": "",
            "KillReason": "",
            "KillTimeout": 0,
            "Message": "",
            "RestartReason": "",
            "SetupError": "",
            "Signal": 0,
            "StartDelay": 0,
            "TaskSignal": "",
            "TaskSignalReason": "",
            "Time": 1636017249803624000,
            "Type": "Received",
            "ValidationError": "",
            "VaultError": ""
          },
          {
            "Details": {
              "message": "Building Task Directory"
            },
            "DiskLimit": 0,
            "DisplayMessage": "Building Task Directory",
            "DownloadError": "",
            "DriverError": "",
            "DriverMessage": "",
            "ExitCode": 0,
            "FailedSibling": "",
            "FailsTask": false,
            "GenericSource": "",
            "KillError": "",
            "KillReason": "",
            "KillTimeout": 0,
            "Message": "Building Task Directory",
            "RestartReason": "",
            "SetupError": "",
            "Signal": 0,
            "StartDelay": 0,
            "TaskSignal": "",
            "TaskSignalReason": "",
            "Time": 1636017249805254000,
            "Type": "Task Setup",
            "ValidationError": "",
            "VaultError": ""
          },
          {
            "Details": {},
            "DiskLimit": 0,
            "DisplayMessage": "Task started by client",
            "DownloadError": "",
            "DriverError": "",
            "DriverMessage": "",
            "ExitCode": 0,
            "FailedSibling": "",
            "FailsTask": false,
            "GenericSource": "",
            "KillError": "",
            "KillReason": "",
            "KillTimeout": 0,
            "Message": "",
            "RestartReason": "",
            "SetupError": "",
            "Signal": 0,
            "StartDelay": 0,
            "TaskSignal": "",
            "TaskSignalReason": "",
            "Time": 1636017252049956000,
            "Type": "Started",
            "ValidationError": "",
            "VaultError": ""
          }
        ],
        "Failed": false,
        "FinishedAt": null,
        "LastRestart": null,
        "Restarts": 0,
        "StartedAt": "2021-11-04T09:14:12.04996Z",
        "State": "running",
        "TaskHandle": null
      }
    }
  }
]

Read Allocation

This endpoint reads information about a specific allocation.

MethodPathProduces
GET/v1/allocation/:alloc_idapplication/json

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

Blocking QueriesACL Required
YESnamespace: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:7"
            },
            "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
    },
    "NodesInPool": 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:7"
        },
        {
          "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

  • Job - A copy of the job at the time that the allocation is created or updated. This is primarily intended for use by the Nomad client when running the allocation, and it may include stale information on some job fields. Up-to-date information about the job status is available from the jobs API; take care to fetch the version of the job associated with this allocation.

  • 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:

    • 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:

      Depending on the type the event will have applicable annotations.

Stop Allocation

This endpoint stops and reschedules a specific allocation.

MethodPathProduces
POST / PUT/v1/allocation/:alloc_id/stopapplication/json

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

Blocking QueriesACL Required
NOnamespace: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.

  • no_shutdown_delay (bool: false) - Ignore the group and task shutdown_delay configuration so that there is no delay between service deregistration and task shutdown. Note that using this parameter will result in failed network connections to the allocation being stopped.

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.

MethodPathProduces
POST / PUT/v1/client/allocation/:alloc_id/signalapplication/json

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

Blocking QueriesACL Required
NOnamespace: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"
}

If Task is omitted, the signal will be sent to all tasks in the allocation.

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.

MethodPathProduces
POST / PUT/v1/client/allocation/:alloc_id/restartapplication/json

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

Blocking QueriesACL Required
NOnamespace: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.

  • TaskName (string: "") - Specifies the individual task to restart. Cannot be used with AllTasks set to true.

  • AllTasks (bool: false) - If set to true all tasks in the allocation will be restarted, even the ones that already ran. Cannot be set to true if TaskName is defined.

Sample Payload

{
  "TaskName": "FOO"
}

Sample Request

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

Sample Response

{}

Exec Allocation

This endpoint executes a command inside the isolation container where an allocation is running. It opens a WebSocket to transmit input to and output from the command.

MethodPathProduces
WebSocket/v1/client/allocation/:alloc_id/execWebSocket JSON streams

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

Blocking QueriesACL Required
NOnamespace:alloc-exec (and namespace:alloc-node-exec if target task uses raw_exec driver)

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.
  • command (string: <required>) - Specifies the command to be executed. This must be a JSON-encoded array of the command to be executed, e.g. ["echo", "hi"] or ["/bin/bash"]. This is specified as a query parameter.
  • task (string: <required>) - Specifies the task name, as a query parameter.
  • tty (bool: false) - Specifies whether a TTY is allocated for this task, as a query parameter.
  • ws_handshake (bool: false) - Specifies whether to expect the authentication token in the first frame, as a query parameter.

Request Frames

Request frames represent the stdin stream from the command as well as TTY resize events. When ?ws_handshake=true, the first request frame must contain the authentication token.

The following are valid formats:

# sending authentication token
{"version":1,"auth_token":"fc3c1968-8d31-5c50-9617-3db2e19ef32e"}

# sending stdin data
{"stdin": {"data": "...base64 encoded string of bytes ..."}}

# indicating stdin is closed
{"stdin": {"close": true}}

# indicating that TTY was resized
{"tty_size": {"height": <characters>, "width": <characters>}}

# basic application-level heartbeat
{}

Response Frames

Response frames represent stdout and stderr output from the command as well as exit codes:

# transferring stdout data
{"stdout": {"data": "...base64 encoded string of bytes ..."}}

# signaling that host closed stdout
{"stdout": {"close": true}}

# transferring stderr data
{"stderr": {"data": "...base64 encoded string of bytes ..."}}

# signaling that host closed stderr
{"stderr": {"close": true}}

# signaling process exited
{"exited": true, "result": {"exit_code": <exit_code_int>}}

# basic application-level heartbeat
{}

Sample Request and Response

Request and response frames encompass the full range of terminal emulator inputs and outputs, including the control characters necessary to render interactive applications. The example response includes instances of the ANSI “control sequence introducer” (CSI), which is ASCII code 27 followed by [.

# \x12: form feed, to clear terminal
{"stdin":{"data":"DA=="}}

# "\x1b[H\x1b[2J$ ":
# CSI-H (move cursor to top left corner), CSI-2J (clear entire screen), print "$ "
{"stdout":{"data":"G1tIG1sySiQg"}}

Allocation Services

The endpoint is used to read all services registered within Nomad belonging to the passed allocation ID.

MethodPathProduces
GET/allocation/:alloc_id/servicesapplication/json

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

Blocking QueriesConsistency ModesACL Required
YESallnamespace:read-job

Parameters

  • :alloc_id (string: <required>) - Specifies the service name. This is specified as part of the path.

  • namespace (string: "default") - Specifies the target namespace.

Sample Request

$ curl \
    https://localhost:4646/v1/allocation/177160af-26f6-619f-9c9f-5e46d1104395/services

Sample Response

[
  {
    "Address": "127.0.0.1",
    "AllocID": "177160af-26f6-619f-9c9f-5e46d1104395",
    "CreateIndex": 14,
    "Datacenter": "dc1",
    "ID": "_nomad-task-177160af-26f6-619f-9c9f-5e46d1104395-redis-example-cache-redis-db",
    "JobID": "example",
    "ModifyIndex": 24,
    "Namespace": "default",
    "NodeID": "7406e90b-de16-d118-80fe-60d0f2730cb3",
    "Port": 29702,
    "ServiceName": "example-cache-redis",
    "Tags": [
      "db",
      "cache"
    ]
  }
]

Allocation Checks

The endpoint is used to read all health checks registered within Nomad belonging to the passed allocation ID.

MethodPathProduces
GET/allocation/:alloc_id/checksapplication/json

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

Blocking QueriesACL Required
NOnamespace:read-job

Parameters

  • :alloc_id (string: <required>) - Specifies the allocation ID. This is specified as part of the path.

Sample Request

$ curl \
    https://localhost:4646/v1/allocation/177160af-26f6-619f-9c9f-5e46d1104395/checks

Sample Response

{
  "a1ed96606694742bf201a640a607e306": {
    "Check": "redis_probe",
    "Group": "example.cache[0]",
    "ID": "a1ed96606694742bf201a640a607e306",
    "Mode": "healthiness",
    "Output": "nomad: tcp ok",
    "Service": "redis",
    "Status": "success",
    "Timestamp": 1690442203
  }
}

Override Pause Schedule State

Enterprise

This feature requires Nomad Enterprise(opens in new tab).

The endpoint is used to override the schedule for tasks using time based execution.

MethodPathProduces
POST / PUT/v1/client/allocation/:alloc_id/pauseapplication/json

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

Blocking QueriesACL Required
NOnamespace:job-submit

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.

  • Task (string: <required>) - Specifies the name of the task whose schedule should be overridden.

  • ScheduleState (string: <required>) - Specifies the pause state to force the task into. One of:

    • "pause" - Forces the task to pause.

    • "run" - Forces the task to run.

    • "scheduled" - Removes any overrides and forces the task to adhere to its schedule.

Sample Request

$ echo '{"Task": "schedtask", "ScheduleState": "run"}' | \
  nomad operator api /v1/client/allocation/23f520cc-629a-46ff-395f-0661e7aa939e/pause

Sample Response

{
  "Index": 0
}

Read Pause Schedule State

Enterprise

This feature requires Nomad Enterprise(opens in new tab).

Retrieve the schedule state for a task using time based execution.

MethodPathProduces
GET/v1/client/allocation/:alloc_id/pauseapplication/json

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

Blocking QueriesACL Required
NOnamespace: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.

  • task (string: <required>) - Specifies the name of the task from which to retrieve the time-based task execution state.

Sample Request

$ nomad operator api /v1/client/allocation/23f520cc-629a-46ff-395f-0661e7aa939e/pause?task=schedtask

Sample Response

{
  "ScheduleState": "scheduled_pause"
}

Field Reference

  • ScheduleState (string): The task's current paused state. It can can have one of the following values:

    • "" - The task is running. The only state returned for tasks with no schedule.

    • force_run - The task's schedule has been overridden to run.

    • force_pause - The task's schedule has been overridden to pause.

    • scheduled_pause - The task is paused according to its schedule.

    • schedule_resume - A schedule override is being removed. Subsequent calls should return running ("") or paused (scheduled_pause) states. This state is rarely possible to observe since it transitions immediately to another state.

Edit this page on GitHub