github.com/ferranbt/nomad@v0.9.3-0.20190607002617-85c449b7667c/website/source/api/allocations.html.md (about) 1 --- 2 layout: api 3 page_title: Allocations - HTTP API 4 sidebar_current: api-allocations 5 description: |- 6 The /allocation endpoints are used to query for and interact with allocations. 7 --- 8 9 # Allocations HTTP API 10 11 The `/allocation` endpoints are used to query for and interact with allocations. 12 13 ## List Allocations 14 15 This endpoint lists all allocations. 16 17 | Method | Path | Produces | 18 | ------ | ------------------------- | -------------------------- | 19 | `GET` | `/v1/allocations` | `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 allocations on based on 32 an index prefix. This is specified as a query string parameter. 33 34 ### Sample Request 35 36 ```text 37 $ curl \ 38 https://localhost:4646/v1/allocations 39 ``` 40 41 ```text 42 $ curl \ 43 https://localhost:4646/v1/allocations?prefix=a8198d79 44 ``` 45 46 ### Sample Response 47 48 ```json 49 [ 50 { 51 "ID": "a8198d79-cfdb-6593-a999-1e9adabcba2e", 52 "EvalID": "5456bd7a-9fc0-c0dd-6131-cbee77f57577", 53 "Name": "example.cache[0]", 54 "NodeID": "fb2170a8-257d-3c64-b14d-bc06cc94e34c", 55 "PreviousAllocation": "516d2753-0513-cfc7-57ac-2d6fac18b9dc", 56 "NextAllocation": "cd13d9b9-4f97-7184-c88b-7b451981616b", 57 "RescheduleTracker": { 58 "Events": [ 59 { 60 "PrevAllocID": "516d2753-0513-cfc7-57ac-2d6fac18b9dc", 61 "PrevNodeID": "9230cd3b-3bda-9a3f-82f9-b2ea8dedb20e", 62 "RescheduleTime": 1517434161192946200, 63 "Delay":"5000000000" 64 }, 65 ] 66 }, 67 "JobID": "example", 68 "TaskGroup": "cache", 69 "DesiredStatus": "run", 70 "DesiredDescription": "", 71 "ClientStatus": "running", 72 "ClientDescription": "", 73 "TaskStates": { 74 "redis": { 75 "State": "running", 76 "FinishedAt": "0001-01-01T00:00:00Z", 77 "LastRestart": "0001-01-01T00:00:00Z", 78 "Restarts": 0, 79 "StartedAt": "2017-07-25T23:36:26.106431265Z", 80 "Failed": false, 81 "Events": [ 82 { 83 "Type": "Received", 84 "Time": 1495747371795703800, 85 "FailsTask": false, 86 "RestartReason": "", 87 "SetupError": "", 88 "DriverError": "", 89 "ExitCode": 0, 90 "Signal": 0, 91 "Message": "", 92 "KillTimeout": 0, 93 "KillError": "", 94 "KillReason": "", 95 "StartDelay": 0, 96 "DownloadError": "", 97 "ValidationError": "", 98 "DiskLimit": 0, 99 "FailedSibling": "", 100 "VaultError": "", 101 "TaskSignalReason": "", 102 "TaskSignal": "", 103 "DriverMessage": "" 104 }, 105 { 106 "Type": "Driver", 107 "Time": 1495747371798867200, 108 "FailsTask": false, 109 "RestartReason": "", 110 "SetupError": "", 111 "DriverError": "", 112 "ExitCode": 0, 113 "Signal": 0, 114 "Message": "", 115 "KillTimeout": 0, 116 "KillError": "", 117 "KillReason": "", 118 "StartDelay": 0, 119 "DownloadError": "", 120 "ValidationError": "", 121 "DiskLimit": 0, 122 "FailedSibling": "", 123 "VaultError": "", 124 "TaskSignalReason": "", 125 "TaskSignal": "", 126 "DriverMessage": "Downloading image redis:3.2" 127 }, 128 { 129 "Type": "Started", 130 "Time": 1495747379525667800, 131 "FailsTask": false, 132 "RestartReason": "", 133 "SetupError": "", 134 "DriverError": "", 135 "ExitCode": 0, 136 "Signal": 0, 137 "Message": "", 138 "KillTimeout": 0, 139 "KillError": "", 140 "KillReason": "", 141 "StartDelay": 0, 142 "DownloadError": "", 143 "ValidationError": "", 144 "DiskLimit": 0, 145 "FailedSibling": "", 146 "VaultError": "", 147 "TaskSignalReason": "", 148 "TaskSignal": "", 149 "DriverMessage": "" 150 } 151 ] 152 } 153 }, 154 "CreateIndex": 54, 155 "ModifyIndex": 57, 156 "CreateTime": 1495747371794276400, 157 "ModifyTime": 1495747371794276400 158 } 159 ] 160 ``` 161 162 ## Read Allocation 163 164 This endpoint reads information about a specific allocation. 165 166 | Method | Path | Produces | 167 | ------ | -------------------------- | -------------------------- | 168 | `GET` | `/v1/allocation/:alloc_id` | `application/json` | 169 170 The table below shows this endpoint's support for 171 [blocking queries](/api/index.html#blocking-queries) and 172 [required ACLs](/api/index.html#acls). 173 174 | Blocking Queries | ACL Required | 175 | ---------------- | -------------------- | 176 | `YES` | `namespace:read-job` | 177 178 ### Parameters 179 180 - `:alloc_id` `(string: <required>)`- Specifies the UUID of the allocation. This 181 must be the full UUID, not the short 8-character one. This is specified as 182 part of the path. 183 184 ### Sample Request 185 186 ```text 187 $ curl \ 188 https://localhost:4646/v1/allocation/5456bd7a-9fc0-c0dd-6131-cbee77f57577 189 ``` 190 191 ### Sample Response 192 193 ```json 194 { 195 "ID": "a8198d79-cfdb-6593-a999-1e9adabcba2e", 196 "EvalID": "5456bd7a-9fc0-c0dd-6131-cbee77f57577", 197 "Name": "example.cache[0]", 198 "NodeID": "fb2170a8-257d-3c64-b14d-bc06cc94e34c", 199 "PreviousAllocation": "516d2753-0513-cfc7-57ac-2d6fac18b9dc", 200 "NextAllocation": "cd13d9b9-4f97-7184-c88b-7b451981616b", 201 "RescheduleTracker": { 202 "Events": [ 203 { 204 "PrevAllocID": "516d2753-0513-cfc7-57ac-2d6fac18b9dc", 205 "PrevNodeID": "9230cd3b-3bda-9a3f-82f9-b2ea8dedb20e", 206 "RescheduleTime": 1517434161192946200, 207 "Delay":"5000000000" 208 }, 209 ] 210 }, 211 "JobID": "example", 212 "Job": { 213 "Region": "global", 214 "ID": "example", 215 "ParentID": "", 216 "Name": "example", 217 "Type": "service", 218 "Priority": 50, 219 "AllAtOnce": false, 220 "Datacenters": [ 221 "dc1" 222 ], 223 "Constraints": null, 224 "Affinities": null, 225 "TaskGroups": [ 226 { 227 "Name": "cache", 228 "Count": 1, 229 "Constraints": null, 230 "Affinities": null, 231 "RestartPolicy": { 232 "Attempts": 10, 233 "Interval": 300000000000, 234 "Delay": 25000000000, 235 "Mode": "delay" 236 }, 237 "Spreads": null, 238 "Tasks": [ 239 { 240 "Name": "redis", 241 "Driver": "docker", 242 "User": "", 243 "Config": { 244 "port_map": [ 245 { 246 "db": 6379 247 } 248 ], 249 "image": "redis:3.2" 250 }, 251 "Env": null, 252 "Services": [ 253 { 254 "Name": "redis-cache", 255 "PortLabel": "db", 256 "Tags": [ 257 "global", 258 "cache" 259 ], 260 "Checks": [ 261 { 262 "Name": "alive", 263 "Type": "tcp", 264 "Command": "", 265 "Args": null, 266 "Path": "", 267 "Protocol": "", 268 "PortLabel": "", 269 "Interval": 10000000000, 270 "Timeout": 2000000000, 271 "InitialStatus": "" 272 } 273 ] 274 } 275 ], 276 "Vault": null, 277 "Templates": null, 278 "Constraints": null, 279 "Affinities": null, 280 "Resources": { 281 "CPU": 500, 282 "MemoryMB": 10, 283 "DiskMB": 0, 284 "Networks": [ 285 { 286 "Device": "", 287 "CIDR": "", 288 "IP": "", 289 "MBits": 10, 290 "ReservedPorts": null, 291 "DynamicPorts": [ 292 { 293 "Label": "db", 294 "Value": 0 295 } 296 ] 297 } 298 ] 299 }, 300 "Spreads": null, 301 "DispatchPayload": null, 302 "Meta": null, 303 "KillTimeout": 5000000000, 304 "LogConfig": { 305 "MaxFiles": 10, 306 "MaxFileSizeMB": 10 307 }, 308 "Artifacts": null, 309 "Leader": false 310 } 311 ], 312 "EphemeralDisk": { 313 "Sticky": false, 314 "SizeMB": 300, 315 "Migrate": false 316 }, 317 "Meta": null 318 } 319 ], 320 "Update": { 321 "Stagger": 10000000000, 322 "MaxParallel": 0 323 }, 324 "Periodic": null, 325 "ParameterizedJob": null, 326 "Payload": null, 327 "Spreads": null, 328 "Meta": null, 329 "VaultToken": "", 330 "Status": "pending", 331 "StatusDescription": "", 332 "CreateIndex": 52, 333 "ModifyIndex": 52, 334 "JobModifyIndex": 52 335 }, 336 "TaskGroup": "cache", 337 "Resources": { 338 "CPU": 500, 339 "MemoryMB": 10, 340 "DiskMB": 300, 341 "Networks": [ 342 { 343 "Device": "lo0", 344 "CIDR": "", 345 "IP": "127.0.0.1", 346 "MBits": 10, 347 "ReservedPorts": null, 348 "DynamicPorts": [ 349 { 350 "Label": "db", 351 "Value": 23116 352 } 353 ] 354 } 355 ] 356 }, 357 "SharedResources": { 358 "CPU": 0, 359 "MemoryMB": 0, 360 "DiskMB": 300, 361 "Networks": null 362 }, 363 "TaskResources": { 364 "redis": { 365 "CPU": 500, 366 "MemoryMB": 10, 367 "DiskMB": 0, 368 "Networks": [ 369 { 370 "Device": "lo0", 371 "CIDR": "", 372 "IP": "127.0.0.1", 373 "MBits": 10, 374 "ReservedPorts": null, 375 "DynamicPorts": [ 376 { 377 "Label": "db", 378 "Value": 23116 379 } 380 ] 381 } 382 ] 383 } 384 }, 385 "Metrics": { 386 "NodesEvaluated": 1, 387 "NodesFiltered": 0, 388 "NodesAvailable": { 389 "dc1": 1 390 }, 391 "ClassFiltered": null, 392 "ConstraintFiltered": null, 393 "NodesExhausted": 0, 394 "ClassExhausted": null, 395 "DimensionExhausted": null, 396 "Scores": { 397 "fb2170a8-257d-3c64-b14d-bc06cc94e34c.binpack": 0.6205732522109244 398 }, 399 "AllocationTime": 31729, 400 "CoalescedFailures": 0 401 }, 402 "DesiredStatus": "run", 403 "DesiredDescription": "", 404 "ClientStatus": "running", 405 "ClientDescription": "", 406 "TaskStates": { 407 "redis": { 408 "State": "running", 409 "Failed": false, 410 "FinishedAt": "0001-01-01T00:00:00Z", 411 "LastRestart": "0001-01-01T00:00:00Z", 412 "Restarts": 0, 413 "StartedAt": "2017-07-25T23:36:26.106431265Z", 414 "Events": [ 415 { 416 "Type": "Received", 417 "Time": 1495747371795703800, 418 "FailsTask": false, 419 "RestartReason": "", 420 "SetupError": "", 421 "DriverError": "", 422 "ExitCode": 0, 423 "Signal": 0, 424 "Message": "", 425 "KillTimeout": 0, 426 "KillError": "", 427 "KillReason": "", 428 "StartDelay": 0, 429 "DownloadError": "", 430 "ValidationError": "", 431 "DiskLimit": 0, 432 "FailedSibling": "", 433 "VaultError": "", 434 "TaskSignalReason": "", 435 "TaskSignal": "", 436 "DriverMessage": "" 437 }, 438 { 439 "Type": "Driver", 440 "Time": 1495747371798867200, 441 "FailsTask": false, 442 "RestartReason": "", 443 "SetupError": "", 444 "DriverError": "", 445 "ExitCode": 0, 446 "Signal": 0, 447 "Message": "", 448 "KillTimeout": 0, 449 "KillError": "", 450 "KillReason": "", 451 "StartDelay": 0, 452 "DownloadError": "", 453 "ValidationError": "", 454 "DiskLimit": 0, 455 "FailedSibling": "", 456 "VaultError": "", 457 "TaskSignalReason": "", 458 "TaskSignal": "", 459 "DriverMessage": "Downloading image redis:3.2" 460 }, 461 { 462 "Type": "Started", 463 "Time": 1495747379525667800, 464 "FailsTask": false, 465 "RestartReason": "", 466 "SetupError": "", 467 "DriverError": "", 468 "ExitCode": 0, 469 "Signal": 0, 470 "Message": "", 471 "KillTimeout": 0, 472 "KillError": "", 473 "KillReason": "", 474 "StartDelay": 0, 475 "DownloadError": "", 476 "ValidationError": "", 477 "DiskLimit": 0, 478 "FailedSibling": "", 479 "VaultError": "", 480 "TaskSignalReason": "", 481 "TaskSignal": "", 482 "DriverMessage": "" 483 } 484 ] 485 } 486 }, 487 "PreviousAllocation": "", 488 "CreateIndex": 54, 489 "ModifyIndex": 57, 490 "AllocModifyIndex": 54, 491 "CreateTime": 1495747371794276400, 492 "ModifyTime": 1495747371794276400 493 } 494 ``` 495 496 #### Field Reference 497 498 - `TaskStates` - A map of tasks to their current state and the latest events 499 that have effected the state. `TaskState` objects contain the following 500 fields: 501 502 - `State`: The task's current state. It can have one of the following 503 values: 504 505 - `TaskStatePending` - The task is waiting to be run, either for the first 506 time or due to a restart. 507 508 - `TaskStateRunning` - The task is currently running. 509 510 - `TaskStateDead` - The task is dead and will not run again. 511 512 - `StartedAt`: The time the task was last started at. Can be updated through 513 restarts. 514 515 - `FinishedAt`: The time the task was finished at. 516 517 - `LastRestart`: The last time the task was restarted. 518 519 - `Restarts`: The number of times the task has restarted. 520 521 - `Events` - An event contains metadata about the event. The latest 10 events 522 are stored per task. Each event is timestamped (Unix nanoseconds) and has one 523 of the following types: 524 525 - `Setup Failure` - The task could not be started because there was a 526 failure setting up the task prior to it running. 527 528 - `Driver Failure` - The task could not be started due to a failure in the 529 driver. 530 531 - `Started` - The task was started; either for the first time or due to a 532 restart. 533 534 - `Terminated` - The task was started and exited. 535 536 - `Killing` - The task has been sent the kill signal. 537 538 - `Killed` - The task was killed by a user. 539 540 - `Received` - The task has been pulled by the client at the given timestamp. 541 542 - `Failed Validation` - The task was invalid and as such it didn't run. 543 544 - `Restarting` - The task terminated and is being restarted. 545 546 - `Not Restarting` - the task has failed and is not being restarted because 547 it has exceeded its restart policy. 548 549 - `Downloading Artifacts` - The task is downloading the artifact(s) 550 - specified in the task. 551 552 - `Failed Artifact Download` - Artifact(s) specified in the task failed to 553 download. 554 555 - `Restart Signaled` - The task was singled to be restarted. 556 557 - `Signaling` - The task was is being sent a signal. 558 559 - `Sibling Task Failed` - A task in the same task group failed. 560 561 - `Leader Task Dead` - The group's leader task is dead. 562 563 - `Driver` - A message from the driver. 564 565 - `Task Setup` - Task setup messages. 566 567 - `Building Task Directory` - Task is building its file system. 568 569 Depending on the type the event will have applicable annotations. 570 571 ## Stop Allocation 572 573 This endpoint stops and reschedules a specific allocation. 574 575 | Method | Path | Produces | 576 | ------ | -------------------------- | -------------------------- | 577 | `POST` / `PUT` | `/v1/allocation/:alloc_id/stop` | `application/json` | 578 579 The table below shows this endpoint's support for 580 [blocking queries](/api/index.html#blocking-queries) and 581 [required ACLs](/api/index.html#acls). 582 583 | Blocking Queries | ACL Required | 584 | ---------------- | -------------------- | 585 | `NO` | `namespace:alloc-lifecycle` | 586 587 ### Parameters 588 589 - `:alloc_id` `(string: <required>)`- Specifies the UUID of the allocation. This 590 must be the full UUID, not the short 8-character one. This is specified as 591 part of the path. 592 593 ### Sample Request 594 595 ```text 596 $ curl -X POST \ 597 https://localhost:4646/v1/allocation/5456bd7a-9fc0-c0dd-6131-cbee77f57577/stop 598 ``` 599 600 ### Sample Response 601 602 ```json 603 { 604 "EvalID": "5456bd7a-9fc0-c0dd-6131-cbee77f57577", 605 "Index": 54 606 } 607 ``` 608 609 ## Signal Allocation 610 611 This endpoint sends a signal to an allocation or task. 612 613 | Method | Path | Produces | 614 | ------ | -------------------------- | -------------------------- | 615 | `POST` / `PUT` | `/v1/allocation/:alloc_id/signal` | `application/json` | 616 617 The table below shows this endpoint's support for 618 [blocking queries](/api/index.html#blocking-queries) and 619 [required ACLs](/api/index.html#acls). 620 621 | Blocking Queries | ACL Required | 622 | ---------------- | -------------------- | 623 | `NO` | `namespace:alloc-lifecycle` | 624 625 ### Parameters 626 627 - `:alloc_id` `(string: <required>)`- Specifies the UUID of the allocation. This 628 must be the full UUID, not the short 8-character one. This is specified as 629 part of the path. 630 631 ### Sample Payload 632 633 ```json 634 { 635 "Signal": "SIGUSR1", 636 "Task": "FOO" 637 } 638 ``` 639 640 ### Sample Request 641 642 ```text 643 $ curl -X POST -d '{"Signal": "SIGUSR1" }' \ 644 https://localhost:4646/v1/client/allocation/5456bd7a-9fc0-c0dd-6131-cbee77f57577/signal 645 ``` 646 647 ### Sample Response 648 649 ```json 650 {} 651 ```