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