Deployments HTTP API

The /deployment endpoints are used to query for and interact with deployments.

List Deployments

This endpoint lists all deployments.

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

Parameters

• prefix (string: "")- Specifies a string to filter deployments 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 and is used before any filter expression is applied.

• namespace (string: "default") - Specifies the target namespace. Specifying * will return all evaluations across all authorized namespaces. This parameter is used before any filter expression is applied.

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

• per_page (int: 0) - Specifies a maximum number of deployments to return for this request. If omitted, the response is not paginated. The ID of the last deployment in the response can be used as the last_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.

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

Sample Request

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

$ curl \
    https://localhost:4646/v1/deployments?prefix=25ba81c

Sample Response

[
  {
    "ID": "70638f62-5c19-193e-30d6-f9d6e689ab8e",
    "JobID": "example",
    "JobVersion": 1,
    "JobModifyIndex": 17,
    "JobSpecModifyIndex": 17,
    "JobCreateIndex": 7,
    "TaskGroups": {
      "cache": {
        "Promoted": false,
        "DesiredCanaries": 1,
        "DesiredTotal": 3,
        "PlacedAllocs": 1,
        "HealthyAllocs": 0,
        "UnhealthyAllocs": 0
      }
    },
    "Status": "running",
    "StatusDescription": "",
    "CreateIndex": 19,
    "ModifyIndex": 19
  }
]

Read Deployment

This endpoint reads information about a specific deployment by ID.

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

Parameters

• :deployment_id (string: <required>)- Specifies the UUID of the deployment. 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/deployment/70638f62-5c19-193e-30d6-f9d6e689ab8e

Sample Response

{
  "ID": "70638f62-5c19-193e-30d6-f9d6e689ab8e",
  "JobID": "example",
  "JobVersion": 1,
  "JobModifyIndex": 17,
  "JobSpecModifyIndex": 17,
  "JobCreateIndex": 7,
  "TaskGroups": {
    "cache": {
      "Promoted": false,
      "DesiredCanaries": 1,
      "DesiredTotal": 3,
      "PlacedAllocs": 1,
      "HealthyAllocs": 0,
      "UnhealthyAllocs": 0
    }
  },
  "Status": "running",
  "StatusDescription": "",
  "CreateIndex": 19,
  "ModifyIndex": 19
}

List Allocations for Deployment

This endpoint lists the allocations created or modified for the given deployment.

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

Parameters

• :deployment_id (string: <required>)- Specifies the UUID of the deployment. 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/deployment/allocations/5456bd7a-9fc0-c0dd-6131-cbee77f57577

Sample Response

[
  {
    "ID"