Job

Description

This resource is used for managing jobs and launching job templates via Tower. Note for historical purposes, launching a job template is linked to job, rather than job template.

Fields Table

name type help_text read_only unique filterable required
job_template Resource job_template The job_template field. False False True False
job_explanation String The job_explanation field. True False True False
created String The created field. False False True False
status String The status field. False False True False
elapsed String The elapsed field. False False True False

API Specification

class tower_cli.resources.job.Resource(*args, **kwargs)[source]

A resource for jobs.

This resource has ordinary list and get methods, but it does not have create or modify. Instead of being created, a job is launched.

cancel(pk=None, fail_if_not_running=False, **kwargs)

Cancel a currently running job.

Parameters:
  • pk (int) – Primary key of the job resource to restart.
  • fail_if_not_running (bool) – Flag that if set, raise exception if the job resource cannot be canceled.
  • **kwargs – Keyword arguments used to look up job resource object to restart if pk is not provided.
Returns:

A dictionary of two keys: “status”, which is “canceled”, and “changed”, which indicates if the job resource has been successfully canceled.
Return type:

dict
Raises:

tower_cli.exceptions.TowerCLIError – When the job resource cannot be canceled and fail_if_not_running flag is on.
delete(pk=None, fail_on_missing=False, **kwargs)

Remove the given object.

Parameters:
  • pk (int) – Primary key of the resource to be deleted.
  • fail_on_missing (bool) – Flag that if set, the object’s not being found is considered a failure; otherwise, a success with no change is reported.
  • **kwargs – Keyword arguments used to look up resource object to delete if pk is not provided.
Returns:

dictionary of only one field “changed”, which is a flag indicating whether the specified resource is successfully deleted.
Return type:

dict
get(pk=None, **kwargs)

Retrieve one and exactly one object.

Parameters:
  • pk (int) – Primary key of the resource to be read. Tower CLI will only attempt to read that object if pk is provided (not None).
  • **kwargs – Keyword arguments used to look up resource object to retrieve if pk is not provided.
Returns:

loaded JSON of the retrieved resource object.
Return type:

dict
launch(job_template=None, monitor=False, wait=False, timeout=None, no_input=True, extra_vars=None, **kwargs)[source]

Launch a new job based on a job template.

Parameters:
  • job_template (str) – Primary key or name of the job template to launch new job.
  • monitor (bool) – Flag that if set, immediately calls monitor on the newly launched job rather than exiting with a success.
  • wait (bool) – Flag that if set, monitor the status of the job, but do not print while job is in progress.
  • timeout (int) – If provided with monitor flag set, this attempt will time out after the given number of seconds.
  • no_input (bool) – Flag that if set, suppress any requests for input.
  • extra_vars (array of strings) – yaml formatted texts that contains extra variables to pass on.
  • diff_mode (bool) – Specify diff mode for job template to run.
  • limit (str) – Specify host limit for job template to run.
  • tags (str) – Specify tagged actions in the playbook to run.
  • skip_tags (str) – Specify tagged actions in the playbook to omit.
  • job_type (str) – Specify job type for job template to run.
  • verbosity (int) – Specify verbosity of the playbook run.
  • inventory (str) – Specify machine credential for job template to run.
  • credential (str) – Specify machine credential for job template to run.
Returns:

Result of subsequent monitor call if monitor flag is on; Result of subsequent wait call if wait flag is on; Result of subsequent status call if none of the two flags are on.
Return type:

dict
list(all_pages=False, **kwargs)

Retrieve a list of objects.

Parameters:
  • all_pages (bool) – Flag that if set, collect all pages of content from the API when returning results.
  • page (int) – The page to show. Ignored if all_pages is set.
  • query (list) – Contains 2-tuples used as query parameters to filter resulting resource objects.
  • **kwargs – Keyword arguments list of available fields used for searching resource objects.
Returns:

A JSON object containing details of all resource objects returned by Tower backend.
Return type:

dict
monitor(pk, parent_pk=None, timeout=None, interval=0.5, outfile=<open file '<stdout>', mode 'w'>, **kwargs)

Stream the standard output from a job run to stdout.

Parameters:
  • pk (int) – Primary key of the job resource object to be monitored.
  • parent_pk (int) – Primary key of the unified job template resource object whose latest job run will be monitored if pk is not set.
  • timeout (float) – Number in seconds after which this method will time out.
  • interval (float) – Polling interval to refresh content from Tower.
  • outfile (file) – Alternative file than stdout to write job stdout to.
  • **kwargs – Keyword arguments used to look up job resource object to monitor if pk is not provided.
Returns:

A dictionary combining the JSON output of the finished job resource object, as well as two extra fields: “changed”, a flag indicating if the job resource object is finished as expected; “id”, an integer which is the primary key of the job resource object being monitored.
Return type:

dict
Raises:
relaunch(pk=None, **kwargs)

Relaunch a stopped job resource.

Parameters:
  • pk (int) – Primary key of the job resource to relaunch.
  • **kwargs – Keyword arguments used to look up job resource object to relaunch if pk is not provided.
Returns:

A dictionary combining the JSON output of the relaunched job resource object, as well as an extra field “changed”, a flag indicating if the job resource object is status-changed as expected.
Return type:

dict
status(pk=None, detail=False, **kwargs)

Retrieve the current job status.

Parameters:
  • pk (int) – Primary key of the resource to retrieve status from.
  • detail (bool) – Flag that if set, return the full JSON of the job resource rather than a status summary.
  • **kwargs – Keyword arguments used to look up resource object to retrieve status from if pk is not provided.
Returns:

full loaded JSON of the specified unified job if detail flag is on; trimed JSON containing only “elapsed”, “failed” and “status” fields of the unified job if detail flag is off.
Return type:

dict
stdout(pk, start_line=None, end_line=None, outfile=<open file '<stdout>', mode 'w'>, **kwargs)

Print out the standard out of a unified job to the command line or output file. For Projects, print the standard out of most recent update. For Inventory Sources, print standard out of most recent sync. For Jobs, print the job’s standard out. For Workflow Jobs, print a status table of its jobs.

Parameters:
  • pk (int) – Primary key of the job resource object to be monitored.
  • start_line – Line at which to start printing job output
  • end_line – Line at which to end printing job output
  • outfile (file) – Alternative file than stdout to write job stdout to.
  • **kwargs – Keyword arguments used to look up job resource object to monitor if pk is not provided.
Returns:

A dictionary containing changed=False
Return type:

dict
wait(pk, parent_pk=None, min_interval=1, max_interval=30, timeout=None, outfile=<open file '<stdout>', mode 'w'>, exit_on=['successful'], **kwargs)

Wait for a job resource object to enter certain status.

Parameters:
  • pk (int) – Primary key of the job resource object to wait.
  • parent_pk (int) – Primary key of the unified job template resource object whose latest job run will be waited if pk is not set.
  • timeout (float) – Number in seconds after which this method will time out.
  • min_interval (float) – Minimum polling interval to request an update from Tower.
  • max_interval (float) – Maximum polling interval to request an update from Tower.
  • outfile (file) – Alternative file than stdout to write job status updates on.
  • exit_on (array) – Job resource object statuses to wait on.
  • **kwargs – Keyword arguments used to look up job resource object to wait if pk is not provided.
Returns:

A dictionary combining the JSON output of the status-changed job resource object, as well as two extra fields: “changed”, a flag indicating if the job resource object is status-changed as expected; “id”, an integer which is the primary key of the job resource object being status-changed.
Return type:

dict
Raises: