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
Alex Dadgar 1f817b6a50 Merge pull request #2566 from hashicorp/f-job-versions 
Track multiple job versions and introduce a stop state for jobs
2017-04-19 11:11:11 -07:00

15 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": "",
"Version": 3,
"CreateIndex": 14,
"ModifyIndex": 14
}
```
Description
Query all versions of a single job.
Method
GET
URL
`/v1/job//versions`
Parameters
None
Blocking Queries
[Supported](/docs/http/index.html#blocking-queries)
Returns
```javascript
[
    {
        "Region": "global",
        "ID": "binstore-storagelocker",
        "Version": 2,
        ...
    },
    {
        "Region": "global",
        "ID": "binstore-storagelocker",
        "Version": 1,
        ...
    },
    {
        "Region": "global",
        "ID": "binstore-storagelocker",
        "Version": 0,
        ...
    }
]
```
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",
  "Children": {
    "Dead": 0,
    "Running": 7,
    "Pending": 2
  },
  "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.
  • EnforceIndex optional If EnforceIndex is set the job will only be registered if the passed JobModifyIndex matches the current job's index. If the index is zero, the register only occurs if the job is new. This paradigm allows check-and-set style job updating.
  • JobModifyIndex optional The JobModifyIndex to enforce the current job is at.
Returns
```javascript
{
"EvalID": "d092fdc0-e1fd-2536-67d8-43af8ca798ac",
"EvalCreateIndex": 35,
"JobModifyIndex": 34,
}
```
Description
Dispatch a new instance of a parameterized job.
Method
PUT or POST
URL
`/v1/job//dispatch`
Parameters
  • Payload optional A `[]byte` array encoded as a base64 string with a maximum size of 16KiB.
  • Meta optional A `map[string]string` of metadata keys to their values.
Returns
```javascript
{
"Index": 13,
"JobCreateIndex": 12,
"EvalCreateIndex": 13,
"EvalID": "e5f55fac-bc69-119d-528a-1fc7ade5e02c",
"DispatchedJobID": "example/dispatch-1485408778-81644024"
}
```
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,
}
```