luxolus/open-nomad
2
0
Fork 0
Code Issues 1 Pull requests Packages Releases Wiki Activity
open-nomad/website/source/docs/http/job.html.md
Diptanu Choudhury 5163e0fa94 Updated docs for /job/allocations endpoint
2017-01-06 11:44:49 -08:00

12 KiB
Raw Blame History

layout page_title sidebar_current description
http HTTP API: /v1/job docs-http-job- The '/1/job' endpoint is used for CRUD on a single job.

/v1/job

The job endpoint is used for CRUD on a single job. By default, the agent's local region is used; another region can be specified using the ?region= query parameter.

GET

Description
Query a single job for its specification and status.
Method
GET
URL
`/v1/job/`
Parameters
None
Blocking Queries
[Supported](/docs/http/index.html#blocking-queries)
Returns
```javascript
{
"Region": "global",
"ID": "binstore-storagelocker",
"Name": "binstore-storagelocker",
"Type": "service",
"Priority": 50,
"AllAtOnce": false,
"Datacenters": [
    "us2",
    "eu1"
],
"Constraints": [
    {
        "LTarget": "${attr.kernel.os}",
        "RTarget": "windows",
        "Operand": "="
    }
],
"TaskGroups": [
    {
        "Name": "binsl",
        "Count": 5,
        "Constraints": [
            {
                "LTarget": "${attr.kernel.os}",
                "RTarget": "linux",
                "Operand": "="
            }
        ],
        "Tasks": [
            {
                "Name": "binstore",
                "Driver": "docker",
                "Config": {
                    "image": "hashicorp/binstore"
                },
                "Constraints": null,
                "Resources": {
                    "CPU": 500,
                    "MemoryMB": 0,
                    "DiskMB": 0,
                    "IOPS": 0,
                    "Networks": [
                        {
                            "Device": "",
                            "CIDR": "",
                            "IP": "",
                            "MBits": 100,
                            "ReservedPorts": null,
                            "DynamicPorts": null
                        }
                    ]
                },
                "Meta": null
            },
            {
                "Name": "storagelocker",
                "Driver": "java",
                "Config": {
                    "image": "hashicorp/storagelocker"
                },
                "Constraints": [
                    {
                        "LTarget": "${attr.kernel.arch}",
                        "RTarget": "amd64",
                        "Operand": "="
                    }
                ],
                "Resources": {
                    "CPU": 500,
                    "MemoryMB": 0,
                    "DiskMB": 0,
                    "IOPS": 0,
                    "Networks": null
                },
                "Meta": null
            }
        ],
        "Meta": {
            "elb_checks": "3",
            "elb_interval": "10",
            "elb_mode": "tcp"
        }
    }
],
"Update": {
    "Stagger": 0,
    "MaxParallel": 0
},
"Meta": {
    "foo": "bar"
},
"Status": "",
"StatusDescription": "",
"CreateIndex": 14,
"ModifyIndex": 14
}
```
Description
Query the allocations belonging to a single job.
Method
GET
URL
`/v1/job//allocations`
Parameters
  • all optional Returns all allocations of job with the given ID including those from past instances of the job.
Blocking Queries
[Supported](/docs/http/index.html#blocking-queries)
Returns
```javascript
[
{
    "ID": "3575ba9d-7a12-0c96-7b28-add168c67984",
    "EvalID": "151accaa-1ac6-90fe-d427-313e70ccbb88",
    "Name": "binstore-storagelocker.binsl[0]",
    "NodeID": "a703c3ca-5ff8-11e5-9213-970ee8879d1b",
    "JobID": "binstore-storagelocker",
    "TaskGroup": "binsl",
    "DesiredStatus": "run",
    "DesiredDescription": "",
    "ClientStatus": "running",
    "ClientDescription": "",
    "CreateIndex": 16,
    "ModifyIndex": 16
},
...
]
```
Description
Query the evaluations belonging to a single job.
Method
GET
URL
`/v1/job//evaluations`
Parameters
None
Blocking Queries
[Supported](/docs/http/index.html#blocking-queries)
Returns
```javascript
[
{
    "ID": "151accaa-1ac6-90fe-d427-313e70ccbb88",
    "Priority": 50,
    "Type": "service",
    "TriggeredBy": "job-register",
    "JobID": "binstore-storagelocker",
    "JobModifyIndex": 14,
    "NodeID": "",
    "NodeModifyIndex": 0,
    "Status": "complete",
    "StatusDescription": "",
    "Wait": 0,
    "NextEval": "",
    "PreviousEval": "",
    "CreateIndex": 15,
    "ModifyIndex": 17
},
...
]
```
Description
Query the summary of a job.
Method
GET
URL
`/v1/job//summary`
Parameters
None
Blocking Queries
[Supported](/docs/http/index.html#blocking-queries)
Returns
```javascript
{
  "JobID": "example",
  "Summary": {
    "cache": {
      "Queued": 0,
      "Complete": 0,
      "Failed": 0,
      "Running": 1,
      "Starting": 0,
      "Lost": 0
    }
  },
  "CreateIndex": 6,
  "ModifyIndex": 10
}
```

PUT / POST

Description
Registers a new job or updates an existing job
Method
PUT or POST
URL
`/v1/job/`
Parameters
  • Job required The JSON definition of the job.
Returns
```javascript
{
"EvalID": "d092fdc0-e1fd-2536-67d8-43af8ca798ac",
"EvalCreateIndex": 35,
"JobModifyIndex": 34,
}
```
Description
Creates a new evaluation for the given job. This can be used to force run the scheduling logic if necessary.
Method
PUT or POST
URL
`/v1/job//evaluate`
Parameters
None
Returns
```javascript
{
"EvalID": "d092fdc0-e1fd-2536-67d8-43af8ca798ac",
"EvalCreateIndex": 35,
"JobModifyIndex": 34,
}
```
Description
Invoke a dry-run of the scheduler for the job.
Method
PUT or POST
URL
`/v1/job//plan`
Parameters
  • Job required The JSON definition of the job.
  • Diff optional Whether the diff structure between the submitted and server side version of the job should be included in the response.
Returns
```javascript
{
  "Index": 0,
  "NextPeriodicLaunch": "0001-01-01T00:00:00Z",
  "Diff": {
	"Type": "Added",
	"TaskGroups": [
	  {
		"Updates": {
		  "create": 1
		},
		"Type": "Added",
		"Tasks": [
		  {
			"Type": "Added",
			"Objects": [...],
			"Name": "redis",
			"Fields": [
			  {
				"Type": "Added",
				"Old": "",
				"New": "docker",
				"Name": "Driver",
				"Annotations": null
			  },
			  {
				"Type": "Added",
				"Old": "",
				"New": "5000000000",
				"Name": "KillTimeout",
				"Annotations": null
			  }
			],
			"Annotations": [
			  "forces create"
			]
		  }
		],
		"Objects": [...],
		"Name": "cache",
		"Fields": [...]
	  }
	],
	"Objects": [
	  {
		"Type": "Added",
		"Objects": null,
		"Name": "Datacenters",
		"Fields": [...]
	  },
	  {
		"Type": "Added",
		"Objects": null,
		"Name": "Constraint",
		"Fields": [...]
	  },
	  {
		"Type": "Added",
		"Objects": null,
		"Name": "Update",
		"Fields": [...]
	  }
	],
	"ID": "example",
    "Fields": [...],
	  ...
	]
  },
"CreatedEvals": [
	{
	  "ModifyIndex": 0,
	  "CreateIndex": 0,
	  "SnapshotIndex": 0,
	  "AnnotatePlan": false,
	  "EscapedComputedClass": false,
	  "NodeModifyIndex": 0,
	  "NodeID": "",
	  "JobModifyIndex": 0,
	  "JobID": "example",
	  "TriggeredBy": "job-register",
	  "Type": "batch",
	  "Priority": 50,
	  "ID": "312e6a6d-8d01-0daf-9105-14919a66dba3",
	  "Status": "blocked",
	  "StatusDescription": "created to place remaining allocations",
	  "Wait": 0,
	  "NextEval": "",
	  "PreviousEval": "80318ae4-7eda-e570-e59d-bc11df134817",
	  "BlockedEval": "",
	  "FailedTGAllocs": null,
	  "ClassEligibility": {
		"v1:7968290453076422024": true
	  }
	}
  ],
  "JobModifyIndex": 0,
  "FailedTGAllocs": {
	"cache": {
	  "CoalescedFailures": 3,
	  "AllocationTime": 46415,
	  "Scores": null,
	  "NodesEvaluated": 1,
	  "NodesFiltered": 0,
	  "NodesAvailable": {
		"dc1": 1
	  },
	  "ClassFiltered": null,
	  "ConstraintFiltered": null,
	  "NodesExhausted": 1,
	  "ClassExhausted": null,
	  "DimensionExhausted": {
		"cpu exhausted": 1
	  }
	}
  },
  "Annotations": {
	"DesiredTGUpdates": {
	  "cache": {
		"DestructiveUpdate": 0,
		"InPlaceUpdate": 0,
		"Stop": 0,
		"Migrate": 0,
		"Place": 11,
		"Ignore": 0
	  }
	}
  }
}
```
Field Reference
  • Diff A diff structure between the submitted job and the server side version. The top-level object is a Job Diff which contains Task Group Diffs, which in turn contain Task Diffs. Each of these objects then has Object and Field Diff structures embedded.
  • NextPeriodicLaunch If the job being planned is periodic, this field will include the next launch time for the job.
  • CreatedEvals A set of evaluations that were created as a result of the dry-run. These evaluations can signify a follow-up rolling update evaluation or a blocked evaluation.
  • JobModifyIndex The JobModifyIndex of the server side version of this job.
  • FailedTGAllocs A set of metrics to understand any allocation failures that occurred for the Task Group.
  • Annotations Annotations include the DesiredTGUpdates, which tracks what the scheduler would do given enough resources for each Task Group.
Description
Forces a new instance of the periodic job. A new instance will be created even if it violates the job's [`prohibit_overlap`](/docs/job-specification/periodic.html#prohibit_overlap) settings. As such, this should be only used to immediately run a periodic job.
Method
PUT or POST
URL
`/v1/job//periodic/force`
Parameters
None
Returns
```javascript
{
"EvalCreateIndex": 7,
"EvalID": "57983ddd-7fcf-3e3a-fd24-f699ccfb36f4"
}
```

DELETE

Description
Deregisters a job, and stops all allocations part of it.
Method
DELETE
URL
`/v1/job/`
Parameters
None
Returns
```javascript
{
"EvalID": "d092fdc0-e1fd-2536-67d8-43af8ca798ac",
"EvalCreateIndex": 35,
"JobModifyIndex": 34,
}
```