github.com/anth0d/nomad@v0.0.0-20221214183521-ae3a0a2cad06/website/content/api-docs/deployments.mdx

---
layout: api
page_title: Deployments - HTTP API
description: The /deployment endpoints are used to query for and interact with deployments.
---

# Deployments HTTP API

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

## List Deployments

This endpoint lists all deployments.

| Method | Path              | Produces           |
| ------ | ----------------- | ------------------ |
| `GET`  | `/v1/deployments` | `application/json` |

The table below shows this endpoint's support for
[blocking queries](/api-docs#blocking-queries) and
[required ACLs](/api-docs#acls).

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

### 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](/api-docs#filtering)
  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

```shell-session
$ curl \
    https://localhost:4646/v1/deployments
```

```shell-session
$ curl \
    https://localhost:4646/v1/deployments?prefix=25ba81c
```

### Sample Response

```json
[
  {
    "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.

| Method | Path                            | Produces           |
| ------ | ------------------------------- | ------------------ |
| `GET`  | `/v1/deployment/:deployment_id` | `application/json` |

The table below shows this endpoint's support for
[blocking queries](/api-docs#blocking-queries) and
[required ACLs](/api-docs#acls).

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

### 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

```shell-session
$ curl \
    https://localhost:4646/v1/deployment/70638f62-5c19-193e-30d6-f9d6e689ab8e
```

### Sample Response

```json
{
  "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.

| Method | Path                                        | Produces           |
| ------ | ------------------------------------------- | ------------------ |
| `GET`  | `/v1/deployment/allocations/:deployment_id` | `application/json` |

The table below shows this endpoint's support for
[blocking queries](/api-docs#blocking-queries) and
[required ACLs](/api-docs#acls).

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

### 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

```shell-session
$ curl \
    https://localhost:4646/v1/deployment/allocations/5456bd7a-9fc0-c0dd-6131-cbee77f57577
```

### Sample Response

```json
[
  {
    "ID": "287b65cc-6c25-cea9-0332-e4a75ca2af98",
    "EvalID": "9751cb74-1a0d-190e-d026-ad2bc666ad2c",
    "Name": "example.cache[0]",
    "NodeID": "cb1f6030-a220-4f92-57dc-7baaabdc3823",
    "JobID": "example",
    "TaskGroup": "cache",
    "DesiredStatus": "run",
    "DesiredDescription": "",
    "ClientStatus": "running",
    "ClientDescription": "",
    "TaskStates": {
      "redis": {
        "State": "running",
        "Failed": false,
        "StartedAt": "2017-06-29T22:29:41.52000268Z",
        "FinishedAt": "0001-01-01T00:00:00Z",
        "Events": [
          {
            "Type": "Received",
            "Time": 1498775380693307400,
            "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": "Task Setup",
            "Time": 1498775380693659000,
            "FailsTask": false,
            "RestartReason": "",
            "SetupError": "",
            "DriverError": "",
            "ExitCode": 0,
            "Signal": 0,
            "Message": "Building Task Directory",
            "KillTimeout": 0,
            "KillError": "",
            "KillReason": "",
            "StartDelay": 0,
            "DownloadError": "",
            "ValidationError": "",
            "DiskLimit": 0,
            "FailedSibling": "",
            "VaultError": "",
            "TaskSignalReason": "",
            "TaskSignal": "",
            "DriverMessage": ""
          },
          {
            "Type": "Started",
            "Time": 1498775381508493800,
            "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": ""
          }
        ]
      }
    },
    "DeploymentStatus": null,
    "CreateIndex": 19,
    "ModifyIndex": 22,
    "CreateTime": 1498775380678486300,
    "ModifyTime": 1498775380678486300
  }
]
```

## Fail Deployment

This endpoint is used to mark a deployment as failed. This should be done to
force the scheduler to stop creating allocations as part of the deployment or to
cause a rollback to a previous job version. This endpoint only triggers a rollback
if the most recent stable version of the job has a different specification than
the job being reverted.

| Method | Path                                 | Produces           |
| ------ | ------------------------------------ | ------------------ |
| `POST` | `/v1/deployment/fail/:deployment_id` | `application/json` |

The table below shows this endpoint's support for
[blocking queries](/api-docs#blocking-queries) and
[required ACLs](/api-docs#acls).

| Blocking Queries | ACL Required           |
| ---------------- | ---------------------- |
| `NO`             | `namespace:submit-job` |

### 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

```shell-session
$ curl \
    --request POST \
    https://localhost:4646/v1/deployment/fail/5456bd7a-9fc0-c0dd-6131-cbee77f57577
```

### Sample Response

```json
{
  "EvalID": "0d834913-58a0-81ac-6e33-e452d83a0c66",
  "EvalCreateIndex": 20,
  "DeploymentModifyIndex": 20,
  "RevertedJobVersion": 1,
  "Index": 20
}
```

## Pause Deployment

This endpoint is used to pause or unpause a deployment. This is done to pause
a rolling upgrade or resume it.

| Method | Path                                  | Produces           |
| ------ | ------------------------------------- | ------------------ |
| `POST` | `/v1/deployment/pause/:deployment_id` | `application/json` |

The table below shows this endpoint's support for
[blocking queries](/api-docs#blocking-queries) and
[required ACLs](/api-docs#acls).

| Blocking Queries | ACL Required           |
| ---------------- | ---------------------- |
| `NO`             | `namespace:submit-job` |

### 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 and in the JSON payload.

- `Pause` `(bool: false)` - Specifies whether to pause or resume the deployment.

### Sample Payload

```javascript
{
  "DeploymentID": "5456bd7a-9fc0-c0dd-6131-cbee77f57577",
  "Pause": true
}
```

### Sample Request

```shell-session
$ curl \
    --request POST \
    https://localhost:4646/v1/deployment/pause/5456bd7a-9fc0-c0dd-6131-cbee77f57577
```

### Sample Response

```json
{
  "EvalID": "0d834913-58a0-81ac-6e33-e452d83a0c66",
  "EvalCreateIndex": 20,
  "DeploymentModifyIndex": 20,
  "Index": 20
}
```

## Promote Deployment

This endpoint is used to promote task groups that have canaries for a
deployment. This should be done when the placed canaries are healthy and the
rolling upgrade of the remaining allocations should begin.

| Method | Path                                    | Produces           |
| ------ | --------------------------------------- | ------------------ |
| `POST` | `/v1/deployment/promote/:deployment_id` | `application/json` |

The table below shows this endpoint's support for
[blocking queries](/api-docs#blocking-queries) and
[required ACLs](/api-docs#acls).

| Blocking Queries | ACL Required           |
| ---------------- | ---------------------- |
| `NO`             | `namespace:submit-job` |

### 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 and JSON payload.

- `All` `(bool: false)` - Specifies whether all task groups should be promoted.

- `Groups` `(array<string>: nil)` - Specifies a particular set of task groups
  that should be promoted.

### Sample Payload

```javascript
{
  "DeploymentID": "5456bd7a-9fc0-c0dd-6131-cbee77f57577",
  "All": true
}
```

```javascript
{
  "DeploymentID": "5456bd7a-9fc0-c0dd-6131-cbee77f57577",
  "Groups": ["web", "api-server"]
}
```

### Sample Request

```shell-session
$ curl \
    --request POST \
    https://localhost:4646/v1/deployment/promote/5456bd7a-9fc0-c0dd-6131-cbee77f57577
```

### Sample Response

```json
{
  "EvalID": "0d834913-58a0-81ac-6e33-e452d83a0c66",
  "EvalCreateIndex": 20,
  "DeploymentModifyIndex": 20,
  "Index": 20
}
```

## Set Allocation Health in Deployment

This endpoint is used to set the health of an allocation that is in the
deployment manually. In some use cases, automatic detection of allocation health
may not be desired. As such those task groups can be marked with an upgrade
policy that uses `health_check = "manual"`. Those allocations must have their
health marked manually using this endpoint. Marking an allocation as healthy
will allow the rolling upgrade to proceed. Marking it as failed will cause the
deployment to fail. This endpoint only triggers a rollback if the most recent stable
version of the job has a different specification than the job being reverted.

| Method | Path                                              | Produces           |
| ------ | ------------------------------------------------- | ------------------ |
| `POST` | `/v1/deployment/allocation-health/:deployment_id` | `application/json` |

The table below shows this endpoint's support for
[blocking queries](/api-docs#blocking-queries) and
[required ACLs](/api-docs#acls).

| Blocking Queries | ACL Required           |
| ---------------- | ---------------------- |
| `NO`             | `namespace:submit-job` |

### 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 and the JSON payload.

- `HealthyAllocationIDs` `(array<string>: nil)` - Specifies the set of
  allocation that should be marked as healthy.

- `UnhealthyAllocationIDs` `(array<string>: nil)` - Specifies the set of
  allocation that should be marked as unhealthy.

### Sample Payload

```javascript
{
  "DeploymentID": "5456bd7a-9fc0-c0dd-6131-cbee77f57577",
  "HealthyAllocationIDs": [
    "eb13bc8a-7300-56f3-14c0-d4ad115ec3f5",
    "6584dad8-7ae3-360f-3069-0b4309711cc1"
  ]
}
```

### Sample Request

```shell-session
$ curl \
    --request POST \
    https://localhost:4646/v1/deployment/allocation-health/5456bd7a-9fc0-c0dd-6131-cbee77f57577
```

### Sample Response

```json
{
  "EvalID": "0d834913-58a0-81ac-6e33-e452d83a0c66",
  "EvalCreateIndex": 20,
  "DeploymentModifyIndex": 20,
  "RevertedJobVersion": 1,
  "Index": 20
}
```

## Unblock Deployment

This endpoint is used to manually mark a blocked multiregion deployment as
successful. A blocked deployment is a multiregion deployment within a region
that has completed within a region but is waiting on the other federated
regions. The endpoint can be used in cases where a failed peer region is
unable to communicate its failed deployment status to other regions to force a
deployment to complete.

| Method | Path                                    | Produces           |
| ------ | --------------------------------------- | ------------------ |
| `POST` | `/v1/deployment/unblock/:deployment_id` | `application/json` |

The table below shows this endpoint's support for
[blocking queries](/api-docs#blocking-queries) and
[required ACLs](/api-docs#acls).

| Blocking Queries | ACL Required           |
| ---------------- | ---------------------- |
| `NO`             | `namespace:submit-job` |

### 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

```shell-session
$ curl \
    --request POST \
    https://localhost:4646/v1/deployment/unblock/5456bd7a-9fc0-c0dd-6131-cbee77f57577
```

### Sample Response

```json
{
  "EvalID": "0d834913-58a0-81ac-6e33-e452d83a0c66",
  "EvalCreateIndex": 20,
  "DeploymentModifyIndex": 20,
  "Index": 20
}
```