github.com/mattyr/nomad@v0.3.3-0.20160919021406-3485a065154a/website/source/docs/http/job.html.md (about) 1 --- 2 layout: "http" 3 page_title: "HTTP API: /v1/job" 4 sidebar_current: "docs-http-job-" 5 description: |- 6 The '/1/job' endpoint is used for CRUD on a single job. 7 --- 8 9 # /v1/job 10 11 The `job` endpoint is used for CRUD on a single job. By default, the agent's local 12 region is used; another region can be specified using the `?region=` query parameter. 13 14 ## GET 15 16 <dl> 17 <dt>Description</dt> 18 <dd> 19 Query a single job for its specification and status. 20 </dd> 21 22 <dt>Method</dt> 23 <dd>GET</dd> 24 25 <dt>URL</dt> 26 <dd>`/v1/job/<ID>`</dd> 27 28 <dt>Parameters</dt> 29 <dd> 30 None 31 </dd> 32 33 <dt>Blocking Queries</dt> 34 <dd> 35 [Supported](/docs/http/index.html#blocking-queries) 36 </dd> 37 38 <dt>Returns</dt> 39 <dd> 40 41 ```javascript 42 { 43 "Region": "global", 44 "ID": "binstore-storagelocker", 45 "Name": "binstore-storagelocker", 46 "Type": "service", 47 "Priority": 50, 48 "AllAtOnce": false, 49 "Datacenters": [ 50 "us2", 51 "eu1" 52 ], 53 "Constraints": [ 54 { 55 "LTarget": "${attr.kernel.os}", 56 "RTarget": "windows", 57 "Operand": "=" 58 } 59 ], 60 "TaskGroups": [ 61 { 62 "Name": "binsl", 63 "Count": 5, 64 "Constraints": [ 65 { 66 "LTarget": "${attr.kernel.os}", 67 "RTarget": "linux", 68 "Operand": "=" 69 } 70 ], 71 "Tasks": [ 72 { 73 "Name": "binstore", 74 "Driver": "docker", 75 "Config": { 76 "image": "hashicorp/binstore" 77 }, 78 "Constraints": null, 79 "Resources": { 80 "CPU": 500, 81 "MemoryMB": 0, 82 "DiskMB": 0, 83 "IOPS": 0, 84 "Networks": [ 85 { 86 "Device": "", 87 "CIDR": "", 88 "IP": "", 89 "MBits": 100, 90 "ReservedPorts": null, 91 "DynamicPorts": null 92 } 93 ] 94 }, 95 "Meta": null 96 }, 97 { 98 "Name": "storagelocker", 99 "Driver": "java", 100 "Config": { 101 "image": "hashicorp/storagelocker" 102 }, 103 "Constraints": [ 104 { 105 "LTarget": "${attr.kernel.arch}", 106 "RTarget": "amd64", 107 "Operand": "=" 108 } 109 ], 110 "Resources": { 111 "CPU": 500, 112 "MemoryMB": 0, 113 "DiskMB": 0, 114 "IOPS": 0, 115 "Networks": null 116 }, 117 "Meta": null 118 } 119 ], 120 "Meta": { 121 "elb_checks": "3", 122 "elb_interval": "10", 123 "elb_mode": "tcp" 124 } 125 } 126 ], 127 "Update": { 128 "Stagger": 0, 129 "MaxParallel": 0 130 }, 131 "Meta": { 132 "foo": "bar" 133 }, 134 "Status": "", 135 "StatusDescription": "", 136 "CreateIndex": 14, 137 "ModifyIndex": 14 138 } 139 ``` 140 141 </dd> 142 </dl> 143 144 <dl> 145 <dt>Description</dt> 146 <dd> 147 Query the allocations belonging to a single job. 148 </dd> 149 150 <dt>Method</dt> 151 <dd>GET</dd> 152 153 <dt>URL</dt> 154 <dd>`/v1/job/<ID>/allocations`</dd> 155 156 <dt>Parameters</dt> 157 <dd> 158 None 159 </dd> 160 161 <dt>Blocking Queries</dt> 162 <dd> 163 [Supported](/docs/http/index.html#blocking-queries) 164 </dd> 165 166 <dt>Returns</dt> 167 <dd> 168 169 ```javascript 170 [ 171 { 172 "ID": "3575ba9d-7a12-0c96-7b28-add168c67984", 173 "EvalID": "151accaa-1ac6-90fe-d427-313e70ccbb88", 174 "Name": "binstore-storagelocker.binsl[0]", 175 "NodeID": "a703c3ca-5ff8-11e5-9213-970ee8879d1b", 176 "JobID": "binstore-storagelocker", 177 "TaskGroup": "binsl", 178 "DesiredStatus": "run", 179 "DesiredDescription": "", 180 "ClientStatus": "running", 181 "ClientDescription": "", 182 "CreateIndex": 16, 183 "ModifyIndex": 16 184 }, 185 ... 186 ] 187 ``` 188 189 </dd> 190 </dl> 191 192 <dl> 193 <dt>Description</dt> 194 <dd> 195 Query the evaluations belonging to a single job. 196 </dd> 197 198 <dt>Method</dt> 199 <dd>GET</dd> 200 201 <dt>URL</dt> 202 <dd>`/v1/job/<ID>/evaluations`</dd> 203 204 <dt>Parameters</dt> 205 <dd> 206 None 207 </dd> 208 209 <dt>Blocking Queries</dt> 210 <dd> 211 [Supported](/docs/http/index.html#blocking-queries) 212 </dd> 213 214 <dt>Returns</dt> 215 <dd> 216 217 ```javascript 218 [ 219 { 220 "ID": "151accaa-1ac6-90fe-d427-313e70ccbb88", 221 "Priority": 50, 222 "Type": "service", 223 "TriggeredBy": "job-register", 224 "JobID": "binstore-storagelocker", 225 "JobModifyIndex": 14, 226 "NodeID": "", 227 "NodeModifyIndex": 0, 228 "Status": "complete", 229 "StatusDescription": "", 230 "Wait": 0, 231 "NextEval": "", 232 "PreviousEval": "", 233 "CreateIndex": 15, 234 "ModifyIndex": 17 235 }, 236 ... 237 ] 238 ``` 239 240 </dd> 241 </dl> 242 243 <dl> 244 <dt>Description</dt> 245 <dd> 246 Query the summary of a job. 247 </dd> 248 249 <dt>Method</dt> 250 <dd>GET</dd> 251 252 <dt>URL</dt> 253 <dd>`/v1/job/<ID>/summary`</dd> 254 255 <dt>Parameters</dt> 256 <dd> 257 None 258 </dd> 259 260 <dt>Blocking Queries</dt> 261 <dd> 262 [Supported](/docs/http/index.html#blocking-queries) 263 </dd> 264 265 <dt>Returns</dt> 266 <dd> 267 268 ```javascript 269 { 270 "JobID": "example", 271 "Summary": { 272 "cache": { 273 "Queued": 0, 274 "Complete": 0, 275 "Failed": 0, 276 "Running": 1, 277 "Starting": 0, 278 "Lost": 0 279 } 280 }, 281 "CreateIndex": 6, 282 "ModifyIndex": 10 283 } 284 ``` 285 286 </dd> 287 </dl> 288 289 290 ## PUT / POST 291 292 <dl> 293 <dt>Description</dt> 294 <dd> 295 Registers a new job or updates an existing job 296 </dd> 297 298 <dt>Method</dt> 299 <dd>PUT or POST</dd> 300 301 <dt>URL</dt> 302 <dd>`/v1/job/<ID>`</dd> 303 304 <dt>Parameters</dt> 305 <dd> 306 <ul> 307 <li> 308 <span class="param">Job</span> 309 <span class="param-flags">required</span> 310 The JSON definition of the job. The general structure is given 311 by the [job specification](/docs/jobspec/index.html), and matches 312 the return response of GET. 313 </li> 314 </ul> 315 </dd> 316 317 <dt>Returns</dt> 318 <dd> 319 320 ```javascript 321 { 322 "EvalID": "d092fdc0-e1fd-2536-67d8-43af8ca798ac", 323 "EvalCreateIndex": 35, 324 "JobModifyIndex": 34, 325 } 326 ``` 327 328 </dd> 329 </dl> 330 331 <dl> 332 <dt>Description</dt> 333 <dd> 334 Creates a new evaluation for the given job. This can be used to force 335 run the scheduling logic if necessary. 336 </dd> 337 338 <dt>Method</dt> 339 <dd>PUT or POST</dd> 340 341 <dt>URL</dt> 342 <dd>`/v1/job/<ID>/evaluate`</dd> 343 344 <dt>Parameters</dt> 345 <dd> 346 None 347 </dd> 348 349 <dt>Returns</dt> 350 <dd> 351 352 ```javascript 353 { 354 "EvalID": "d092fdc0-e1fd-2536-67d8-43af8ca798ac", 355 "EvalCreateIndex": 35, 356 "JobModifyIndex": 34, 357 } 358 ``` 359 360 </dd> 361 </dl> 362 363 <dl> 364 <dt>Description</dt> 365 <dd> 366 Invoke a dry-run of the scheduler for the job. 367 </dd> 368 369 <dt>Method</dt> 370 <dd>PUT or POST</dd> 371 372 <dt>URL</dt> 373 <dd>`/v1/job/<ID>/plan`</dd> 374 375 <dt>Parameters</dt> 376 <dd> 377 <ul> 378 <li> 379 <span class="param">Job</span> 380 <span class="param-flags">required</span> 381 The JSON definition of the job. The general structure is given 382 by the [job specification](/docs/jobspec/index.html), and matches 383 the return response of GET. 384 </li> 385 <li> 386 <span class="param">Diff</span> 387 <span class="param-flags">optional</span> 388 Whether the diff structure between the submitted and server side version 389 of the job should be included in the response. 390 </li> 391 </ul> 392 </dd> 393 394 <dt>Returns</dt> 395 <dd> 396 397 ```javascript 398 { 399 "Index": 0, 400 "NextPeriodicLaunch": "0001-01-01T00:00:00Z", 401 "Diff": { 402 "Type": "Added", 403 "TaskGroups": [ 404 { 405 "Updates": { 406 "create": 1 407 }, 408 "Type": "Added", 409 "Tasks": [ 410 { 411 "Type": "Added", 412 "Objects": [...], 413 "Name": "redis", 414 "Fields": [ 415 { 416 "Type": "Added", 417 "Old": "", 418 "New": "docker", 419 "Name": "Driver", 420 "Annotations": null 421 }, 422 { 423 "Type": "Added", 424 "Old": "", 425 "New": "5000000000", 426 "Name": "KillTimeout", 427 "Annotations": null 428 } 429 ], 430 "Annotations": [ 431 "forces create" 432 ] 433 } 434 ], 435 "Objects": [...], 436 "Name": "cache", 437 "Fields": [...] 438 } 439 ], 440 "Objects": [ 441 { 442 "Type": "Added", 443 "Objects": null, 444 "Name": "Datacenters", 445 "Fields": [...] 446 }, 447 { 448 "Type": "Added", 449 "Objects": null, 450 "Name": "Constraint", 451 "Fields": [...] 452 }, 453 { 454 "Type": "Added", 455 "Objects": null, 456 "Name": "Update", 457 "Fields": [...] 458 } 459 ], 460 "ID": "example", 461 "Fields": [...], 462 ... 463 ] 464 }, 465 "CreatedEvals": [ 466 { 467 "ModifyIndex": 0, 468 "CreateIndex": 0, 469 "SnapshotIndex": 0, 470 "AnnotatePlan": false, 471 "EscapedComputedClass": false, 472 "NodeModifyIndex": 0, 473 "NodeID": "", 474 "JobModifyIndex": 0, 475 "JobID": "example", 476 "TriggeredBy": "job-register", 477 "Type": "batch", 478 "Priority": 50, 479 "ID": "312e6a6d-8d01-0daf-9105-14919a66dba3", 480 "Status": "blocked", 481 "StatusDescription": "created to place remaining allocations", 482 "Wait": 0, 483 "NextEval": "", 484 "PreviousEval": "80318ae4-7eda-e570-e59d-bc11df134817", 485 "BlockedEval": "", 486 "FailedTGAllocs": null, 487 "ClassEligibility": { 488 "v1:7968290453076422024": true 489 } 490 } 491 ], 492 "JobModifyIndex": 0, 493 "FailedTGAllocs": { 494 "cache": { 495 "CoalescedFailures": 3, 496 "AllocationTime": 46415, 497 "Scores": null, 498 "NodesEvaluated": 1, 499 "NodesFiltered": 0, 500 "NodesAvailable": { 501 "dc1": 1 502 }, 503 "ClassFiltered": null, 504 "ConstraintFiltered": null, 505 "NodesExhausted": 1, 506 "ClassExhausted": null, 507 "DimensionExhausted": { 508 "cpu exhausted": 1 509 } 510 } 511 }, 512 "Annotations": { 513 "DesiredTGUpdates": { 514 "cache": { 515 "DestructiveUpdate": 0, 516 "InPlaceUpdate": 0, 517 "Stop": 0, 518 "Migrate": 0, 519 "Place": 11, 520 "Ignore": 0 521 } 522 } 523 } 524 } 525 ``` 526 527 </dd> 528 529 <dt>Field Reference</dt> 530 <dd> 531 <ul> 532 <li> 533 <span class="param">Diff</span> 534 A diff structure between the submitted job and the server side version. 535 The top-level object is a Job Diff which contains, Task Group Diffs 536 which in turn contain Task Diffs. Each of these objects then has Object 537 and Field Diff structures in-bedded. 538 </li> 539 <li> 540 <span class="param">NextPeriodicLaunch</span> 541 If the job being planned is periodic, this field will include the next 542 launch time for the job. 543 </li> 544 <li> 545 <span class="param">CreatedEvals</span> 546 A set of evaluations that were created as a result of the dry-run. These 547 evaluations can signify a follow-up rolling update evaluation or a 548 blocked evaluation. 549 </li> 550 <li> 551 <span class="param">JobModifyIndex</span> 552 The JobModifyIndex of the server side version of this job. 553 </li> 554 <li> 555 <span class="param">FailedTGAllocs</span> 556 A set of metrics to understand any allocation failures that occurred for 557 the Task Group. 558 </li> 559 <li> 560 <span class="param">Annotations</span> 561 Annotations include the DesiredTGUpdates, which tracks what the 562 scheduler would do given enough resources for each Task Group. 563 </li> 564 </ul> 565 </dd> 566 </dl> 567 568 569 <dl> 570 <dt>Description</dt> 571 <dd> 572 Forces a new instance of the periodic job. A new instance will be created 573 even if it violates the job's 574 [`prohibit_overlap`](/docs/jobspec/index.html#prohibit_overlap) settings. As 575 such, this should be only used to immediately run a periodic job. 576 </dd> 577 578 <dt>Method</dt> 579 <dd>PUT or POST</dd> 580 581 <dt>URL</dt> 582 <dd>`/v1/job/<ID>/periodic/force`</dd> 583 584 <dt>Parameters</dt> 585 <dd> 586 None 587 </dd> 588 589 <dt>Returns</dt> 590 <dd> 591 592 ```javascript 593 { 594 "EvalCreateIndex": 7, 595 "EvalID": "57983ddd-7fcf-3e3a-fd24-f699ccfb36f4" 596 } 597 ``` 598 599 </dd> 600 </dl> 601 602 ## DELETE 603 604 <dl> 605 <dt>Description</dt> 606 <dd> 607 Deregisters a job, and stops all allocations part of it. 608 </dd> 609 610 <dt>Method</dt> 611 <dd>DELETE</dd> 612 613 <dt>URL</dt> 614 <dd>`/v1/job/<ID>`</dd> 615 616 <dt>Parameters</dt> 617 <dd> 618 None 619 </dd> 620 621 <dt>Returns</dt> 622 <dd> 623 624 ```javascript 625 { 626 "EvalID": "d092fdc0-e1fd-2536-67d8-43af8ca798ac", 627 "EvalCreateIndex": 35, 628 "JobModifyIndex": 34, 629 } 630 ``` 631 632 </dd> 633 </dl>