github.com/Ilhicas/nomad@v1.0.4-0.20210304152020-e86851182bc3/website/content/api-docs/allocations.mdx (about) 1 --- 2 layout: api 3 page_title: Allocations - HTTP API 4 sidebar_title: Allocations 5 description: The /allocation endpoints are used to query for and interact with allocations. 6 --- 7 8 # Allocations HTTP API 9 10 The `/allocation` endpoints are used to query for and interact with allocations. 11 12 ## List Allocations 13 14 This endpoint lists all allocations. 15 16 | Method | Path | Produces | 17 | ------ | ----------------- | ------------------ | 18 | `GET` | `/v1/allocations` | `application/json` | 19 20 The table below shows this endpoint's support for 21 [blocking queries](/api-docs#blocking-queries) and 22 [required ACLs](/api-docs#acls). 23 24 | Blocking Queries | ACL Required | 25 | ---------------- | -------------------- | 26 | `YES` | `namespace:read-job` | 27 28 ### Parameters 29 30 - `prefix` `(string: "")`- Specifies a string to filter allocations based on an 31 ID prefix. Because the value is decoded to bytes, the prefix must have an 32 even number of hexadecimal characters (0-9a-f). This is specified as a query 33 string parameter. 34 35 - `namespace` `(string: "default")` - Specifies the namespace to search. Specifying 36 `*` would return all allocations across all the authorized namespaces. 37 38 - `resources` `(bool: false)` - Specifies whether or not to include the 39 `AllocatedResources` field in the response. 40 41 - `task_states` `(bool: true)` - Specifies whether or not to include the 42 `TaskStates` field in the response. TaskStates are included by default but 43 can represent a large percentage of the overall response size. Clusters with 44 a large number of allocations may set `task_states=false` to significantly 45 reduce the size of the response. 46 47 ### Sample Request 48 49 ```shell-session 50 $ curl \ 51 https://localhost:4646/v1/allocations 52 ``` 53 54 ```shell-session 55 $ curl \ 56 https://localhost:4646/v1/allocations?prefix=a8198d79 57 ``` 58 59 ```shell-session 60 $ curl \ 61 https://localhost:4646/v1/allocations?namespace=*&prefix=a8198d79 62 ``` 63 64 ### Sample Response 65 66 ```json 67 [ 68 { 69 "ID": "a8198d79-cfdb-6593-a999-1e9adabcba2e", 70 "EvalID": "5456bd7a-9fc0-c0dd-6131-cbee77f57577", 71 "Name": "example.cache[0]", 72 "NodeID": "fb2170a8-257d-3c64-b14d-bc06cc94e34c", 73 "PreviousAllocation": "516d2753-0513-cfc7-57ac-2d6fac18b9dc", 74 "NextAllocation": "cd13d9b9-4f97-7184-c88b-7b451981616b", 75 "RescheduleTracker": { 76 "Events": [ 77 { 78 "PrevAllocID": "516d2753-0513-cfc7-57ac-2d6fac18b9dc", 79 "PrevNodeID": "9230cd3b-3bda-9a3f-82f9-b2ea8dedb20e", 80 "RescheduleTime": 1517434161192946200, 81 "Delay": "5000000000" 82 } 83 ] 84 }, 85 "JobID": "example", 86 "TaskGroup": "cache", 87 "DesiredStatus": "run", 88 "DesiredDescription": "", 89 "ClientStatus": "running", 90 "ClientDescription": "", 91 "TaskStates": { 92 "redis": { 93 "State": "running", 94 "FinishedAt": "0001-01-01T00:00:00Z", 95 "LastRestart": "0001-01-01T00:00:00Z", 96 "Restarts": 0, 97 "StartedAt": "2017-07-25T23:36:26.106431265Z", 98 "Failed": false, 99 "Events": [ 100 { 101 "Type": "Received", 102 "Time": 1495747371795703800, 103 "FailsTask": false, 104 "RestartReason": "", 105 "SetupError": "", 106 "DriverError": "", 107 "ExitCode": 0, 108 "Signal": 0, 109 "Message": "", 110 "KillTimeout": 0, 111 "KillError": "", 112 "KillReason": "", 113 "StartDelay": 0, 114 "DownloadError": "", 115 "ValidationError": "", 116 "DiskLimit": 0, 117 "FailedSibling": "", 118 "VaultError": "", 119 "TaskSignalReason": "", 120 "TaskSignal": "", 121 "DriverMessage": "" 122 }, 123 { 124 "Type": "Driver", 125 "Time": 1495747371798867200, 126 "FailsTask": false, 127 "RestartReason": "", 128 "SetupError": "", 129 "DriverError": "", 130 "ExitCode": 0, 131 "Signal": 0, 132 "Message": "", 133 "KillTimeout": 0, 134 "KillError": "", 135 "KillReason": "", 136 "StartDelay": 0, 137 "DownloadError": "", 138 "ValidationError": "", 139 "DiskLimit": 0, 140 "FailedSibling": "", 141 "VaultError": "", 142 "TaskSignalReason": "", 143 "TaskSignal": "", 144 "DriverMessage": "Downloading image redis:3.2" 145 }, 146 { 147 "Type": "Started", 148 "Time": 1495747379525667800, 149 "FailsTask": false, 150 "RestartReason": "", 151 "SetupError": "", 152 "DriverError": "", 153 "ExitCode": 0, 154 "Signal": 0, 155 "Message": "", 156 "KillTimeout": 0, 157 "KillError": "", 158 "KillReason": "", 159 "StartDelay": 0, 160 "DownloadError": "", 161 "ValidationError": "", 162 "DiskLimit": 0, 163 "FailedSibling": "", 164 "VaultError": "", 165 "TaskSignalReason": "", 166 "TaskSignal": "", 167 "DriverMessage": "" 168 } 169 ] 170 } 171 }, 172 "CreateIndex": 54, 173 "ModifyIndex": 57, 174 "CreateTime": 1495747371794276400, 175 "ModifyTime": 1495747371794276400 176 } 177 ] 178 ``` 179 180 ## Read Allocation 181 182 This endpoint reads information about a specific allocation. 183 184 | Method | Path | Produces | 185 | ------ | -------------------------- | ------------------ | 186 | `GET` | `/v1/allocation/:alloc_id` | `application/json` | 187 188 The table below shows this endpoint's support for 189 [blocking queries](/api-docs#blocking-queries) and 190 [required ACLs](/api-docs#acls). 191 192 | Blocking Queries | ACL Required | 193 | ---------------- | -------------------- | 194 | `YES` | `namespace:read-job` | 195 196 ### Parameters 197 198 - `:alloc_id` `(string: <required>)`- Specifies the UUID of the allocation. This 199 must be the full UUID, not the short 8-character one. This is specified as 200 part of the path. 201 202 ### Sample Request 203 204 ```shell-session 205 $ curl \ 206 https://localhost:4646/v1/allocation/5456bd7a-9fc0-c0dd-6131-cbee77f57577 207 ``` 208 209 ### Sample Response 210 211 ```json 212 { 213 "ID": "a8198d79-cfdb-6593-a999-1e9adabcba2e", 214 "EvalID": "5456bd7a-9fc0-c0dd-6131-cbee77f57577", 215 "Name": "example.cache[0]", 216 "NodeID": "fb2170a8-257d-3c64-b14d-bc06cc94e34c", 217 "PreviousAllocation": "516d2753-0513-cfc7-57ac-2d6fac18b9dc", 218 "NextAllocation": "cd13d9b9-4f97-7184-c88b-7b451981616b", 219 "RescheduleTracker": { 220 "Events": [ 221 { 222 "PrevAllocID": "516d2753-0513-cfc7-57ac-2d6fac18b9dc", 223 "PrevNodeID": "9230cd3b-3bda-9a3f-82f9-b2ea8dedb20e", 224 "RescheduleTime": 1517434161192946200, 225 "Delay": "5000000000" 226 } 227 ] 228 }, 229 "JobID": "example", 230 "Job": { 231 "Region": "global", 232 "ID": "example", 233 "ParentID": "", 234 "Name": "example", 235 "Type": "service", 236 "Priority": 50, 237 "AllAtOnce": false, 238 "Datacenters": ["dc1"], 239 "Constraints": null, 240 "Affinities": null, 241 "TaskGroups": [ 242 { 243 "Name": "cache", 244 "Count": 1, 245 "Constraints": null, 246 "Affinities": null, 247 "RestartPolicy": { 248 "Attempts": 10, 249 "Interval": 300000000000, 250 "Delay": 25000000000, 251 "Mode": "delay" 252 }, 253 "Spreads": null, 254 "Tasks": [ 255 { 256 "Name": "redis", 257 "Driver": "docker", 258 "User": "", 259 "Config": { 260 "port_map": [ 261 { 262 "db": 6379 263 } 264 ], 265 "image": "redis:3.2" 266 }, 267 "Env": null, 268 "Services": [ 269 { 270 "Name": "redis-cache", 271 "PortLabel": "db", 272 "Tags": ["global", "cache"], 273 "Checks": [ 274 { 275 "Name": "alive", 276 "Type": "tcp", 277 "Command": "", 278 "Args": null, 279 "Path": "", 280 "Protocol": "", 281 "PortLabel": "", 282 "Interval": 10000000000, 283 "Timeout": 2000000000, 284 "InitialStatus": "" 285 } 286 ] 287 } 288 ], 289 "Vault": null, 290 "Templates": null, 291 "Constraints": null, 292 "Affinities": null, 293 "Resources": { 294 "CPU": 500, 295 "MemoryMB": 10, 296 "DiskMB": 0, 297 "Networks": [ 298 { 299 "Device": "", 300 "CIDR": "", 301 "IP": "", 302 "MBits": 10, 303 "ReservedPorts": null, 304 "DynamicPorts": [ 305 { 306 "Label": "db", 307 "Value": 0 308 } 309 ] 310 } 311 ] 312 }, 313 "Spreads": null, 314 "DispatchPayload": null, 315 "Meta": null, 316 "KillTimeout": 5000000000, 317 "LogConfig": { 318 "MaxFiles": 10, 319 "MaxFileSizeMB": 10 320 }, 321 "Artifacts": null, 322 "Leader": false 323 } 324 ], 325 "EphemeralDisk": { 326 "Sticky": false, 327 "SizeMB": 300, 328 "Migrate": false 329 }, 330 "Meta": null 331 } 332 ], 333 "Update": { 334 "Stagger": 10000000000, 335 "MaxParallel": 0 336 }, 337 "Periodic": null, 338 "ParameterizedJob": null, 339 "Payload": null, 340 "Spreads": null, 341 "Meta": null, 342 "VaultToken": "", 343 "Status": "pending", 344 "StatusDescription": "", 345 "CreateIndex": 52, 346 "ModifyIndex": 52, 347 "JobModifyIndex": 52 348 }, 349 "TaskGroup": "cache", 350 "Resources": { 351 "CPU": 500, 352 "MemoryMB": 10, 353 "DiskMB": 300, 354 "Networks": [ 355 { 356 "Device": "lo0", 357 "CIDR": "", 358 "IP": "127.0.0.1", 359 "MBits": 10, 360 "ReservedPorts": null, 361 "DynamicPorts": [ 362 { 363 "Label": "db", 364 "Value": 23116 365 } 366 ] 367 } 368 ] 369 }, 370 "SharedResources": { 371 "CPU": 0, 372 "MemoryMB": 0, 373 "DiskMB": 300, 374 "Networks": null 375 }, 376 "TaskResources": { 377 "redis": { 378 "CPU": 500, 379 "MemoryMB": 10, 380 "DiskMB": 0, 381 "Networks": [ 382 { 383 "Device": "lo0", 384 "CIDR": "", 385 "IP": "127.0.0.1", 386 "MBits": 10, 387 "ReservedPorts": null, 388 "DynamicPorts": [ 389 { 390 "Label": "db", 391 "Value": 23116 392 } 393 ] 394 } 395 ] 396 } 397 }, 398 "Metrics": { 399 "NodesEvaluated": 1, 400 "NodesFiltered": 0, 401 "NodesAvailable": { 402 "dc1": 1 403 }, 404 "ClassFiltered": null, 405 "ConstraintFiltered": null, 406 "NodesExhausted": 0, 407 "ClassExhausted": null, 408 "DimensionExhausted": null, 409 "Scores": { 410 "fb2170a8-257d-3c64-b14d-bc06cc94e34c.binpack": 0.6205732522109244 411 }, 412 "AllocationTime": 31729, 413 "CoalescedFailures": 0 414 }, 415 "DesiredStatus": "run", 416 "DesiredDescription": "", 417 "ClientStatus": "running", 418 "ClientDescription": "", 419 "TaskStates": { 420 "redis": { 421 "State": "running", 422 "Failed": false, 423 "FinishedAt": "0001-01-01T00:00:00Z", 424 "LastRestart": "0001-01-01T00:00:00Z", 425 "Restarts": 0, 426 "StartedAt": "2017-07-25T23:36:26.106431265Z", 427 "Events": [ 428 { 429 "Type": "Received", 430 "Time": 1495747371795703800, 431 "FailsTask": false, 432 "RestartReason": "", 433 "SetupError": "", 434 "DriverError": "", 435 "ExitCode": 0, 436 "Signal": 0, 437 "Message": "", 438 "KillTimeout": 0, 439 "KillError": "", 440 "KillReason": "", 441 "StartDelay": 0, 442 "DownloadError": "", 443 "ValidationError": "", 444 "DiskLimit": 0, 445 "FailedSibling": "", 446 "VaultError": "", 447 "TaskSignalReason": "", 448 "TaskSignal": "", 449 "DriverMessage": "" 450 }, 451 { 452 "Type": "Driver", 453 "Time": 1495747371798867200, 454 "FailsTask": false, 455 "RestartReason": "", 456 "SetupError": "", 457 "DriverError": "", 458 "ExitCode": 0, 459 "Signal": 0, 460 "Message": "", 461 "KillTimeout": 0, 462 "KillError": "", 463 "KillReason": "", 464 "StartDelay": 0, 465 "DownloadError": "", 466 "ValidationError": "", 467 "DiskLimit": 0, 468 "FailedSibling": "", 469 "VaultError": "", 470 "TaskSignalReason": "", 471 "TaskSignal": "", 472 "DriverMessage": "Downloading image redis:3.2" 473 }, 474 { 475 "Type": "Started", 476 "Time": 1495747379525667800, 477 "FailsTask": false, 478 "RestartReason": "", 479 "SetupError": "", 480 "DriverError": "", 481 "ExitCode": 0, 482 "Signal": 0, 483 "Message": "", 484 "KillTimeout": 0, 485 "KillError": "", 486 "KillReason": "", 487 "StartDelay": 0, 488 "DownloadError": "", 489 "ValidationError": "", 490 "DiskLimit": 0, 491 "FailedSibling": "", 492 "VaultError": "", 493 "TaskSignalReason": "", 494 "TaskSignal": "", 495 "DriverMessage": "" 496 } 497 ] 498 } 499 }, 500 "PreviousAllocation": "", 501 "CreateIndex": 54, 502 "ModifyIndex": 57, 503 "AllocModifyIndex": 54, 504 "CreateTime": 1495747371794276400, 505 "ModifyTime": 1495747371794276400 506 } 507 ``` 508 509 #### Field Reference 510 511 - `Job` - A copy of the job at the time that the allocation is created or 512 updated. This is primarily intended for use by the Nomad client when running 513 the allocation, and it may include stale information on some job fields. 514 Up-to-date information about the job status is available from the 515 [jobs API](/api-docs/jobs); take care to fetch the version of the job 516 associated with this allocation. 517 518 - `TaskStates` - A map of tasks to their current state and the latest events 519 that have effected the state. `TaskState` objects contain the following 520 fields: 521 522 - `State`: The task's current state. It can have one of the following 523 values: 524 525 - `TaskStatePending` - The task is waiting to be run, either for the first 526 time or due to a restart. 527 528 - `TaskStateRunning` - The task is currently running. 529 530 - `TaskStateDead` - The task is dead and will not run again. 531 532 - `StartedAt`: The time the task was last started at. Can be updated through 533 restarts. 534 535 - `FinishedAt`: The time the task was finished at. 536 537 - `LastRestart`: The last time the task was restarted. 538 539 - `Restarts`: The number of times the task has restarted. 540 541 - `Events` - An event contains metadata about the event. The latest 10 events 542 are stored per task. Each event is timestamped (Unix nanoseconds) and has one 543 of the following types: 544 545 - `Setup Failure` - The task could not be started because there was a 546 failure setting up the task prior to it running. 547 548 - `Driver Failure` - The task could not be started due to a failure in the 549 driver. 550 551 - `Started` - The task was started; either for the first time or due to a 552 restart. 553 554 - `Terminated` - The task was started and exited. 555 556 - `Killing` - The task has been sent the kill signal. 557 558 - `Killed` - The task was killed by a user. 559 560 - `Received` - The task has been pulled by the client at the given timestamp. 561 562 - `Failed Validation` - The task was invalid and as such it didn't run. 563 564 - `Restarting` - The task terminated and is being restarted. 565 566 - `Not Restarting` - the task has failed and is not being restarted because 567 it has exceeded its restart policy. 568 569 - `Downloading Artifacts` - The task is downloading the artifact(s) 570 - specified in the task. 571 572 - `Failed Artifact Download` - Artifact(s) specified in the task failed to 573 download. 574 575 - `Restart Signaled` - The task was singled to be restarted. 576 577 - `Signaling` - The task was is being sent a signal. 578 579 - `Sibling Task Failed` - A task in the same task group failed. 580 581 - `Leader Task Dead` - The group's leader task is dead. 582 583 - `Driver` - A message from the driver. 584 585 - `Task Setup` - Task setup messages. 586 587 - `Building Task Directory` - Task is building its file system. 588 589 Depending on the type the event will have applicable annotations. 590 591 ## Stop Allocation 592 593 This endpoint stops and reschedules a specific allocation. 594 595 | Method | Path | Produces | 596 | -------------- | ------------------------------- | ------------------ | 597 | `POST` / `PUT` | `/v1/allocation/:alloc_id/stop` | `application/json` | 598 599 The table below shows this endpoint's support for 600 [blocking queries](/api-docs#blocking-queries) and 601 [required ACLs](/api-docs#acls). 602 603 | Blocking Queries | ACL Required | 604 | ---------------- | --------------------------- | 605 | `NO` | `namespace:alloc-lifecycle` | 606 607 ### Parameters 608 609 - `:alloc_id` `(string: <required>)`- Specifies the UUID of the allocation. This 610 must be the full UUID, not the short 8-character one. This is specified as 611 part of the path. 612 613 ### Sample Request 614 615 ```shell-session 616 $ curl -X POST \ 617 https://localhost:4646/v1/allocation/5456bd7a-9fc0-c0dd-6131-cbee77f57577/stop 618 ``` 619 620 ### Sample Response 621 622 ```json 623 { 624 "EvalID": "5456bd7a-9fc0-c0dd-6131-cbee77f57577", 625 "Index": 54 626 } 627 ``` 628 629 ## Signal Allocation 630 631 This endpoint sends a signal to an allocation or task. 632 633 | Method | Path | Produces | 634 | -------------- | ---------------------------------------- | ------------------ | 635 | `POST` / `PUT` | `/v1/client/allocation/:alloc_id/signal` | `application/json` | 636 637 The table below shows this endpoint's support for 638 [blocking queries](/api-docs#blocking-queries) and 639 [required ACLs](/api-docs#acls). 640 641 | Blocking Queries | ACL Required | 642 | ---------------- | --------------------------- | 643 | `NO` | `namespace:alloc-lifecycle` | 644 645 ### Parameters 646 647 - `:alloc_id` `(string: <required>)`- Specifies the UUID of the allocation. This 648 must be the full UUID, not the short 8-character one. This is specified as 649 part of the path. 650 651 ### Sample Payload 652 653 ```json 654 { 655 "Signal": "SIGUSR1", 656 "Task": "FOO" 657 } 658 ``` 659 660 ### Sample Request 661 662 ```shell-session 663 $ curl -X POST -d '{"Signal": "SIGUSR1" }' \ 664 https://localhost:4646/v1/client/allocation/5456bd7a-9fc0-c0dd-6131-cbee77f57577/signal 665 ``` 666 667 ### Sample Response 668 669 ```json 670 {} 671 ``` 672 673 ## Restart Allocation 674 675 This endpoint restarts an allocation or task in-place. 676 677 | Method | Path | Produces | 678 | -------------- | ----------------------------------------- | ------------------ | 679 | `POST` / `PUT` | `/v1/client/allocation/:alloc_id/restart` | `application/json` | 680 681 The table below shows this endpoint's support for 682 [blocking queries](/api-docs#blocking-queries) and 683 [required ACLs](/api-docs#acls). 684 685 | Blocking Queries | ACL Required | 686 | ---------------- | --------------------------- | 687 | `NO` | `namespace:alloc-lifecycle` | 688 689 ### Parameters 690 691 - `:alloc_id` `(string: <required>)`- Specifies the UUID of the allocation. This 692 must be the full UUID, not the short 8-character one. This is specified as 693 part of the path. 694 695 ### Sample Payload 696 697 ```json 698 { 699 "Task": "FOO" 700 } 701 ``` 702 703 ### Sample Request 704 705 ```shell-session 706 $ curl -X POST -d '{"Task": "redis" }' \ 707 https://localhost:4646/v1/client/allocation/5456bd7a-9fc0-c0dd-6131-cbee77f57577/restart 708 ``` 709 710 ### Sample Response 711 712 ```json 713 {} 714 ``` 715 716 ## Exec Allocation 717 718 This endpoint executes a command inside the isolation container where an allocation is running. 719 It opens a WebSocket to transmit input to and output from the command. 720 721 | Method | Path | Produces | 722 | ------ | -------------------------- | -------------------------- | 723 | `WebSocket` | `/v1/client/allocation/:alloc_id/exec` | WebSocket JSON streams | 724 725 The table below shows this endpoint's support for 726 [blocking queries](/api/index.html#blocking-queries) and 727 [required ACLs](/api/index.html#acls). 728 729 | Blocking Queries | ACL Required | 730 | ---------------- | -------------------- | 731 | `NO` | `namespace:alloc-exec` (and `namespace:alloc-node-exec` if target task uses raw_exec driver) | 732 733 ### Parameters 734 735 - `:alloc_id` `(string: <required>)`- Specifies the UUID of the allocation. This 736 must be the full UUID, not the short 8-character one. This is specified as 737 part of the path. 738 - `command` `(string: <required>)` - Specifies the command to be executed. This 739 must be a JSON-encoded array of the command to be executed, e.g. `["echo", "hi"]` 740 or `["/bin/bash"]`. This is specified as a query parameter. 741 - `task` `(string: <required>)` - Specifies the task name, as a query parameter. 742 - `tty` `(bool: false)` - Specifies whether a TTY is allocated for this task, as 743 a query parameter. 744 - `ws_handshake` `(bool: false)` - Specifies whether to expect the authentication 745 token in the first frame, as a query parameter. 746 747 ### Request Frames 748 749 Request frames represent the `stdin` stream from the command as well as TTY resize events. 750 When `?ws_handshake=true`, the first request frame must contain the authentication token. 751 752 The following are valid formats: 753 754 ``` 755 # sending authentication token 756 {"version":1,"auth_token":"fc3c1968-8d31-5c50-9617-3db2e19ef32e"} 757 758 # sending stdin data 759 {"stdin": {"data": "...base64 encoded string of bytes ..."}} 760 761 # indicating stdin is closed 762 {"stdin": {"close": true}} 763 764 # indicating that TTY was resized 765 {"tty_size": {"height": <characters>, "width": <characters>}} 766 767 # basic application-level heartbeat 768 {} 769 ``` 770 771 ### Response Frames 772 773 Response frames represent `stdout` and `stderr` output from the command as well as exit codes: 774 775 ``` 776 # transferring stdout data 777 {"stdout": {"data": "...base64 encoded string of bytes ..."}} 778 779 # signaling that host closed stdout 780 {"stdout": {"close": true}} 781 782 # transferring stderr data 783 {"stderr": {"data": "...base64 encoded string of bytes ..."}} 784 785 # signaling that host closed stderr 786 {"stderr": {"close": true}} 787 788 # signaling process exited 789 {"exited": true, "result": {"exit_code": <exit_code_int>}} 790 791 # basic application-level heartbeat 792 {} 793 ``` 794 795 ### Sample Request and Response 796 797 Request and response frames encompass the full range of terminal emulator inputs and outputs, including the control characters necessary to render interactive applications. The example response includes instances of the ANSI “control sequence introducer” (CSI), which is ASCII code 27 followed by `[`. 798 799 ``` 800 # \x12: form feed, to clear terminal 801 {"stdin":{"data":"DA=="}} 802 803 # "\x1b[H\x1b[2J$ ": 804 # CSI-H (move cursor to top left corner), CSI-2J (clear entire screen), print "$ " 805 {"stdout":{"data":"G1tIG1sySiQg"}}