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