Jobs endpoints
Sections
Use the /jobs
endpoint to examine orchestrator jobs and their
details.
GET /jobs
List all of the jobs known to the orchestrator.
Parameters
The request accepts the following query parameters:
Parameter | Definition |
---|---|
limit
|
Return only the most recent n number of jobs. |
|
Return results offset n records into the result set. |
order_by
|
Return results ordered by a column. Ordering is available
on owner , timestamp , environment , name , and state . Orderings requested on owner are applied to the login subfield of owner . |
order
|
Indicates whether results are returned in ascending or descending order. Valid values are "asc" and "desc". Defaults to "asc" |
type |
Indicates the type of job. Matches the command that created the
job, which is either deploy , task , or
plan_task
|
task |
An optional task name to match against. Partial matches are
supported. If type is specified, the task option
is only allowed for task and plan_task types.
|
For example:
https://orchestrator.example.com:8143/orchestrator/v1/jobs/352/jobs?limit=20&offset=20
Copied!
Response format
The response is a JSON object that lists orchestrator jobs and associated details and pagination information.
For information about jobs, the following keys are used:
Key | Definition |
---|---|
items
|
Contains an array of all the known jobs. |
id
|
An absolute URL to the given job. |
name
|
The name of the given job. |
state
|
The current state of the job:
, ready , running , stopping , stopped , finished , or
failed . |
command
|
The command that created that job. |
type |
The type of job. Either deploy ,
task , plan_task , plan_script ,
plan_upload , plan_command ,
plan_wait , plan_apply ,
plan_apply_prep
|
options
|
All of the options used to create that job. The schema of options might vary based on the command. |
owner
|
The subject id and login for the user that requested the job. |
description
|
(deprecated) A user-provided description of the job. For
future compatibility, use the description in options . |
timestamp
|
The time when the job state last changed. |
created_timestamp |
The time the job was created. |
finished_timestamp |
The time the job finished. |
duration |
The number of seconds the job took to run. |
environment
|
(deprecated) The environment that the job operates in. |
node_count
|
The number of nodes the job runs on. |
node_states
|
A JSON map containing the counts of nodes involved with the job by current node
state. Unrepresented states are not displayed. This field is |
nodes
|
A link to get more information about the nodes participating in a given job. |
report
|
A link to the report for a given job. |
events
|
A link to the events for a given job |
userdata
|
An object of arbitrary key/value data supplied to the job. |
Key | Definition |
---|---|
pagination |
Contains information about the limit, offset, and total number of items. |
limit |
The number of items the request was limited to. |
offset |
The offset from the start of the collection. Offset begins at zero. |
order_by |
Either owner , timestamp , environment , name , or state . |
order |
Either asc or desc . |
total |
The total number of items in the collection, ignoring limit and offset
|
type |
The type of job filtered on, if any. Either deploy , task , or plan_task . |
For example:
{
"items": [
{
"id": "https://orchestrator.example.com:8143/orchestrator/v1/jobs/1234",
"name": "1234",
"state": "finished",
"command": "deploy",
"type": "deploy",
"node_count": 5,
"node_states": {
"finished": 2,
"errored": 1,
"failed": 1,
"running": 1
},
"options": {
"concurrency": null,
"noop": false,
"trace": false,
"debug": false,
"scope": {},
"enforce_environment": true,
"environment": "production",
"evaltrace": false,
"target": null,
"description": "deploy the web app"
},
"owner" : {
"email" : "admin@example.com",
"is_revoked" : false,
"last_login" : "2020-05-05T14:03:06.226Z",
"is_remote" : true,
"login" : "admin",
"inherited_role_ids" : [ 2 ],
"group_ids" : [ "9a588fd8-3daa-4fc2-a396-bf88945def1e" ],
"is_superuser" : false,
"id" : "751a8f7e-b53a-4ccd-9f4f-e93db6aa38ec",
"role_ids" : [ 1 ],
"display_name" : "Admin",
"is_group" : false
},
"description": "deploy the web app",
"timestamp": "2016-05-20T16:45:31Z",
"started_timestamp": "2016-05-20T16:41:15Z",
"finished_timestamp": "2016-05-20T16:45:31Z",
"duration": "256.0",
"environment": {
"name": "production"
},
"report": {
"id": "https://localhost:8143/orchestrator/v1/jobs/375/report"
},
"events": {
"id": "https://localhost:8143/orchestrator/v1/jobs/375/events"
},
"nodes": {
"id": "https://localhost:8143/orchestrator/v1/jobs/375/nodes"
},
"userdata": {
"servicenow_ticket": "INC0011211"
}
},
{
"description": "",
"report": {
"id": "https://orchestrator.example.com:8143/orchestrator/v1/jobs/1235/report"
},
"name": "1235",
"events": {
"id": "https://orchestrator.example.com:8143/orchestrator/v1/jobs/1235/events"
},
"command": "plan_task",
"type": "plan_task",
"state": "finished",
"nodes": {
"id": "https://orchestrator.example.com:8143/orchestrator/v1/jobs/1235/nodes"
},
"id": "https://orchestrator.example.com:8143/orchestrator/v1/jobs/1235",
"environment": {
"name": ""
},
"options": {
"description": "",
"plan_job": 197,
"noop": null,
"task": "facts",
"sensitive": [],
"scheduled-job-id": null,
"params": {},
"scope": {
"nodes": [
"orchestrator.example.com"
]
},
"project": {
"project_id": "foo_id",
"ref": "524df30f58002d30a3549c52c34a1cce29da2981"
}
},
"timestamp": "2020-09-14T18:00:12Z",
"started_timestamp": "2020-09-14T17:59:05Z",
"finished_timestamp": "2020-09-14T18:00:12Z",
"duration": "67.34",
"owner": {
"email": "",
"is_revoked": false,
"last_login": "2020-08-05T17:54:07.045Z",
"is_remote": false,
"login": "admin",
"is_superuser": true,
"id": "42bf351c-f9ec-40af-84ad-e976fec7f4bd",
"role_ids": [
1
],
"display_name": "Administrator",
"is_group": false
},
"node_count": 1,
"node_states": {
"finished": 1
},
"userdata": {}
}
],
"pagination": {
"limit": 20,
"offset": 0,
"order": "asc",
"order_by": "timestamp",
"total": 2,
"type": ""
}
}
Copied!
Error responses
For this endpoint, the kind
key of the error displays the conflict.
Key | Definition |
---|---|
puppetlabs.orchestrator/validation-error
|
If the limit parameter is not an integer, the
server returns a 400 response. |
GET /jobs/:job-id
List all details of a given job.
Response format
The response is a JSON object that lists all details of a given job, and uses these keys:
Key | Definition |
---|---|
id
|
An absolute URL to the given job. |
name
|
The name of the given job. |
state
|
The current state of the job: new , ready , running , stopping , stopped , finished , or
failed . |
command
|
The command that created that job. |
type |
The type of job. Either deploy ,
task , plan_task ,
plan_script , plan_upload , plan_command , plan_wait , plan_apply, or plan_apply_prep
|
options
|
All of the options used to create that job. |
owner
|
The subject id and login for the user that requested the job. |
description
|
(deprecated) A user-provided description of the job. |
timestamp
|
The time when the job state last changed. |
environment
|
The environment that the job operates in. |
node_count
|
The number of nodes the job runs on. |
nodes
|
A link to get more information about the nodes participating in a given job. |
report
|
A link to the report for a given job. |
events
|
A link to the events for a given job. |
status
|
The various enter and exit times for a given job state. |
userdata
|
An object of arbitrary key/value data supplied to the job. |
{
"id" : "https://orchestrator.example.com:8143/orchestrator/v1/jobs/1234",
"name" : "1234",
"command" : "deploy",
"type": "deploy",
"state": "finished",
"options" : {
"concurrency" : null,
"noop" : false,
"trace" : false,
"debug" : false,
"scope" : {
"application" : "Wordpress_app" },
"enforce_environment" : true,
"environment" : "production",
"evaltrace" : false,
"target" : null
},
"node_count" : 5,
"owner" : {
"email" : "admin@example.com",
"is_revoked" : false,
"last_login" : "2020-05-05T14:03:06.226Z",
"is_remote" : true,
"login" : "admin",
"inherited_role_ids" : [ 2 ],
"group_ids" : [ "9a588fd8-3daa-4fc2-a396-bf88945def1e" ],
"is_superuser" : false,
"id" : "751a8f7e-b53a-4ccd-9f4f-e93db6aa38ec",
"role_ids" : [ 1 ],
"display_name" : "Admin",
"is_group" : false
},
"description" : "deploy the web app",
"timestamp": "2016-05-20T16:45:31Z",
"started_timestamp": "2016-05-20T16:41:15Z",
"finished_timestamp": "2016-05-20T16:45:31Z",
"duration": "256.0",
"environment" : {
"name" : "production"
},
"status" : [ {
"state" : "new",
"enter_time" : "2016-04-11T18:44:31Z",
"exit_time" : "2016-04-11T18:44:31Z"
}, {
"state" : "ready",
"enter_time" : "2016-04-11T18:44:31Z",
"exit_time" : "2016-04-11T18:44:31Z"
}, {
"state" : "running",
"enter_time" : "2016-04-11T18:44:31Z",
"exit_time" : "2016-04-11T18:45:31Z"
}, {
"state" : "finished",
"enter_time" : "2016-04-11T18:45:31Z",
"exit_time" : null
} ],
"nodes" : { "id" : "https://orchestrator.example.com:8143/orchestrator/v1/jobs/1234/nodes" },
"report" : { "id" : "https://orchestrator.example.com:8143/orchestrator/v1/jobs/1234/report" },
"userdata": {}
}
Copied!
Error responses
For this endpoint, the kind
key of the error displays the conflict.
Key | Definition |
---|---|
puppetlabs.orchestrator/validation-error
|
If the job-id in the request is not an integer,
the server returns a 400 response. |
puppetlabs.orchestrator/unknown-job
|
If the job does not exist, the server returns a
404 response. |
GET /jobs/:job-id/nodes
List all of the nodes associated with a given job.
Request format
Key | Definition |
---|---|
limit |
Returns only the most recent n number of node results in a job. |
offset |
Returns results offset n records into the result set. |
order_by |
Returns results ordered by a column. Ordering is available on name , duration , state , start_timestamp ,
and finish_timestamp . |
order |
Indicates whether results should be returned in ascending (asc ) or descending (desc ) order. Defaults to asc . |
state |
Returns only the nodes in the state supplied. One of either new , ready , running , stopping ,
stopped , finished , or failed , |
Response format
The response is a JSON object that details the nodes associated with a job.
next-events
is an object containing information about where
to find events about the job. It has the following keys:
Key | Definition |
---|---|
id
|
The url of the next event. |
event
|
The next event id. |
items
: a list of all the nodes associated with the job,
where each node has the following keys:
Key | Definition |
---|---|
timestamp
|
(deprecated) The time of the most recent activity on the
node. Prefer start_timestamp and finish_timestamp . |
start_timestamp
|
The time the node starting running or |
finish_timestamp
|
The time the node finished running or |
duration
|
The duration of the puppet run in seconds if the node has
finished running, the duration in seconds that has passed after the node started
running if it is currently running, or nil if the node hasn't started running or was skipped |
state
|
The current state of the job. |
transaction_uuid
|
(deprecated) The ID used to identify the nodes last report. |
name
|
The hostname of the node. |
details
|
information about the last event and state of a given node. |
result
|
The result of a successful, failed, errored node-run. The schema of this varies. |
For example:
{
"next-events": {
"id": "https://orchestrator.example.com:8143/orchestrator/v1/jobs/3/events?start=10",
"event": "10"
},
"items" : [ {
"timestamp" : "2015-07-13T20:37:01Z",
"start_timestamp" : "2015-07-13T20:36:13Z",
"finish_timestamp" : "2015-07-13T20:37:01Z",
"duration" : 48.0,
"state" : "state",
"transaction_uuid" : :uuid,
"name" : "wss6c3w9wngpycg.example.com",
"details" : {
"message": "Message of latest event"
},
"result": {
"output_1": "success",
"output_2": [1, 1, 2, 3,]
}
},{
...
} ]
}
Copied!
Results
The result field is available after a node finishes, fails, or errors and contains the contents of the details of the corresponding event. In task jobs this is the result of executing the task. For puppet jobs it contains metrics from the puppet run.
For example:
An error when running a task:
"result" : {
"msg" : "Running tasks is not supported for agents older than version 5.1.0",
"kind" : "puppetlabs.orchestrator/execution-failure",
"details" : {
"node" : "copper-6"
}
}
Copied!
Raw stdout from a task:
"result" : {
"output" : "test\n"
}
Copied!
Structured output from a task:
"result" : {
"status" : "up to date",
"version" : "5.0.0.201.g879fc5a-1.el7"
}
Copied!
Error output from a task:
"result" : {
"error" : "Invalid task name 'package::status'"
}
Copied!
Puppet run results:
"result" : {
"hash" : "d7ec44e176bb4b2e8a816157ebbae23b065b68cc",
"noop" : {
"noop" : false,
"no_noop" : false
},
"status" : "unchanged",
"metrics" : {
"corrective_change" : 0,
"out_of_sync" : 0,
"restarted" : 0,
"skipped" : 0,
"total" : 347,
"changed" : 0,
"scheduled" : 0,
"failed_to_restart" : 0,
"failed" : 0
},
"environment" : "production",
"configuration_version" : "1502024081"
}
Copied!
"result" : {
"noop": false,
"status" : "unchanged",
"metrics" : {
"corrective_change" : 0,
"out_of_sync" : 0,
"restarted" : 0,
"skipped" : 0,
"total" : 347,
"changed" : 0,
"scheduled" : 0,
"failed_to_restart" : 0,
"failed" : 0
}
}
Copied!
Details
The details field contains information based on the last event and current state of the node and can be empty. In some cases it can duplicate data from the results key for historical reasons.
If the node state is finished
or failed
the details hash can include a message and a report-url. (deprecated) for
jobs started with the run command it also duplicates some information from the result.
{
"items" : [ {
"timestamp" : "2015-07-13T20:37:01Z",
"state" : "finished",
"transaction_uuid" : :uuid,
"name" : "wss6c3w9wngpycg.example.com",
"details" : {
"report-url" : "https://peconsole.example.com/#/cm/report/a15bf509dd7c40705e4e1c24d0935e2e8a1591df",
"message": "Finished puppet run on wss6c3w9wngpycg.example.com - Success!"
}
"result" : {
"metrics" : {
"total" : 82,
"failed" : 0,
"changed" : 51,
"skipped" : 0,
"restarted" : 2,
"scheduled" : 0,
"out_of_sync" : 51,
"failed_to_restart" : 0
},
},{
...
} ]
}
Copied!
If the node state is skipped
or errored
, the service
includes a :detail
key that explains why a node is in that state.
{
"items" : [ {
"timestamp" : "2015-07-13T20:37:01Z",
"state" : "failed",
"transaction_uuid" : :uuid,
"name" : "wss6c3w9wngpycg.example.com",
"details" : {
"message": "Error running puppet on wss6c3w9wngpycg.example.com: java.net.Exception: Something went wrong"
}
},{
...
} ]
}
Copied!
If the node state is running
, the service returns the
run-time
(in seconds).
{
"items" : [ {
"timestamp" : "2015-07-13T20:37:01Z",
"state" : "running",
"transaction_uuid" : :uuid,
"name" : "wss6c3w9wngpycg.example.com",
"details" : {
"run-time": 30,
"message": "Started puppet run on wss6c3w9wngpycg.example.com..."
}
},{
...
} ]
}
Copied!
Error responses
For this endpoint, the kind
key of the error displays the conflict.
Key | Definition |
---|---|
puppetlabs.orchestrator/validation-error
|
If the job-id in the request is not an integer,
the server returns a 400 response. |
puppetlabs.orchestrator/unknown-job
|
If the job does not exist, the server returns a
404 response. |
GET /jobs/:job-id/report
Returns a report for a given job.
Response format
The response is a JSON object that reports the status of a job, and uses these keys:
Key | Definition |
---|---|
items
|
An array of all the reports associated with a given job. |
node
|
The hostname of a node. |
state
|
The current state of the job. |
timestamp
|
The time when the job was created. |
events
|
Any events associated with that node during the job. |
For example:
{
"items" : [ {
"node" : "wss6c3w9wngpycg.example.com",
"state" : "running",
"timestamp" : "2015-07-13T20:37:01Z",
"events" : [ ]
}, {
...
} ]
}
Copied!
Error responses
For this endpoint, the kind
key of the error displays the conflict.
Key | Definition |
---|---|
puppetlabs.orchestrator/validation-error
|
If the job-id in the request is not an
integer, the server returns a 400 response. |
hpuppetlabs.orchestrator/unknown-job
|
If the job does not exist, the server returns a
404 response. |