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>