github.com/smintz/nomad@v0.8.3/website/source/api/jobs.html.md (about) 1 --- 2 layout: api 3 page_title: Jobs - HTTP API 4 sidebar_current: api-jobs 5 description: |- 6 The /jobs endpoints are used to query for and interact with jobs. 7 --- 8 9 # Jobs HTTP API 10 11 The `/jobs` endpoints are used to query for and interact with jobs. 12 13 ## List Jobs 14 15 This endpoint lists all known jobs in the system registered with Nomad. 16 17 | Method | Path | Produces | 18 | ------ | ------------------------- | -------------------------- | 19 | `GET` | `/v1/jobs` | `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:list-jobs` | 28 29 ### Parameters 30 31 - `prefix` `(string: "")` - Specifies a string to filter jobs 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/jobs 39 ``` 40 41 ```text 42 $ curl \ 43 https://localhost:4646/v1/jobs?prefix=team 44 ``` 45 46 ### Sample Response 47 48 ```json 49 [ 50 { 51 "ID": "example", 52 "ParentID": "", 53 "Name": "example", 54 "Type": "service", 55 "Priority": 50, 56 "Status": "pending", 57 "StatusDescription": "", 58 "JobSummary": { 59 "JobID": "example", 60 "Summary": { 61 "cache": { 62 "Queued": 1, 63 "Complete": 1, 64 "Failed": 0, 65 "Running": 0, 66 "Starting": 0, 67 "Lost": 0 68 } 69 }, 70 "Children": { 71 "Pending": 0, 72 "Running": 0, 73 "Dead": 0 74 }, 75 "CreateIndex": 52, 76 "ModifyIndex": 96 77 }, 78 "CreateIndex": 52, 79 "ModifyIndex": 93, 80 "JobModifyIndex": 52 81 } 82 ] 83 ``` 84 85 ## Create Job 86 87 This endpoint creates (aka "registers") a new job in the system. 88 89 | Method | Path | Produces | 90 | ------- | ------------------------- | -------------------------- | 91 | `POST` | `/v1/jobs` | `application/json` | 92 93 The table below shows this endpoint's support for 94 [blocking queries](/api/index.html#blocking-queries) and 95 [required ACLs](/api/index.html#acls). 96 97 | Blocking Queries | ACL Required | 98 | ---------------- | ------------ | 99 | `NO` | `namespace:submit-job`<br>`namespace:sentinel-override` if `PolicyOverride` set | 100 101 ### Parameters 102 103 - `Job` `(Job: <required>)` - Specifies the JSON definition of the job. 104 105 - `EnforceIndex` `(bool: false)` - If set, the job will only be registered if the 106 passed `JobModifyIndex` matches the current job's index. If the index is zero, 107 the register only occurs if the job is new. This paradigm allows check-and-set 108 style job updating. 109 110 - `JobModifyIndex` `(int: 0)` - Specifies the `JobModifyIndex` to enforce the 111 current job is at. 112 113 - `PolicyOverride` `(bool: false)` - If set, any soft mandatory Sentinel policies 114 will be overridden. This allows a job to be registered when it would be denied 115 by policy. 116 117 ### Sample Payload 118 119 ```json 120 { 121 "Job": { 122 "ID": "example", 123 "Name": "example", 124 "Type": "service", 125 "Priority": 50, 126 "Datacenters": [ 127 "dc1" 128 ], 129 "TaskGroups": [{ 130 "Name": "cache", 131 "Count": 1, 132 "Tasks": [{ 133 "Name": "redis", 134 "Driver": "docker", 135 "User": "", 136 "Config": { 137 "image": "redis:3.2", 138 "port_map": [{ 139 "db": 6379 140 }] 141 }, 142 "Services": [{ 143 "Id": "", 144 "Name": "redis-cache", 145 "Tags": [ 146 "global", 147 "cache" 148 ], 149 "PortLabel": "db", 150 "AddressMode": "", 151 "Checks": [{ 152 "Id": "", 153 "Name": "alive", 154 "Type": "tcp", 155 "Command": "", 156 "Args": null, 157 "Path": "", 158 "Protocol": "", 159 "PortLabel": "", 160 "Interval": 10000000000, 161 "Timeout": 2000000000, 162 "InitialStatus": "", 163 "TLSSkipVerify": false 164 }] 165 }], 166 "Resources": { 167 "CPU": 500, 168 "MemoryMB": 256, 169 "Networks": [{ 170 "Device": "", 171 "CIDR": "", 172 "IP": "", 173 "MBits": 10, 174 "DynamicPorts": [{ 175 "Label": "db", 176 "Value": 0 177 }] 178 }] 179 }, 180 "Leader": false 181 }], 182 "RestartPolicy": { 183 "Interval": 300000000000, 184 "Attempts": 10, 185 "Delay": 25000000000, 186 "Mode": "delay" 187 }, 188 "ReschedulePolicy": { 189 "Attempts": 10, 190 "Delay": 30000000000, 191 "DelayFunction": "exponential", 192 "Interval": 0, 193 "MaxDelay": 3600000000000, 194 "Unlimited": true 195 }, 196 "EphemeralDisk": { 197 "SizeMB": 300 198 } 199 }], 200 "Update": { 201 "MaxParallel": 1, 202 "MinHealthyTime": 10000000000, 203 "HealthyDeadline": 180000000000, 204 "AutoRevert": false, 205 "Canary": 0 206 } 207 } 208 } 209 ``` 210 211 ### Sample Request 212 213 ```text 214 $ curl \ 215 --request POST \ 216 --data @my-job.nomad \ 217 https://localhost:4646/v1/jobs 218 ``` 219 220 ### Sample Response 221 222 ```json 223 { 224 "EvalID": "", 225 "EvalCreateIndex": 0, 226 "JobModifyIndex": 109, 227 "Warnings": "", 228 "Index": 0, 229 "LastContact": 0, 230 "KnownLeader": false 231 } 232 ``` 233 234 ## Parse Job 235 236 This endpoint will parse a HCL jobspec and produce the equivalent JSON encoded 237 job. 238 239 | Method | Path | Produces | 240 | ------ | ------------------------- | -------------------------- | 241 | `POST` | `/v1/jobs/parse` | `application/json` | 242 243 The table below shows this endpoint's support for 244 [blocking queries](/api/index.html#blocking-queries) and 245 [required ACLs](/api/index.html#acls). 246 247 | Blocking Queries | ACL Required | 248 | ---------------- | ------------ | 249 | `NO` | `none` | 250 251 ### Parameters 252 253 - `JobHCL` `(string: <required>)` - Specifies the HCL definition of the job 254 encoded in a JSON string. 255 - `Canonicalize` `(bool: false)` - Flag to enable setting any unset fields to 256 their default values. 257 258 ## Sample Payload 259 260 ```json 261 { 262 "JobHCL":"job \"example\" { type = \"service\" group \"cache\" {} }", 263 "Canonicalize": true 264 } 265 ``` 266 267 ### Sample Request 268 269 ```text 270 $ curl \ 271 --request POST \ 272 --data '{"Canonicalize": true, "JobHCL": "job \"my-job\" {}"}' \ 273 https://localhost:4646/v1/jobs/parse 274 ``` 275 276 ### Sample Response 277 278 ```json 279 { 280 "AllAtOnce": false, 281 "Constraints": null, 282 "CreateIndex": 0, 283 "Datacenters": null, 284 "ID": "my-job", 285 "JobModifyIndex": 0, 286 "Meta": null, 287 "Migrate": null, 288 "ModifyIndex": 0, 289 "Name": "my-job", 290 "Namespace": "default", 291 "ParameterizedJob": null, 292 "ParentID": "", 293 "Payload": null, 294 "Periodic": null, 295 "Priority": 50, 296 "Region": "global", 297 "Reschedule": null, 298 "Stable": false, 299 "Status": "", 300 "StatusDescription": "", 301 "Stop": false, 302 "SubmitTime": null, 303 "TaskGroups": null, 304 "Type": "service", 305 "Update": null, 306 "VaultToken": "", 307 "Version": 0 308 } 309 ``` 310 311 ## Read Job 312 313 This endpoint reads information about a single job for its specification and 314 status. 315 316 | Method | Path | Produces | 317 | ------ | ------------------------- | -------------------------- | 318 | `GET` | `/v1/job/:job_id` | `application/json` | 319 320 The table below shows this endpoint's support for 321 [blocking queries](/api/index.html#blocking-queries) and 322 [required ACLs](/api/index.html#acls). 323 324 | Blocking Queries | ACL Required | 325 | ---------------- | -------------------------- | 326 | `YES` | `namespace:read-job` | 327 328 ### Parameters 329 330 - `:job_id` `(string: <required>)` - Specifies the ID of the job (as specified in 331 the job file during submission). This is specified as part of the path. 332 333 ### Sample Request 334 335 ```text 336 $ curl \ 337 https://localhost:4646/v1/job/my-job 338 ``` 339 340 ### Sample Response 341 342 ```json 343 { 344 "Region": "global", 345 "ID": "example", 346 "ParentID": "", 347 "Name": "example", 348 "Type": "batch", 349 "Priority": 50, 350 "AllAtOnce": false, 351 "Datacenters": [ 352 "dc1" 353 ], 354 "Constraints": [ 355 { 356 "LTarget": "${attr.kernel.name}", 357 "RTarget": "linux", 358 "Operand": "=" 359 } 360 ], 361 "TaskGroups": [ 362 { 363 "Name": "cache", 364 "Count": 1, 365 "Constraints": [ 366 { 367 "LTarget": "${attr.os.signals}", 368 "RTarget": "SIGUSR1", 369 "Operand": "set_contains" 370 } 371 ], 372 "RestartPolicy": { 373 "Attempts": 10, 374 "Interval": 300000000000, 375 "Delay": 25000000000, 376 "Mode": "delay" 377 }, 378 "Tasks": [ 379 { 380 "Name": "redis", 381 "Driver": "docker", 382 "User": "foo-user", 383 "Config": { 384 "image": "redis:latest", 385 "port_map": [ 386 { 387 "db": 6379 388 } 389 ] 390 }, 391 "Env": { 392 "foo": "bar", 393 "baz": "pipe" 394 }, 395 "Services": [ 396 { 397 "Name": "cache-redis", 398 "PortLabel": "db", 399 "Tags": [ 400 "global", 401 "cache" 402 ], 403 "Checks": [ 404 { 405 "Name": "alive", 406 "Type": "tcp", 407 "Command": "", 408 "Args": null, 409 "Path": "", 410 "Protocol": "", 411 "PortLabel": "", 412 "Interval": 10000000000, 413 "Timeout": 2000000000, 414 "InitialStatus": "" 415 } 416 ] 417 } 418 ], 419 "Vault": null, 420 "Templates": [ 421 { 422 "SourcePath": "local/config.conf.tpl", 423 "DestPath": "local/config.conf", 424 "EmbeddedTmpl": "", 425 "ChangeMode": "signal", 426 "ChangeSignal": "SIGUSR1", 427 "Splay": 5000000000, 428 "Perms": "" 429 } 430 ], 431 "Constraints": null, 432 "Resources": { 433 "CPU": 500, 434 "MemoryMB": 256, 435 "DiskMB": 0, 436 "IOPS": 0, 437 "Networks": [ 438 { 439 "Device": "", 440 "CIDR": "", 441 "IP": "", 442 "MBits": 10, 443 "ReservedPorts": [ 444 { 445 "Label": "rpc", 446 "Value": 25566 447 } 448 ], 449 "DynamicPorts": [ 450 { 451 "Label": "db", 452 "Value": 0 453 } 454 ] 455 } 456 ] 457 }, 458 "DispatchPayload": { 459 "File": "config.json" 460 }, 461 "Meta": { 462 "foo": "bar", 463 "baz": "pipe" 464 }, 465 "KillTimeout": 5000000000, 466 "LogConfig": { 467 "MaxFiles": 10, 468 "MaxFileSizeMB": 10 469 }, 470 "Artifacts": [ 471 { 472 "GetterSource": "http://foo.com/artifact.tar.gz", 473 "GetterOptions": { 474 "checksum": "md5:c4aa853ad2215426eb7d70a21922e794" 475 }, 476 "RelativeDest": "local/" 477 } 478 ], 479 "Leader": false 480 } 481 ], 482 "EphemeralDisk": { 483 "Sticky": false, 484 "SizeMB": 300, 485 "Migrate": false 486 }, 487 "Meta": { 488 "foo": "bar", 489 "baz": "pipe" 490 } 491 } 492 ], 493 "Update": { 494 "Stagger": 10000000000, 495 "MaxParallel": 1 496 }, 497 "Periodic": { 498 "Enabled": true, 499 "Spec": "* * * * *", 500 "SpecType": "cron", 501 "ProhibitOverlap": true 502 }, 503 "ParameterizedJob": { 504 "Payload": "required", 505 "MetaRequired": [ 506 "foo" 507 ], 508 "MetaOptional": [ 509 "bar" 510 ] 511 }, 512 "Payload": null, 513 "Meta": { 514 "foo": "bar", 515 "baz": "pipe" 516 }, 517 "VaultToken": "", 518 "Status": "running", 519 "StatusDescription": "", 520 "CreateIndex": 7, 521 "ModifyIndex": 7, 522 "JobModifyIndex": 7 523 } 524 ``` 525 526 ## List Job Versions 527 528 This endpoint reads information about all versions of a job. 529 530 | Method | Path | Produces | 531 | ------ | -------------------------- | -------------------------- | 532 | `GET` | `/v1/job/:job_id/versions` | `application/json` | 533 534 The table below shows this endpoint's support for 535 [blocking queries](/api/index.html#blocking-queries) and 536 [required ACLs](/api/index.html#acls). 537 538 | Blocking Queries | ACL Required | 539 | ---------------- | -------------------------- | 540 | `YES` | `namespace:read-job` | 541 542 ### Parameters 543 544 - `:job_id` `(string: <required>)` - Specifies the ID of the job (as specified in 545 the job file during submission). This is specified as part of the path. 546 547 ### Sample Request 548 549 ```text 550 $ curl \ 551 https://localhost:4646/v1/job/my-job/versions 552 ``` 553 554 ### Sample Response 555 556 ```json 557 [ 558 { 559 "Stop": false, 560 "Region": "global", 561 "ID": "example", 562 "ParentID": "", 563 "Name": "example", 564 "Type": "service", 565 "Priority": 50, 566 "AllAtOnce": false, 567 "Datacenters": [ 568 "dc1" 569 ], 570 "Constraints": null, 571 "TaskGroups": [ 572 { 573 "Name": "cache", 574 "Count": 1, 575 "Update": { 576 "Stagger": 0, 577 "MaxParallel": 1, 578 "HealthCheck": "checks", 579 "MinHealthyTime": 10000000000, 580 "HealthyDeadline": 300000000000, 581 "AutoRevert": false, 582 "Canary": 0 583 }, 584 "Constraints": null, 585 "RestartPolicy": { 586 "Attempts": 10, 587 "Interval": 300000000000, 588 "Delay": 25000000000, 589 "Mode": "delay" 590 }, 591 "Tasks": [ 592 { 593 "Name": "redis", 594 "Driver": "docker", 595 "User": "", 596 "Config": { 597 "image": "redis:3.2", 598 "port_map": [ 599 { 600 "db": 6379 601 } 602 ] 603 }, 604 "Env": null, 605 "Services": [ 606 { 607 "Name": "redis-cache", 608 "PortLabel": "db", 609 "Tags": [ 610 "global", 611 "cache" 612 ], 613 "Checks": [ 614 { 615 "Name": "alive", 616 "Type": "tcp", 617 "Command": "", 618 "Args": null, 619 "Path": "", 620 "Protocol": "", 621 "PortLabel": "", 622 "Interval": 10000000000, 623 "Timeout": 2000000000, 624 "InitialStatus": "", 625 "TLSSkipVerify": false 626 } 627 ] 628 } 629 ], 630 "Vault": null, 631 "Templates": null, 632 "Constraints": null, 633 "Resources": { 634 "CPU": 500, 635 "MemoryMB": 256, 636 "DiskMB": 0, 637 "IOPS": 0, 638 "Networks": [ 639 { 640 "Device": "", 641 "CIDR": "", 642 "IP": "", 643 "MBits": 10, 644 "ReservedPorts": null, 645 "DynamicPorts": [ 646 { 647 "Label": "db", 648 "Value": 0 649 } 650 ] 651 } 652 ] 653 }, 654 "DispatchPayload": null, 655 "Meta": null, 656 "KillTimeout": 5000000000, 657 "LogConfig": { 658 "MaxFiles": 10, 659 "MaxFileSizeMB": 10 660 }, 661 "Artifacts": null, 662 "Leader": false 663 } 664 ], 665 "EphemeralDisk": { 666 "Sticky": false, 667 "SizeMB": 300, 668 "Migrate": false 669 }, 670 "Meta": null 671 } 672 ], 673 "Update": { 674 "Stagger": 10000000000, 675 "MaxParallel": 1, 676 "HealthCheck": "", 677 "MinHealthyTime": 0, 678 "HealthyDeadline": 0, 679 "AutoRevert": false, 680 "Canary": 0 681 }, 682 "Periodic": null, 683 "ParameterizedJob": null, 684 "Payload": null, 685 "Meta": null, 686 "VaultToken": "", 687 "Status": "pending", 688 "StatusDescription": "", 689 "Stable": false, 690 "Version": 0, 691 "CreateIndex": 7, 692 "ModifyIndex": 7, 693 "JobModifyIndex": 7 694 } 695 ] 696 ``` 697 698 ## List Job Allocations 699 700 This endpoint reads information about a single job's allocations. 701 702 | Method | Path | Produces | 703 | ------ | ----------------------------- | -------------------------- | 704 | `GET` | `/v1/job/:job_id/allocations` | `application/json` | 705 706 The table below shows this endpoint's support for 707 [blocking queries](/api/index.html#blocking-queries) and 708 [required ACLs](/api/index.html#acls). 709 710 | Blocking Queries | ACL Required | 711 | ---------------- | -------------------------- | 712 | `YES` | `namespace:read-job` | 713 714 ### Parameters 715 716 - `:job_id` `(string: <required>)` - Specifies the ID of the job (as specified in 717 the job file during submission). This is specified as part of the path. 718 719 - `all` `(bool: false)` - Specifies whether the list of allocations should 720 include allocations from a previously registered job with the same ID. This is 721 possible if the job is deregistered and reregistered. 722 723 ### Sample Request 724 725 ```text 726 $ curl \ 727 https://localhost:4646/v1/job/my-job/allocations 728 ``` 729 730 ### Sample Response 731 732 ```json 733 [ 734 { 735 "ID": "ed344e0a-7290-d117-41d3-a64f853ca3c2", 736 "EvalID": "a9c5effc-2242-51b2-f1fe-054ee11ab189", 737 "Name": "example.cache[0]", 738 "NodeID": "cb1f6030-a220-4f92-57dc-7baaabdc3823", 739 "PreviousAllocation": "516d2753-0513-cfc7-57ac-2d6fac18b9dc", 740 "NextAllocation": "cd13d9b9-4f97-7184-c88b-7b451981616b", 741 "RescheduleTracker": { 742 "Events": [ 743 { 744 "PrevAllocID": "516d2753-0513-cfc7-57ac-2d6fac18b9dc", 745 "PrevNodeID": "9230cd3b-3bda-9a3f-82f9-b2ea8dedb20e", 746 "RescheduleTime": 1517434161192946200, 747 "Delay":5000000000, 748 }, 749 ] 750 }, 751 "JobID": "example", 752 "TaskGroup": "cache", 753 "DesiredStatus": "run", 754 "DesiredDescription": "", 755 "ClientStatus": "running", 756 "ClientDescription": "", 757 "TaskStates": { 758 "redis": { 759 "State": "running", 760 "Failed": false, 761 "StartedAt": "2017-05-25T23:41:23.240184101Z", 762 "FinishedAt": "0001-01-01T00:00:00Z", 763 "Events": [ 764 { 765 "Type": "Received", 766 "Time": 1495755675956923000, 767 "FailsTask": false, 768 "RestartReason": "", 769 "SetupError": "", 770 "DriverError": "", 771 "ExitCode": 0, 772 "Signal": 0, 773 "Message": "", 774 "KillTimeout": 0, 775 "KillError": "", 776 "KillReason": "", 777 "StartDelay": 0, 778 "DownloadError": "", 779 "ValidationError": "", 780 "DiskLimit": 0, 781 "FailedSibling": "", 782 "VaultError": "", 783 "TaskSignalReason": "", 784 "TaskSignal": "", 785 "DriverMessage": "" 786 }, 787 { 788 "Type": "Task Setup", 789 "Time": 1495755675957466400, 790 "FailsTask": false, 791 "RestartReason": "", 792 "SetupError": "", 793 "DriverError": "", 794 "ExitCode": 0, 795 "Signal": 0, 796 "Message": "Building Task Directory", 797 "KillTimeout": 0, 798 "KillError": "", 799 "KillReason": "", 800 "StartDelay": 0, 801 "DownloadError": "", 802 "ValidationError": "", 803 "DiskLimit": 0, 804 "FailedSibling": "", 805 "VaultError": "", 806 "TaskSignalReason": "", 807 "TaskSignal": "", 808 "DriverMessage": "" 809 }, 810 { 811 "Type": "Driver", 812 "Time": 1495755675970286800, 813 "FailsTask": false, 814 "RestartReason": "", 815 "SetupError": "", 816 "DriverError": "", 817 "ExitCode": 0, 818 "Signal": 0, 819 "Message": "", 820 "KillTimeout": 0, 821 "KillError": "", 822 "KillReason": "", 823 "StartDelay": 0, 824 "DownloadError": "", 825 "ValidationError": "", 826 "DiskLimit": 0, 827 "FailedSibling": "", 828 "VaultError": "", 829 "TaskSignalReason": "", 830 "TaskSignal": "", 831 "DriverMessage": "Downloading image redis:3.2" 832 }, 833 { 834 "Type": "Started", 835 "Time": 1495755683227522000, 836 "FailsTask": false, 837 "RestartReason": "", 838 "SetupError": "", 839 "DriverError": "", 840 "ExitCode": 0, 841 "Signal": 0, 842 "Message": "", 843 "KillTimeout": 0, 844 "KillError": "", 845 "KillReason": "", 846 "StartDelay": 0, 847 "DownloadError": "", 848 "ValidationError": "", 849 "DiskLimit": 0, 850 "FailedSibling": "", 851 "VaultError": "", 852 "TaskSignalReason": "", 853 "TaskSignal": "", 854 "DriverMessage": "" 855 } 856 ] 857 } 858 }, 859 "CreateIndex": 9, 860 "ModifyIndex": 13, 861 "CreateTime": 1495755675944527600, 862 "ModifyTime": 1495755675944527600 863 } 864 ] 865 ``` 866 867 ## List Job Evaluations 868 869 This endpoint reads information about a single job's evaluations 870 871 | Method | Path | Produces | 872 | ------ | ----------------------------- | -------------------------- | 873 | `GET` | `/v1/job/:job_id/evaluations` | `application/json` | 874 875 The table below shows this endpoint's support for 876 [blocking queries](/api/index.html#blocking-queries) and 877 [required ACLs](/api/index.html#acls). 878 879 | Blocking Queries | ACL Required | 880 | ---------------- | -------------------------- | 881 | `YES` | `namespace:read-job` | 882 883 ### Parameters 884 885 - `:job_id` `(string: <required>)` - Specifies the ID of the job (as specified in 886 the job file during submission). This is specified as part of the path. 887 888 ### Sample Request 889 890 ```text 891 $ curl \ 892 https://localhost:4646/v1/job/my-job/evaluations 893 ``` 894 895 ### Sample Response 896 897 ```json 898 [ 899 { 900 "ID": "a9c5effc-2242-51b2-f1fe-054ee11ab189", 901 "Priority": 50, 902 "Type": "service", 903 "TriggeredBy": "job-register", 904 "JobID": "example", 905 "JobModifyIndex": 7, 906 "NodeID": "", 907 "NodeModifyIndex": 0, 908 "Status": "complete", 909 "StatusDescription": "", 910 "Wait": 0, 911 "NextEval": "", 912 "PreviousEval": "", 913 "BlockedEval": "", 914 "FailedTGAllocs": null, 915 "ClassEligibility": null, 916 "EscapedComputedClass": false, 917 "AnnotatePlan": false, 918 "QueuedAllocations": { 919 "cache": 0 920 }, 921 "SnapshotIndex": 8, 922 "CreateIndex": 8, 923 "ModifyIndex": 10 924 } 925 ] 926 ``` 927 928 ## List Job Deployments 929 930 This endpoint lists a single job's deployments 931 932 | Method | Path | Produces | 933 | ------ | ----------------------------- | -------------------------- | 934 | `GET` | `/v1/job/:job_id/deployments` | `application/json` | 935 936 The table below shows this endpoint's support for 937 [blocking queries](/api/index.html#blocking-queries) and 938 [required ACLs](/api/index.html#acls). 939 940 | Blocking Queries | ACL Required | 941 | ---------------- | -------------------------- | 942 | `YES` | `namespace:read-job` | 943 944 ### Parameters 945 946 - `:job_id` `(string: <required>)` - Specifies the ID of the job (as specified in 947 the job file during submission). This is specified as part of the path. 948 949 ### Sample Request 950 951 ```text 952 $ curl \ 953 https://localhost:4646/v1/job/my-job/deployments 954 ``` 955 956 ### Sample Response 957 958 ```json 959 [ 960 { 961 "ID": "85ee4a9a-339f-a921-a9ef-0550d20b2c61", 962 "JobID": "my-job", 963 "JobVersion": 1, 964 "JobModifyIndex": 19, 965 "JobCreateIndex": 7, 966 "TaskGroups": { 967 "cache": { 968 "AutoRevert": true, 969 "Promoted": false, 970 "PlacedCanaries": [ 971 "d0ad0808-2765-abf6-1e15-79fb7fe5a416", 972 "38c70cd8-81f2-1489-a328-87bb29ec0e0f" 973 ], 974 "DesiredCanaries": 2, 975 "DesiredTotal": 3, 976 "PlacedAllocs": 2, 977 "HealthyAllocs": 2, 978 "UnhealthyAllocs": 0 979 } 980 }, 981 "Status": "running", 982 "StatusDescription": "Deployment is running", 983 "CreateIndex": 21, 984 "ModifyIndex": 25 985 }, 986 { 987 "ID": "fb6070fb-4a44-e255-4e6f-8213eba3871a", 988 "JobID": "my-job", 989 "JobVersion": 0, 990 "JobModifyIndex": 7, 991 "JobCreateIndex": 7, 992 "TaskGroups": { 993 "cache": { 994 "AutoRevert": true, 995 "Promoted": false, 996 "PlacedCanaries": null, 997 "DesiredCanaries": 0, 998 "DesiredTotal": 3, 999 "PlacedAllocs": 3, 1000 "HealthyAllocs": 3, 1001 "UnhealthyAllocs": 0 1002 } 1003 }, 1004 "Status": "successful", 1005 "StatusDescription": "Deployment completed successfully", 1006 "CreateIndex": 9, 1007 "ModifyIndex": 17 1008 } 1009 ] 1010 ``` 1011 1012 1013 ## Read Job's Most Recent Deployment 1014 1015 This endpoint returns a single job's most recent deployment. 1016 1017 | Method | Path | Produces | 1018 | ------ | ----------------------------- | -------------------------- | 1019 | `GET` | `/v1/job/:job_id/deployment` | `application/json` | 1020 1021 The table below shows this endpoint's support for 1022 [blocking queries](/api/index.html#blocking-queries) and 1023 [required ACLs](/api/index.html#acls). 1024 1025 | Blocking Queries | ACL Required | 1026 | ---------------- | -------------------------- | 1027 | `YES` | `namespace:read-job` | 1028 1029 ### Parameters 1030 1031 - `:job_id` `(string: <required>)` - Specifies the ID of the job (as specified in 1032 the job file during submission). This is specified as part of the path. 1033 1034 ### Sample Request 1035 1036 ```text 1037 $ curl \ 1038 https://localhost:4646/v1/job/my-job/deployment 1039 ``` 1040 1041 ### Sample Response 1042 1043 ```json 1044 { 1045 "ID": "85ee4a9a-339f-a921-a9ef-0550d20b2c61", 1046 "JobID": "my-job", 1047 "JobVersion": 1, 1048 "JobModifyIndex": 19, 1049 "JobCreateIndex": 7, 1050 "TaskGroups": { 1051 "cache": { 1052 "AutoRevert": true, 1053 "Promoted": false, 1054 "PlacedCanaries": [ 1055 "d0ad0808-2765-abf6-1e15-79fb7fe5a416", 1056 "38c70cd8-81f2-1489-a328-87bb29ec0e0f" 1057 ], 1058 "DesiredCanaries": 2, 1059 "DesiredTotal": 3, 1060 "PlacedAllocs": 2, 1061 "HealthyAllocs": 2, 1062 "UnhealthyAllocs": 0 1063 } 1064 }, 1065 "Status": "running", 1066 "StatusDescription": "Deployment is running", 1067 "CreateIndex": 21, 1068 "ModifyIndex": 25 1069 } 1070 ``` 1071 1072 1073 ## Read Job Summary 1074 1075 This endpoint reads summary information about a job. 1076 1077 | Method | Path | Produces | 1078 | ------ | -------------------------- | -------------------------- | 1079 | `GET` | `/v1/job/:job_id/summary` | `application/json` | 1080 1081 The table below shows this endpoint's support for 1082 [blocking queries](/api/index.html#blocking-queries) and 1083 [required ACLs](/api/index.html#acls). 1084 1085 | Blocking Queries | ACL Required | 1086 | ---------------- | -------------------------- | 1087 | `YES` | `namespace:read-job` | 1088 1089 ### Parameters 1090 1091 - `:job_id` `(string: <required>)` - Specifies the ID of the job (as specified in 1092 the job file during submission). This is specified as part of the path. 1093 1094 ### Sample Request 1095 1096 ```text 1097 $ curl \ 1098 https://localhost:4646/v1/job/my-job/summary 1099 ``` 1100 1101 ### Sample Response 1102 1103 ```json 1104 { 1105 "JobID": "example", 1106 "Summary": { 1107 "cache": { 1108 "Queued": 0, 1109 "Complete": 0, 1110 "Failed": 0, 1111 "Running": 1, 1112 "Starting": 0, 1113 "Lost": 0 1114 } 1115 }, 1116 "Children": { 1117 "Pending": 0, 1118 "Running": 0, 1119 "Dead": 0 1120 }, 1121 "CreateIndex": 7, 1122 "ModifyIndex": 13 1123 } 1124 ``` 1125 1126 ## Update Existing Job 1127 1128 This endpoint registers a new job or updates an existing job. 1129 1130 | Method | Path | Produces | 1131 | ------- | -------------------------- | -------------------------- | 1132 | `POST` | `/v1/job/:job_id` | `application/json` | 1133 1134 The table below shows this endpoint's support for 1135 [blocking queries](/api/index.html#blocking-queries) and 1136 [required ACLs](/api/index.html#acls). 1137 1138 | Blocking Queries | ACL Required | 1139 | ---------------- | ------------ | 1140 | `NO` | `namespace:submit-job`<br>`namespace:sentinel-override` if `PolicyOverride` set | 1141 1142 ### Parameters 1143 1144 - `:job_id` `(string: <required>)` - Specifies the ID of the job (as specified in 1145 the job file during submission). This is specified as part of the path. 1146 1147 - `Job` `(Job: <required>)` - Specifies the JSON definition of the job. 1148 1149 - `EnforceIndex` `(bool: false)` - If set, the job will only be registered if the 1150 passed `JobModifyIndex` matches the current job's index. If the index is zero, 1151 the register only occurs if the job is new. This paradigm allows check-and-set 1152 style job updating. 1153 1154 - `JobModifyIndex` `(int: 0)` - Specifies the `JobModifyIndex` to enforce the 1155 current job is at. 1156 1157 - `PolicyOverride` `(bool: false)` - If set, any soft mandatory Sentinel policies 1158 will be overridden. This allows a job to be registered when it would be denied 1159 by policy. 1160 1161 ### Sample Payload 1162 1163 ```javascript 1164 { 1165 "Job": { 1166 // ... 1167 }, 1168 "EnforceIndex": true, 1169 "JobModifyIndex": 4 1170 } 1171 ``` 1172 1173 ### Sample Request 1174 1175 ```text 1176 $ curl \ 1177 --request POST \ 1178 --data @payload.json \ 1179 https://localhost:4646/v1/job/my-job 1180 ``` 1181 1182 ### Sample Response 1183 1184 ```json 1185 { 1186 "EvalID": "d092fdc0-e1fd-2536-67d8-43af8ca798ac", 1187 "EvalCreateIndex": 35, 1188 "JobModifyIndex": 34, 1189 } 1190 ``` 1191 1192 ## Dispatch Job 1193 1194 This endpoint dispatches a new instance of a parameterized job. 1195 1196 | Method | Path | Produces | 1197 | ------- | -------------------------- | -------------------------- | 1198 | `POST` | `/v1/job/:job_id/dispatch` | `application/json` | 1199 1200 The table below shows this endpoint's support for 1201 [blocking queries](/api/index.html#blocking-queries) and 1202 [required ACLs](/api/index.html#acls). 1203 1204 | Blocking Queries | ACL Required | 1205 | ---------------- | ------------------------------ | 1206 | `NO` | `namespace:dispatch-job` | 1207 1208 ### Parameters 1209 1210 - `:job_id` `(string: <required>)` - Specifies the ID of the job (as specified 1211 in the job file during submission). This is specified as part of the path. 1212 1213 - `Payload` `(string: "")` - Specifies a base64 encoded string containing the 1214 payload. This is limited to 15 KB. 1215 1216 - `Meta` `(meta<string|string>: nil)` - Specifies arbitrary metadata to pass to 1217 the job. 1218 1219 ### Sample Payload 1220 1221 ```json 1222 { 1223 "Payload": "A28C3==", 1224 "Meta": { 1225 "key": "Value" 1226 } 1227 } 1228 ``` 1229 1230 ### Sample Request 1231 1232 ```text 1233 $ curl \ 1234 --request POST \ 1235 --payload @payload.json \ 1236 https://localhost:4646/v1/job/my-job/dispatch 1237 ``` 1238 1239 ### Sample Response 1240 1241 ```json 1242 { 1243 "Index": 13, 1244 "JobCreateIndex": 12, 1245 "EvalCreateIndex": 13, 1246 "EvalID": "e5f55fac-bc69-119d-528a-1fc7ade5e02c", 1247 "DispatchedJobID": "example/dispatch-1485408778-81644024" 1248 } 1249 ``` 1250 1251 ## Revert to older Job Version 1252 1253 This endpoint reverts the job to an older version. 1254 1255 | Method | Path | Produces | 1256 | ------- | -------------------------- | -------------------------- | 1257 | `POST` | `/v1/job/:job_id/revert` | `application/json` | 1258 1259 The table below shows this endpoint's support for 1260 [blocking queries](/api/index.html#blocking-queries) and 1261 [required ACLs](/api/index.html#acls). 1262 1263 | Blocking Queries | ACL Required | 1264 | ---------------- | ---------------------------- | 1265 | `NO` | `namespace:submit-job` | 1266 1267 ### Parameters 1268 1269 - `JobID` `(string: <required>)` - Specifies the ID of the job (as specified 1270 in the job file during submission). This is specified as part of the path. 1271 1272 - `JobVersion` `(integer: 0)` - Specifies the job version to revert to. 1273 1274 - `EnforcePriorVersion` `(integer: nil)` - Optional value specifying the current 1275 job's version. This is checked and acts as a check-and-set value before 1276 reverting to the specified job. 1277 1278 ### Sample Payload 1279 1280 ```json 1281 { 1282 "JobID": "my-job", 1283 "JobVersion": 2, 1284 } 1285 ``` 1286 1287 ### Sample Request 1288 1289 ```text 1290 $ curl \ 1291 --request POST \ 1292 --payload @payload.json \ 1293 https://localhost:4646/v1/job/my-job/revert 1294 ``` 1295 1296 ### Sample Response 1297 1298 ```json 1299 { 1300 "EvalID": "d092fdc0-e1fd-2536-67d8-43af8ca798ac", 1301 "EvalCreateIndex": 35, 1302 "JobModifyIndex": 34, 1303 } 1304 ``` 1305 1306 1307 ## Set Job Stability 1308 1309 This endpoint sets the job's stability. 1310 1311 | Method | Path | Produces | 1312 | ------- | -------------------------- | -------------------------- | 1313 | `POST` | `/v1/job/:job_id/stable` | `application/json` | 1314 1315 The table below shows this endpoint's support for 1316 [blocking queries](/api/index.html#blocking-queries) and 1317 [required ACLs](/api/index.html#acls). 1318 1319 | Blocking Queries | ACL Required | 1320 | ---------------- | ---------------------------- | 1321 | `NO` | `namespace:submit-job` | 1322 1323 ### Parameters 1324 1325 - `JobID` `(string: <required>)` - Specifies the ID of the job (as specified 1326 in the job file during submission). This is specified as part of the path. 1327 1328 - `JobVersion` `(integer: 0)` - Specifies the job version to set the stability on. 1329 1330 - `Stable` `(bool: false)` - Specifies whether the job should be marked as 1331 stable or not. 1332 1333 ### Sample Payload 1334 1335 ```json 1336 { 1337 "JobID": "my-job", 1338 "JobVersion": 2, 1339 "Stable": true 1340 } 1341 ``` 1342 1343 ### Sample Request 1344 1345 ```text 1346 $ curl \ 1347 --request POST \ 1348 --payload @payload.json \ 1349 https://localhost:4646/v1/job/my-job/stable 1350 ``` 1351 1352 ### Sample Response 1353 1354 ```json 1355 { 1356 "JobModifyIndex": 34, 1357 } 1358 ``` 1359 1360 1361 ## Create Job Evaluation 1362 1363 This endpoint creates a new evaluation for the given job. This can be used to 1364 force run the scheduling logic if necessary. 1365 1366 | Method | Path | Produces | 1367 | ------- | -------------------------- | -------------------------- | 1368 | `POST` | `/v1/job/:job_id/evaluate` | `application/json` | 1369 1370 The table below shows this endpoint's support for 1371 [blocking queries](/api/index.html#blocking-queries) and 1372 [required ACLs](/api/index.html#acls). 1373 1374 | Blocking Queries | ACL Required | 1375 | ---------------- | -------------------------- | 1376 | `NO` | `namespace:read-job` | 1377 1378 ### Parameters 1379 1380 - `:job_id` `(string: <required>)` - Specifies the ID of the job (as specified in 1381 the job file during submission). This is specified as part of the path. 1382 1383 ### Sample Request 1384 1385 ```text 1386 $ curl \ 1387 --request POST \ 1388 https://localhost:4646/v1/job/my-job/evaluate 1389 ``` 1390 1391 ### Sample Response 1392 1393 ```json 1394 { 1395 "EvalID": "d092fdc0-e1fd-2536-67d8-43af8ca798ac", 1396 "EvalCreateIndex": 35, 1397 "JobModifyIndex": 34, 1398 } 1399 ``` 1400 1401 ## Create Job Plan 1402 1403 This endpoint invokes a dry-run of the scheduler for the job. 1404 1405 | Method | Path | Produces | 1406 | ------- | -------------------------- | -------------------------- | 1407 | `POST` | `/v1/job/:job_id/plan` | `application/json` | 1408 1409 The table below shows this endpoint's support for 1410 [blocking queries](/api/index.html#blocking-queries) and 1411 [required ACLs](/api/index.html#acls). 1412 1413 | Blocking Queries | ACL Required | 1414 | ---------------- | ------------ | 1415 | `NO` | `namespace:submit-job`<br>`namespace:sentinel-override` if `PolicyOverride` set | 1416 1417 ### Parameters 1418 1419 - `:job_id` `(string: <required>)` - Specifies the ID of the job (as specified in 1420 - the job file during submission). This is specified as part of the path. 1421 1422 - `Job` `(string: <required>)` - Specifies the JSON definition of the job. 1423 1424 - `Diff` `(bool: false)` - Specifies whether the diff structure between the 1425 submitted and server side version of the job should be included in the 1426 response. 1427 1428 - `PolicyOverride` `(bool: false)` - If set, any soft mandatory Sentinel policies 1429 will be overridden. This allows a job to be registered when it would be denied 1430 by policy. 1431 1432 ### Sample Payload 1433 1434 ```json 1435 { 1436 "Job": "...", 1437 "Diff": true, 1438 "PolicyOverride": false 1439 } 1440 ``` 1441 1442 ### Sample Request 1443 1444 ```text 1445 $ curl \ 1446 --request POST \ 1447 --payload @payload.json \ 1448 https://localhost:4646/v1/job/my-job/plan 1449 ``` 1450 1451 ### Sample Response 1452 1453 ```json 1454 { 1455 "Index": 0, 1456 "NextPeriodicLaunch": "0001-01-01T00:00:00Z", 1457 "Warnings": "", 1458 "Diff": { 1459 "Type": "Added", 1460 "TaskGroups": [ 1461 { 1462 "Updates": { 1463 "create": 1 1464 }, 1465 "Type": "Added", 1466 "Tasks": [ 1467 { 1468 "Type": "Added", 1469 "Objects": [ 1470 "..." 1471 ], 1472 "Name": "redis", 1473 "Fields": [ 1474 { 1475 "Type": "Added", 1476 "Old": "", 1477 "New": "docker", 1478 "Name": "Driver", 1479 "Annotations": null 1480 }, 1481 { 1482 "Type": "Added", 1483 "Old": "", 1484 "New": "5000000000", 1485 "Name": "KillTimeout", 1486 "Annotations": null 1487 } 1488 ], 1489 "Annotations": [ 1490 "forces create" 1491 ] 1492 } 1493 ], 1494 "Objects": [ 1495 "..." 1496 ], 1497 "Name": "cache", 1498 "Fields": [ 1499 "..." 1500 ] 1501 } 1502 ], 1503 "Objects": [ 1504 { 1505 "Type": "Added", 1506 "Objects": null, 1507 "Name": "Datacenters", 1508 "Fields": [ 1509 "..." 1510 ] 1511 }, 1512 { 1513 "Type": "Added", 1514 "Objects": null, 1515 "Name": "Constraint", 1516 "Fields": [ 1517 "..." 1518 ] 1519 }, 1520 { 1521 "Type": "Added", 1522 "Objects": null, 1523 "Name": "Update", 1524 "Fields": [ 1525 "..." 1526 ] 1527 } 1528 ], 1529 "ID": "example", 1530 "Fields": [ 1531 "..." 1532 ] 1533 }, 1534 "CreatedEvals": [ 1535 { 1536 "ModifyIndex": 0, 1537 "CreateIndex": 0, 1538 "SnapshotIndex": 0, 1539 "AnnotatePlan": false, 1540 "EscapedComputedClass": false, 1541 "NodeModifyIndex": 0, 1542 "NodeID": "", 1543 "JobModifyIndex": 0, 1544 "JobID": "example", 1545 "TriggeredBy": "job-register", 1546 "Type": "batch", 1547 "Priority": 50, 1548 "ID": "312e6a6d-8d01-0daf-9105-14919a66dba3", 1549 "Status": "blocked", 1550 "StatusDescription": "created to place remaining allocations", 1551 "Wait": 0, 1552 "NextEval": "", 1553 "PreviousEval": "80318ae4-7eda-e570-e59d-bc11df134817", 1554 "BlockedEval": "", 1555 "FailedTGAllocs": null, 1556 "ClassEligibility": { 1557 "v1:7968290453076422024": true 1558 } 1559 } 1560 ], 1561 "JobModifyIndex": 0, 1562 "FailedTGAllocs": { 1563 "cache": { 1564 "CoalescedFailures": 3, 1565 "AllocationTime": 46415, 1566 "Scores": null, 1567 "NodesEvaluated": 1, 1568 "NodesFiltered": 0, 1569 "NodesAvailable": { 1570 "dc1": 1 1571 }, 1572 "ClassFiltered": null, 1573 "ConstraintFiltered": null, 1574 "NodesExhausted": 1, 1575 "ClassExhausted": null, 1576 "DimensionExhausted": { 1577 "cpu": 1 1578 } 1579 } 1580 }, 1581 "Annotations": { 1582 "DesiredTGUpdates": { 1583 "cache": { 1584 "DestructiveUpdate": 0, 1585 "InPlaceUpdate": 0, 1586 "Stop": 0, 1587 "Migrate": 0, 1588 "Place": 11, 1589 "Ignore": 0 1590 } 1591 } 1592 } 1593 } 1594 ``` 1595 1596 #### Field Reference 1597 1598 - `Diff` - A diff structure between the submitted job and the server side 1599 version. The top-level object is a Job Diff which contains Task Group Diffs, 1600 which in turn contain Task Diffs. Each of these objects then has Object and 1601 Field Diff structures embedded. 1602 1603 - `NextPeriodicLaunch` - If the job being planned is periodic, this field will 1604 include the next launch time for the job. 1605 1606 - `CreatedEvals` - A set of evaluations that were created as a result of the 1607 dry-run. These evaluations can signify a follow-up rolling update evaluation 1608 or a blocked evaluation. 1609 1610 - `JobModifyIndex` - The `JobModifyIndex` of the server side version of this job. 1611 1612 - `FailedTGAllocs` - A set of metrics to understand any allocation failures that 1613 occurred for the Task Group. 1614 1615 - `Annotations` - Annotations include the `DesiredTGUpdates`, which tracks what 1616 - the scheduler would do given enough resources for each Task Group. 1617 1618 1619 ## Force New Periodic Instance 1620 1621 This endpoint forces a new instance of the periodic job. A new instance will be 1622 created even if it violates the job's 1623 [`prohibit_overlap`](/docs/job-specification/periodic.html#prohibit_overlap) 1624 settings. As such, this should be only used to immediately run a periodic job. 1625 1626 | Method | Path | Produces | 1627 | ------- | -------------------------------- | -------------------------- | 1628 | `POST` | `/v1/job/:job_id/periodic/force` | `application/json` | 1629 1630 The table below shows this endpoint's support for 1631 [blocking queries](/api/index.html#blocking-queries) and 1632 [required ACLs](/api/index.html#acls). 1633 1634 | Blocking Queries | ACL Required | 1635 | ---------------- | ---------------------- | 1636 | `NO` | `namespace:submit-job` | 1637 1638 ### Parameters 1639 1640 - `:job_id` `(string: <required>)` - Specifies the ID of the job (as specified in 1641 the job file during submission). This is specified as part of the path. 1642 1643 ### Sample Request 1644 1645 ```text 1646 $ curl \ 1647 --request POST \ 1648 https://localhost:4646/v1/job/my-job/periodic/force 1649 ``` 1650 1651 ### Sample Response 1652 1653 ```json 1654 { 1655 "EvalCreateIndex": 7, 1656 "EvalID": "57983ddd-7fcf-3e3a-fd24-f699ccfb36f4" 1657 } 1658 ``` 1659 1660 ## Stop a Job 1661 1662 This endpoint deregisters a job, and stops all allocations part of it. 1663 1664 | Method | Path | Produces | 1665 | -------- | -------------------------- | -------------------------- | 1666 | `DELETE` | `/v1/job/:job_id` | `application/json` | 1667 1668 The table below shows this endpoint's support for 1669 [blocking queries](/api/index.html#blocking-queries) and 1670 [required ACLs](/api/index.html#acls). 1671 1672 | Blocking Queries | ACL Required | 1673 | ---------------- | ---------------------------- | 1674 | `NO` | `namespace:submit-job` | 1675 1676 ### Parameters 1677 1678 - `:job_id` `(string: <required>)` - Specifies the ID of the job (as specified in 1679 the job file during submission). This is specified as part of the path. 1680 1681 - `Purge` `(bool: false)` - Specifies that the job should stopped and purged 1682 immediately. This means the job will not be queryable after being stopped. If 1683 not set, the job will be purged by the garbage collector. 1684 1685 ### Sample Request 1686 1687 ```text 1688 $ curl \ 1689 --request DELETE \ 1690 https://localhost:4646/v1/job/my-job?purge=true 1691 ``` 1692 1693 ### Sample Response 1694 1695 ```json 1696 { 1697 "EvalID": "d092fdc0-e1fd-2536-67d8-43af8ca798ac", 1698 "EvalCreateIndex": 35, 1699 "JobModifyIndex": 34, 1700 } 1701 ```