github.com/smintz/nomad@v0.8.3/website/source/api/deployments.html.md (about) 1 --- 2 layout: api 3 page_title: Deployments - HTTP API 4 sidebar_current: api-deployments 5 description: |- 6 The /deployment endpoints are used to query for and interact with deployments. 7 --- 8 9 # Deployments HTTP API 10 11 The `/deployment` endpoints are used to query for and interact with deployments. 12 13 ## List Deployments 14 15 This endpoint lists all deployments. 16 17 | Method | Path | Produces | 18 | ------ | ------------------------ | -------------------------- | 19 | `GET` | `/v1/deployments` | `application/json` | 20 21 The table below shows this endpoint's support for 22 [blocking queries](/api/index.html#blocking-queries) and 23 [required ACLs](/api/index.html#acls). 24 25 | Blocking Queries | ACL Required | 26 | ---------------- | -------------------- | 27 | `YES` | `namespace:read-job` | 28 29 ### Parameters 30 31 - `prefix` `(string: "")`- Specifies a string to filter deployments on based on 32 an index prefix. This is specified as a querystring parameter. 33 34 ### Sample Request 35 36 ```text 37 $ curl \ 38 https://localhost:4646/v1/deployments 39 ``` 40 41 ```text 42 $ curl \ 43 https://localhost:4646/v1/deployments?prefix=25ba81c 44 ``` 45 46 ### Sample Response 47 48 ```json 49 [ 50 { 51 "ID": "70638f62-5c19-193e-30d6-f9d6e689ab8e", 52 "JobID": "example", 53 "JobVersion": 1, 54 "JobModifyIndex": 17, 55 "JobCreateIndex": 7, 56 "TaskGroups": { 57 "cache": { 58 "Promoted": false, 59 "DesiredCanaries": 1, 60 "DesiredTotal": 3, 61 "PlacedAllocs": 1, 62 "HealthyAllocs": 0, 63 "UnhealthyAllocs": 0 64 } 65 }, 66 "Status": "running", 67 "StatusDescription": "", 68 "CreateIndex": 19, 69 "ModifyIndex": 19 70 } 71 ] 72 ``` 73 74 ## Read Deployment 75 76 This endpoint reads information about a specific deployment by ID. 77 78 | Method | Path | Produces | 79 | ------ | -------------------------------- | -------------------------- | 80 | `GET` | `/v1/deployment/:deployment_id` | `application/json` | 81 82 The table below shows this endpoint's support for 83 [blocking queries](/api/index.html#blocking-queries) and 84 [required ACLs](/api/index.html#acls). 85 86 | Blocking Queries | ACL Required | 87 | ---------------- | -------------------- | 88 | `YES` | `namespace:read-job` | 89 90 ### Parameters 91 92 - `:deployment_id` `(string: <required>)`- Specifies the UUID of the deployment. 93 This must be the full UUID, not the short 8-character one. This is specified 94 as part of the path. 95 96 ### Sample Request 97 98 ```text 99 $ curl \ 100 https://localhost:4646/v1/deployment/70638f62-5c19-193e-30d6-f9d6e689ab8e 101 ``` 102 103 ### Sample Response 104 105 ```json 106 { 107 "ID": "70638f62-5c19-193e-30d6-f9d6e689ab8e", 108 "JobID": "example", 109 "JobVersion": 1, 110 "JobModifyIndex": 17, 111 "JobCreateIndex": 7, 112 "TaskGroups": { 113 "cache": { 114 "Promoted": false, 115 "DesiredCanaries": 1, 116 "DesiredTotal": 3, 117 "PlacedAllocs": 1, 118 "HealthyAllocs": 0, 119 "UnhealthyAllocs": 0 120 } 121 }, 122 "Status": "running", 123 "StatusDescription": "", 124 "CreateIndex": 19, 125 "ModifyIndex": 19 126 } 127 ``` 128 129 ## List Allocations for Deployment 130 131 This endpoint lists the allocations created or modified for the given 132 deployment. 133 134 | Method | Path | Produces | 135 | ------ | ------------------------------------------- | -------------------------- | 136 | `GET` | `/v1/deployment/allocations/:deployment_id` | `application/json` | 137 138 The table below shows this endpoint's support for 139 [blocking queries](/api/index.html#blocking-queries) and 140 [required ACLs](/api/index.html#acls). 141 142 | Blocking Queries | ACL Required | 143 | ---------------- | -------------------- | 144 | `YES` | `namespace:read-job` | 145 146 ### Parameters 147 148 - `:deployment_id` `(string: <required>)`- Specifies the UUID of the deployment. 149 This must be the full UUID, not the short 8-character one. This is specified 150 as part of the path. 151 152 ### Sample Request 153 154 ```text 155 $ curl \ 156 https://localhost:4646/v1/deployment/allocations/5456bd7a-9fc0-c0dd-6131-cbee77f57577 157 ``` 158 159 ### Sample Response 160 161 ```json 162 [ 163 { 164 "ID": "287b65cc-6c25-cea9-0332-e4a75ca2af98", 165 "EvalID": "9751cb74-1a0d-190e-d026-ad2bc666ad2c", 166 "Name": "example.cache[0]", 167 "NodeID": "cb1f6030-a220-4f92-57dc-7baaabdc3823", 168 "JobID": "example", 169 "TaskGroup": "cache", 170 "DesiredStatus": "run", 171 "DesiredDescription": "", 172 "ClientStatus": "running", 173 "ClientDescription": "", 174 "TaskStates": { 175 "redis": { 176 "State": "running", 177 "Failed": false, 178 "StartedAt": "2017-06-29T22:29:41.52000268Z", 179 "FinishedAt": "0001-01-01T00:00:00Z", 180 "Events": [ 181 { 182 "Type": "Received", 183 "Time": 1498775380693307400, 184 "FailsTask": false, 185 "RestartReason": "", 186 "SetupError": "", 187 "DriverError": "", 188 "ExitCode": 0, 189 "Signal": 0, 190 "Message": "", 191 "KillTimeout": 0, 192 "KillError": "", 193 "KillReason": "", 194 "StartDelay": 0, 195 "DownloadError": "", 196 "ValidationError": "", 197 "DiskLimit": 0, 198 "FailedSibling": "", 199 "VaultError": "", 200 "TaskSignalReason": "", 201 "TaskSignal": "", 202 "DriverMessage": "" 203 }, 204 { 205 "Type": "Task Setup", 206 "Time": 1498775380693659000, 207 "FailsTask": false, 208 "RestartReason": "", 209 "SetupError": "", 210 "DriverError": "", 211 "ExitCode": 0, 212 "Signal": 0, 213 "Message": "Building Task Directory", 214 "KillTimeout": 0, 215 "KillError": "", 216 "KillReason": "", 217 "StartDelay": 0, 218 "DownloadError": "", 219 "ValidationError": "", 220 "DiskLimit": 0, 221 "FailedSibling": "", 222 "VaultError": "", 223 "TaskSignalReason": "", 224 "TaskSignal": "", 225 "DriverMessage": "" 226 }, 227 { 228 "Type": "Started", 229 "Time": 1498775381508493800, 230 "FailsTask": false, 231 "RestartReason": "", 232 "SetupError": "", 233 "DriverError": "", 234 "ExitCode": 0, 235 "Signal": 0, 236 "Message": "", 237 "KillTimeout": 0, 238 "KillError": "", 239 "KillReason": "", 240 "StartDelay": 0, 241 "DownloadError": "", 242 "ValidationError": "", 243 "DiskLimit": 0, 244 "FailedSibling": "", 245 "VaultError": "", 246 "TaskSignalReason": "", 247 "TaskSignal": "", 248 "DriverMessage": "" 249 } 250 ] 251 } 252 }, 253 "DeploymentStatus": null, 254 "CreateIndex": 19, 255 "ModifyIndex": 22, 256 "CreateTime": 1498775380678486300, 257 "ModifyTime": 1498775380678486300 258 } 259 ] 260 ``` 261 262 ## Fail Deployment 263 264 This endpoint is used to mark a deployment as failed. This should be done to 265 force the scheduler to stop creating allocations as part of the deployment or to 266 cause a rollback to a previous job version. This endpoint only triggers a rollback 267 if the most recent stable version of the job has a different specification than 268 the job being reverted. 269 270 | Method | Path | Produces | 271 | ------- | ------------------------------------ | -------------------------- | 272 | `POST` | `/v1/deployment/fail/:deployment_id` | `application/json` | 273 274 The table below shows this endpoint's support for 275 [blocking queries](/api/index.html#blocking-queries) and 276 [required ACLs](/api/index.html#acls). 277 278 | Blocking Queries | ACL Required | 279 | ---------------- | ---------------------- | 280 | `NO` | `namespace:submit-job` | 281 282 ### Parameters 283 284 - `:deployment_id` `(string: <required>)`- Specifies the UUID of the deployment. 285 This must be the full UUID, not the short 8-character one. This is specified 286 as part of the path. 287 288 ### Sample Request 289 290 ```text 291 $ curl \ 292 --request POST \ 293 https://localhost:4646/v1/deployment/fail/5456bd7a-9fc0-c0dd-6131-cbee77f57577 294 ``` 295 296 ### Sample Response 297 298 ```json 299 { 300 "EvalID": "0d834913-58a0-81ac-6e33-e452d83a0c66", 301 "EvalCreateIndex": 20, 302 "DeploymentModifyIndex": 20, 303 "RevertedJobVersion": 1, 304 "Index": 20 305 } 306 ``` 307 308 ## Pause Deployment 309 310 This endpoint is used to pause or unpause a deployment. This is done to pause 311 a rolling upgrade or resume it. 312 313 | Method | Path | Produces | 314 | ------- | ------------------------------------- | -------------------------- | 315 | `POST` | `/v1/deployment/pause/:deployment_id` | `application/json` | 316 317 The table below shows this endpoint's support for 318 [blocking queries](/api/index.html#blocking-queries) and 319 [required ACLs](/api/index.html#acls). 320 321 | Blocking Queries | ACL Required | 322 | ---------------- | ---------------------- | 323 | `NO` | `namespace:submit-job` | 324 325 ### Parameters 326 327 - `:deployment_id` `(string: <required>)`- Specifies the UUID of the deployment. 328 This must be the full UUID, not the short 8-character one. This is specified 329 as part of the path and in the JSON payload. 330 331 - `Pause` `(bool: false)` - Specifies whether to pause or resume the deployment. 332 333 ### Sample Payload 334 335 ```javascript 336 { 337 "DeploymentID": "5456bd7a-9fc0-c0dd-6131-cbee77f57577", 338 "Pause": true 339 } 340 ``` 341 342 ### Sample Request 343 344 ```text 345 $ curl \ 346 --request POST \ 347 https://localhost:4646/v1/deployment/pause/5456bd7a-9fc0-c0dd-6131-cbee77f57577 348 ``` 349 350 ### Sample Response 351 352 ```json 353 { 354 "EvalID": "0d834913-58a0-81ac-6e33-e452d83a0c66", 355 "EvalCreateIndex": 20, 356 "DeploymentModifyIndex": 20, 357 "Index": 20 358 } 359 ``` 360 361 ## Promote Deployment 362 363 This endpoint is used to promote task groups that have canaries for a 364 deployment. This should be done when the placed canaries are healthy and the 365 rolling upgrade of the remaining allocations should begin. 366 367 | Method | Path | Produces | 368 | ------- | ------------------------------------- | -------------------------- | 369 | `POST` | `/v1/deployment/promote/:deployment_id` | `application/json` | 370 371 The table below shows this endpoint's support for 372 [blocking queries](/api/index.html#blocking-queries) and 373 [required ACLs](/api/index.html#acls). 374 375 | Blocking Queries | ACL Required | 376 | ---------------- | ---------------------- | 377 | `NO` | `namespace:submit-job` | 378 379 ### Parameters 380 381 - `:deployment_id` `(string: <required>)`- Specifies the UUID of the deployment. 382 This must be the full UUID, not the short 8-character one. This is specified 383 as part of the path and JSON payload. 384 385 - `All` `(bool: false)` - Specifies whether all task groups should be promoted. 386 387 - `Groups` `(array<string>: nil)` - Specifies a particular set of task groups 388 that should be promoted. 389 390 ### Sample Payload 391 392 ```javascript 393 { 394 "DeploymentID": "5456bd7a-9fc0-c0dd-6131-cbee77f57577", 395 "All": true 396 } 397 ``` 398 399 ```javascript 400 { 401 "DeploymentID": "5456bd7a-9fc0-c0dd-6131-cbee77f57577", 402 "Groups": ["web", "api-server"] 403 } 404 ``` 405 406 ### Sample Request 407 408 ```text 409 $ curl \ 410 --request POST \ 411 https://localhost:4646/v1/deployment/promote/5456bd7a-9fc0-c0dd-6131-cbee77f57577 412 ``` 413 414 ### Sample Response 415 416 ```json 417 { 418 "EvalID": "0d834913-58a0-81ac-6e33-e452d83a0c66", 419 "EvalCreateIndex": 20, 420 "DeploymentModifyIndex": 20, 421 "Index": 20 422 } 423 ``` 424 425 ## Set Allocation Health in Deployment 426 427 This endpoint is used to set the health of an allocation that is in the 428 deployment manually. In some use cases, automatic detection of allocation health 429 may not be desired. As such those task groups can be marked with an upgrade 430 policy that uses `health_check = "manual"`. Those allocations must have their 431 health marked manually using this endpoint. Marking an allocation as healthy 432 will allow the rolling upgrade to proceed. Marking it as failed will cause the 433 deployment to fail. This endpoint only triggers a rollback if the most recent stable 434 version of the job has a different specification than the job being reverted. 435 436 | Method | Path | Produces | 437 | ------- | ------------------------------------------------- | -------------------------- | 438 | `POST` | `/v1/deployment/allocation-health/:deployment_id` | `application/json` | 439 440 The table below shows this endpoint's support for 441 [blocking queries](/api/index.html#blocking-queries) and 442 [required ACLs](/api/index.html#acls). 443 444 | Blocking Queries | ACL Required | 445 | ---------------- | ---------------------- | 446 | `NO` | `namespace:submit-job` | 447 448 ### Parameters 449 450 - `:deployment_id` `(string: <required>)`- Specifies the UUID of the deployment. 451 This must be the full UUID, not the short 8-character one. This is specified 452 as part of the path and the JSON payload. 453 454 - `HealthyAllocationIDs` `(array<string>: nil)` - Specifies the set of 455 allocation that should be marked as healthy. 456 457 - `UnhealthyAllocationIDs` `(array<string>: nil)` - Specifies the set of 458 allocation that should be marked as unhealthy. 459 460 ### Sample Payload 461 462 ```javascript 463 { 464 "DeploymentID": "5456bd7a-9fc0-c0dd-6131-cbee77f57577", 465 "HealthyAllocationIDs": [ 466 "eb13bc8a-7300-56f3-14c0-d4ad115ec3f5", 467 "6584dad8-7ae3-360f-3069-0b4309711cc1" 468 ] 469 } 470 ``` 471 472 ### Sample Request 473 474 ```text 475 $ curl \ 476 --request POST \ 477 https://localhost:4646/v1/deployment/allocation-health/5456bd7a-9fc0-c0dd-6131-cbee77f57577 478 ``` 479 480 ### Sample Response 481 482 ```json 483 { 484 "EvalID": "0d834913-58a0-81ac-6e33-e452d83a0c66", 485 "EvalCreateIndex": 20, 486 "DeploymentModifyIndex": 20, 487 "RevertedJobVersion": 1, 488 "Index": 20 489 } 490 ```