Ad Hoc Commands

Description

This resource is used for managing and executing ad hoc commands via Tower. While the rest CRUD operations follow the common usage pattern, an ad hoc command resource cannot be created via the normal way of calling create, but only be created on-the-fly via launch.

Fields Table

name type help_text read_only unique filterable required
job_explanation String The job_explanation field. False 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
job_type Choices: run,check The job_type field. False False True True
inventory Resource inventory The inventory field. False False True True
limit String The limit field. False False True False
credential Resource credential The credential field. False False True True
module_name String The module_name field. False False True False
module_args String The module_args field. False False True False
forks int The forks field. False False True False
verbosity mapped_choice The verbosity field. False False True False
become_enabled bool The become_enabled field. False False True False
diff_mode bool The diff_mode field. False False True False

API Specification

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

A resource for ad hoc commands.

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(monitor=False, wait=False, timeout=None, **kwargs)[source]

Launch a new ad-hoc command.

Parameters:
  • monitor (bool) – Flag that if set, immediately calls monitor on the newly launched command 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.
  • **kwargs – Fields needed to create and launch an ad hoc command.
Returns:

Result of subsequent monitor call if monitor flag is on; Result of subsequent wait call if wait flag is on; dictionary of “id” and “changed” if none of the two flags are on.
Return type:

dict
Raises:

tower_cli.exceptions.TowerCLIError – When ad hoc commands are not available in Tower backend.
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
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: