• HashiCorp Developer

  • HashiCorp Cloud Platform
  • Terraform
  • Packer
  • Consul
  • Vault
  • Boundary
  • Nomad
  • Waypoint
  • Vagrant
Nomad
  • Install
  • Intro
  • Tutorials
  • Documentation
  • API
  • Tools
  • Plugins
  • Sign up
Nomad Home

API

Skip to main content
  • API

  • Libraries & SDKs
  • JSON Jobs

  • Agent
  • Allocations
  • Client
  • Deployments
  • Evaluations
  • Events
  • Jobs
  • Namespaces
  • Nodes
  • Metrics
  • Plugins
  • Quotas
  • Recommendations
  • Regions
  • Scaling Policies
  • Search
  • Sentinel Policies
  • Services
  • Status
  • System
  • UI
  • Validate
  • Variables
  • Volumes

  • Resources

  • Tutorial Library
  • Community Forum
    (opens in new tab)
  • Support
    (opens in new tab)
  • GitHub
    (opens in new tab)
  1. Developer
  2. Nomad
  3. API
  4. Deployments
  • Nomad
  • v1.3.x
  • v1.2.x
  • v1.1.x
  • v1.0.x
  • v0.12.x
  • v0.11.x

ยปDeployments HTTP API

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

List Deployments

This endpoint lists all deployments.

MethodPathProduces
GET/v1/deploymentsapplication/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 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.

MethodPathProduces
GET/v1/deployment/:deployment_idapplication/json

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

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

$ 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.

MethodPathProduces
GET/v1/deployment/allocations/:deployment_idapplication/json

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

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

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

Sample Response

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

MethodPathProduces
POST/v1/deployment/fail/:deployment_idapplication/json

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

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

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

Sample Response

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

MethodPathProduces
POST/v1/deployment/pause/:deployment_idapplication/json

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

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

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

Sample Request

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

Sample Response

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

MethodPathProduces
POST/v1/deployment/promote/:deployment_idapplication/json

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

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

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

Sample Request

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

Sample Response

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

MethodPathProduces
POST/v1/deployment/allocation-health/:deployment_idapplication/json

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

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

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

Sample Request

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

Sample Response

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

MethodPathProduces
POST/v1/deployment/unblock/:deployment_idapplication/json

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

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

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

Sample Response

{
  "EvalID": "0d834913-58a0-81ac-6e33-e452d83a0c66",
  "EvalCreateIndex": 20,
  "DeploymentModifyIndex": 20,
  "Index": 20
}
Edit this page on GitHub

On this page

  1. Deployments HTTP API
  2. List Deployments
  3. Read Deployment
  4. List Allocations for Deployment
  5. Fail Deployment
  6. Pause Deployment
  7. Promote Deployment
  8. Set Allocation Health in Deployment
  9. Unblock Deployment
Give Feedback(opens in new tab)
  • Certifications
  • System Status
  • Terms of Use
  • Security
  • Privacy
  • Trademark Policy
  • Trade Controls
  • Give Feedback(opens in new tab)