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