Provided by: ansible-tower-cli_3.2.0-2_all 
NAME
tower_cli - tower_cli Documentation
tower-cli is a command line tool for Ansible Tower. It allows Tower commands to be easily run from the
Unix command line. It can also be used as a client library for other python apps, or as a reference for
others developing API interactions with Tower’s REST API.
ABOUT TOWER
Ansible Tower is a GUI and REST interface for Ansible that supercharges it by adding RBAC, centralized
logging, autoscaling/provisioning callbacks, graphical inventory editing, and more.
Tower is free to use for up to 30 days or 10 nodes. Beyond this, a license is required.
CAPABILITIES
This command line tool sends commands to the Tower API. It is capable of retrieving, creating, modifying,
and deleting most resources within Tower.
A few potential uses include:
• Launching playbook runs (for instance, from Jenkins, TeamCity, Bamboo, etc)
• Checking on job statuses
• Rapidly creating objects like organizations, users, teams, and more
TABLE OF CONTENTS
Installation
Install from Package Managers
Tower CLI is available as a package on PyPI.
The preferred way to install is through pip:
$ pip install ansible-tower-cli
Build from Source
ansible-tower-cli may also be consumed and built directly from source.
$ git clone https://github.com/ansible/tower-cli.git
Then, inside tower_cli directory, run
$ make install
and follow the instructions.
If you are not familar with ansible-tower-cli’s dependency tree, we suggested building source in a fresh
virtual environment to prevent any dependency conflict.
Install the Right Version
REST API of Ansible Tower is versioned, and each API version is supported by a subset, rather than all,
of ansible-tower-cli versions. Make sure you are pairing your Tower backend with a right version of
ansible-tower-cli, specifically:
• If you are using Tower 3.2.0 and beyond, API v2 is available, you should use ansible-tower-cli 3.2.0
and beyond.
• If you are using a Tower version lower than 3.2.0, only API v1 is available, you should use
ansible-tower-cli versions lower than 3.2.0.
Quick Start
This chapter walks you through the general process of setting up and using Tower CLI. It starts with CLI
usage and ends with API usage. For details, please see API and CLI references in subsequent chapters.
It is assumed you have a Tower backend available to talk to and Tower CLI installed. Please see
‘Installation’ chapter for instructions on installing Tower CLI.
First of all, make sure you know the name of the Tower backend, like tower.example.com, as well as the
username/password set of a user in that Tower backend, like user/pass. These are connection information
necessary for Tower CLI to communicate to Tower. With these prerequisites, run
$ tower-cli config host tower.example.com
$ tower-cli config username user
$ tower-cli config password pass
The first Tower CLI command, tower-cli config. writes the connection informations to a configuration file
(~/.tower-cli.cfg in this case), and subsequent commands and API calls will read this file, extract
connection information and talk to Tower as the specified user. See details of Tower CLI configuration in
API reference and tower-cli config --help.
Then, use Tower CLI to actually control your Tower backend. The CRUD operations against almost every
Tower resource can be done using Tower CLI. Suppose we want to see the available job templates to choose
for running:
$ tower-cli job_template list
A command-line-formatted table would show up, giving general summary of (maybe part of) the available job
templates. Note the actual HTTP(S) response is in JSON format, you can choose to see the JSON response
itself instead using --format flag.
$ tower-cli job_template list --format json
Other than normal resource CRUD operations, Tower CLI can be used to launch and monitor executable
resources like job templates and projects. Suppose we have had the ID of the job template we want to
execute from the previous list call, we can launch the job template by:
$ tower-cli job launch -J <ID of the job template> --monitor
This command will POST to Tower backend to launch the job template to be executed, and monitor the
triggered job run by dumping job stdout in real-time, just as what Tower UI does.
The best CLI help you can get is from --help option. Each Tower CLI command is guaranteed to have a
--help option instructing the command hierarchy and detailed usage like command format the meaning of
each available command option. Use --help whenever you have questions about a Tower CLI command.
Under the hood, Tower CLI is composed of an API engine and a wrapper layer around it to make it a CLI.
Using API of Tower CLI gives you finer-grained control and makes it easy to integrate Tower CLI into your
python scripts.
The usage of Tower CLI’s API is two-phased: get resource and call its API. First you get the type of
resource you want to interact with.
import tower_cli
res = tower_cli.get_resource('job_template')
Due to legacy reasons, we use a non-traditional way of importing resource class, tower_cli.get_resource.
Alternatively, you can use the old way by using import alias:
import tower_cli.resources.job_template import Resource as JobTemplate
res = JobTemplate()
Then, interaction with Tower would be as easy as straight-forward resource public method calls, like
jt_list = res.list()
tower_cli.get_resource('job').launch(job_template=1, monitor=True)
More API usage can be found in API reference.
API Reference
NOTE: This API documentation assumes you are using 3.2.0 and higher versions of ansible-tower-cli. If you
are using a lower version than 3.2.0, there is no guarantee API usages in this documentation would work
as expected.
Introduction
Like Tower UI, Tower CLI is a client talking to multiple REST services of Tower backend, but via Python
script or UNIX command line. Thus the usage of Tower CLI’s APIs are pretty straight-forward: get a
resource corresponding to its counterpart in Tower backend, and call public methods of that resource,
which in term requests specific REST endpoint and fetch/render response JSON. Here is a simple example of
creating a new organization using Tower CLI in Python:
from tower_cli import get_resource
from tower_cli.exceptions import Found
from tower_cli.conf import settings
with settings.runtime_values(username='user', password='pass'):
try:
res = get_resource('organization')
new_org = res.create(name='foo', description='bar', fail_on_found=True)
except Found:
print('This organization already exists.')
assert isinstance(new_org, dict)
print(new_org['id'])
The above example shows the pattern for most Tower CLI API use cases, which is composed of 3 parts:
runtime configuration, fetch resource and invoke its public methods, and exception handling.
Tower CLI needs a set of configurations to function properly, all configuration settings are stored in
singleton object tower_cli.conf.settings, which provides a public context manager runtime_values to
temporary override settings on file with temporary runtime values. see more about Tower CLI
configurations in ‘Configuration’ section.
Most of the resources listed at Tower’s endpoint /api/v2/ have client-side proxy classes in Tower CLI.
The two main ways of getting resource proxies in Tower CLI are:
from tower_cli import get_resource
res = get_resource('<resource name>')
and
import tower_cli.resources.<resource module name>.Resource as <alias>
res = <alias>()
A typical resource in Tower CLI has 2 components: fields and public methods. Resource fields can be seen
as wrappers around actual resource fields exposed by Tower REST API. They are generally used by public
methods to create and modify resources and filter when searching for specific resources; Public methods
are the actual wrappers around querying Tower REST APIs, they can be used both for general CRUD
operations against Tower resources, like delete a user, and for specific tasks like launching an ad hoc
command, monitoring a job run or constructing a workflow graph from script.
In the table of contents below, all available Tower CLI resources are listed, the documentation for each
of them all follow the same structure: a ‘Description’ section which gives an introduction to the
resource; a ‘Fields Table’ section which lists all available fields of that resource; and a ‘API
Specification’ section, which expands the usage detail of every available public method.
Note most public methods have a keyword argument **kwargs. This argument basically contains and only
contains resource fields, unless specified.
Any usage errors or connection exceptions are thrown as subclasses of tower_cli.exceptions.TowerCLIError,
see ‘Exceptions’ section below for details.
Table of Contents
Configuration
In Tower CLI, there are a number of configuration settings available to users. These settings are mostly
used to set up connection details to Tower backend, like hostname of Tower backend and user name/password
used for authentication; some are also used for other purposes, like toggle on/off colored stdout. Here
is a list of all available Tower CLI settings:
┌───────────────┬──────────────────────────────┬──────────────────────────────┐
│Key │ Value Type / Value Default │ Description │
├───────────────┼──────────────────────────────┼──────────────────────────────┤
│color │ Boolean/’true’ │ Whether to use colored │
│ │ │ output for highlighting or │
│ │ │ not. │
├───────────────┼──────────────────────────────┼──────────────────────────────┤
│format │ String with options │ Output format. The “human” │
│ │ (‘human’, ‘json’, │ format is intended for │
│ │ ‘yaml’)/’human’ │ humans reading output on the │
│ │ │ CLI; the “json” and “yaml” │
│ │ │ formats provide more data. │
│ │ │ [CLI use only] │
├───────────────┼──────────────────────────────┼──────────────────────────────┤
│host │ String/‘127.0.0.1’ │ The location of the Ansible │
│ │ │ Tower host. HTTPS is assumed │
│ │ │ as the protocol unless “‐ │
│ │ │ http://” is explicitly │
│ │ │ provided. │
├───────────────┼──────────────────────────────┼──────────────────────────────┤
│password │ String/’‘ │ Password to use to │
│ │ │ authenticate to Ansible │
│ │ │ Tower. │
├───────────────┼──────────────────────────────┼──────────────────────────────┤
│username │ String/’‘ │ Username to use to │
│ │ │ authenticate to Ansible │
│ │ │ Tower. │
├───────────────┼──────────────────────────────┼──────────────────────────────┤
│verify_ssl │ Boolean/’true’ │ Whether to force verified │
│ │ │ SSL connections. │
├───────────────┼──────────────────────────────┼──────────────────────────────┤
│verbose │ Boolean/’false’ │ Whether to show information │
│ │ │ about requests being made. │
├───────────────┼──────────────────────────────┼──────────────────────────────┤
│description_on │ Boolean/’false’ │ Whether to show description │
│ │ │ in human-formatted output. │
│ │ │ [CLI use only] │
├───────────────┼──────────────────────────────┼──────────────────────────────┤
│certificate │ String/’‘ │ Path to a custom certificate │
│ │ │ file that will be used │
│ │ │ throughout the command. │
│ │ │ Ignored if –insecure flag if │
│ │ │ set in command or verify_ssl │
│ │ │ is set to false │
├───────────────┼──────────────────────────────┼──────────────────────────────┤
│use_token │ Boolean/’false’ │ Whether to use token-based │
│ │ │ authentication. │
└───────────────┴──────────────────────────────┴──────────────────────────────┘
Note: Some settings are marked as ‘CLI use only’, this means although users are free to set values to
those settings, those settings only affect CLI but not API usage.
class tower_cli.conf.Settings
A class that understands configurations provided to tower-cli through configuration files or
runtime parameters. A signleton object tower_cli.conf.settings will be instantiated and used.
The 5 levels of precedence for settings, listing from least to greatest, are:
• defaults: Default values provided
• global: Contents parsed from .ini-formatted file /etc/tower/tower_cli.cfg if exists.
• user: Contents parsed from .ini-formatted file ~/.tower_cli.cfg if exists.
• local: Contents parsed from .ini-formatted file .tower_cli.cfg if exists in the present
working directory or any parent directories.
• runtime: keyworded arguements provided by settings.runtime_values context manager.
Note that .ini configuration file should follow the specified format in order to be correctly
parsed:
[general]
<configuration name 1> = <value 1>
<configuration name 2> = <value 2>
...
runtime_values(**kwargs)
Context manager that temporarily override runtime level configurations.
Parameters
kwargs (arbitrary keyword arguments) – Keyword arguments specifying runtime
configuration settings.
Returns
N/A
Example
>>> import tower_cli
>>> from tower_cli.conf import settings
>>> with settings.runtime_values(username='user', password='pass'):
>>> print(tower_cli.get_resource('credential').list())
Exceptions
APIs of tower_cli raise exceptions defined in tower_cli.exceptions module. Check raise list of resource
public method documentation for possible exceptions.
exception tower_cli.exceptions.AuthError(message)
An exception class for reporting when a request failed due to an authorization failure.
exception tower_cli.exceptions.BadRequest(message)
An exception class for reporting unexpected error codes from Ansible Tower such that 400 <= code <
500.
In theory, we should never, ever get these.
exception tower_cli.exceptions.CannotStartJob(message)
An exception class for jobs that cannot be started within Tower for whatever reason.
exception tower_cli.exceptions.ConnectionError(message)
An exception class to bubble requests errors more nicely, and communicate connection issues to the
user.
exception tower_cli.exceptions.Forbidden(message)
An exception class for reporting when a user doesn’t have permission to do something.
exception tower_cli.exceptions.Found(message)
An exception class for when a record already exists, and we were explicitly told that it
shouldn’t.
exception tower_cli.exceptions.JobFailure(message)
An exception class for job failures that require error codes within the Tower CLI.
exception tower_cli.exceptions.MethodNotAllowed(message)
An exception class for sending a request to a URL where the URL doesn’t accept that method at all.
exception tower_cli.exceptions.MultipleRelatedError(message)
An exception class for errors where we try to find a single related object, and get more than one.
exception tower_cli.exceptions.MultipleResults(message)
An exception class for reporting when a request that expected one and exactly one result got more
than that.
exception tower_cli.exceptions.NotFound(message)
An exception class for reporting when a request went through without incident, but the requested
content could not be found.
exception tower_cli.exceptions.RelatedError(message)
An exception class for errors where we can’t find related objects that we expect to find.
exception tower_cli.exceptions.ServerError(message)
An exception class for reporting server-side errors which are expected to be ephemeral.
exception tower_cli.exceptions.Timeout(message)
An exception class for timeouts encountered within Tower CLI, usually for monitoring.
exception tower_cli.exceptions.TowerCLIError(message)
Base exception class for problems raised within Tower CLI. This class adds coloring to
exceptions.
exception tower_cli.exceptions.UsageError(message)
An exception class for reporting usage errors.
This uses an exit code of 2 in order to match click (which matters more than following the
erstwhile “standard” of using 64).
exception tower_cli.exceptions.ValidationError(message)
An exception class for invalid values being sent as option switches to Tower CLI.
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 │ False │ False │ True │ False │
│ │ │ job_explanation │ │ │ │ │
│ │ │ field. │ │ │ │ │
├────────────────┼───────────────┼─────────────────┼───────────┼────────┼────────────┼──────────┤
│created │ String │ The created │ False │ False │ True │ False │
│ │ │ field. │ │ │ │ │
├────────────────┼───────────────┼─────────────────┼───────────┼────────┼────────────┼──────────┤
│status │ String │ The status │ False │ False │ True │ False │
│ │ │ field. │ │ │ │ │
├────────────────┼───────────────┼─────────────────┼───────────┼────────┼────────────┼──────────┤
│elapsed │ String │ The elapsed │ False │ False │ True │ False │
│ │ │ field. │ │ │ │ │
├────────────────┼───────────────┼─────────────────┼───────────┼────────┼────────────┼──────────┤
│job_type │ Choices: │ The job_type │ False │ False │ True │ True │
│ │ run,check │ field. │ │ │ │ │
├────────────────┼───────────────┼─────────────────┼───────────┼────────┼────────────┼──────────┤
│inventory │ Resource │ The inventory │ False │ False │ True │ True │
│ │ inventory │ field. │ │ │ │ │
├────────────────┼───────────────┼─────────────────┼───────────┼────────┼────────────┼──────────┤
│limit │ String │ The limit │ False │ False │ True │ False │
│ │ │ field. │ │ │ │ │
├────────────────┼───────────────┼─────────────────┼───────────┼────────┼────────────┼──────────┤
│credential │ Resource │ The credential │ False │ False │ True │ True │
│ │ credential │ field. │ │ │ │ │
├────────────────┼───────────────┼─────────────────┼───────────┼────────┼────────────┼──────────┤
│module_name │ String │ The module_name │ False │ False │ True │ False │
│ │ │ field. │ │ │ │ │
├────────────────┼───────────────┼─────────────────┼───────────┼────────┼────────────┼──────────┤
│module_args │ String │ The module_args │ False │ False │ True │ False │
│ │ │ field. │ │ │ │ │
├────────────────┼───────────────┼─────────────────┼───────────┼────────┼────────────┼──────────┤
│forks │ int │ The forks │ False │ False │ True │ False │
│ │ │ field. │ │ │ │ │
├────────────────┼───────────────┼─────────────────┼───────────┼────────┼────────────┼──────────┤
│verbosity │ mapped_choice │ The verbosity │ False │ False │ True │ False │
│ │ │ field. │ │ │ │ │
└────────────────┴───────────────┴─────────────────┴───────────┴────────┴────────────┴──────────┘
│become_enabled │ bool │ The │ False │ False │ True │ False │
│ │ │ become_enabled │ │ │ │ │
│ │ │ field. │ │ │ │ │
├────────────────┼───────────────┼─────────────────┼───────────┼────────┼────────────┼──────────┤
│diff_mode │ bool │ The diff_mode │ False │ False │ True │ False │
│ │ │ field. │ │ │ │ │
└────────────────┴───────────────┴─────────────────┴───────────┴────────┴────────────┴──────────┘
API Specification
class tower_cli.resources.ad_hoc.Resource(*args, **kwargs)
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)
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=<_io.TextIOWrapper name='<stdout>'
mode='w' encoding='UTF-8'>, **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 wiil 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
• tower_cli.exceptions.Timeout – When monitor time reaches time out.
• tower_cli.exceptions.JobFailure – When the job being monitored runs into failure.
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=<_io.TextIOWrapper
name='<stdout>' mode='w' encoding='UTF-8'>, 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
• tower_cli.exceptions.Timeout – When wait time reaches time out.
• tower_cli.exceptions.JobFailure – When the job being waited on runs into failure.
Credential Type
Description
This resource is used for managing credential type resources in Tower.
Fields Table
┌─────────────────┬──────────────────────────────────┬────────────────┬───────────┬────────┬────────────┬──────────┐
│name │ type │ help_text │ read_only │ unique │ filterable │ required │
├─────────────────┼──────────────────────────────────┼────────────────┼───────────┼────────┼────────────┼──────────┤
│name │ String │ The name │ False │ True │ True │ True │
│ │ │ field. │ │ │ │ │
├─────────────────┼──────────────────────────────────┼────────────────┼───────────┼────────┼────────────┼──────────┤
│description │ String │ The │ False │ False │ True │ False │
│ │ │ description │ │ │ │ │
│ │ │ field. │ │ │ │ │
├─────────────────┼──────────────────────────────────┼────────────────┼───────────┼────────┼────────────┼──────────┤
│kind │ Choices: │ The type of │ False │ False │ True │ True │
│ │ ssh,vault,net,scm,cloud,insights │ credential │ │ │ │ │
│ │ │ type being │ │ │ │ │
│ │ │ added. Valid │ │ │ │ │
│ │ │ options are: │ │ │ │ │
│ │ │ ssh, vault, │ │ │ │ │
│ │ │ net, scm, │ │ │ │ │
│ │ │ cloud and │ │ │ │ │
│ │ │ insights. Note │ │ │ │ │
│ │ │ only cloud and │ │ │ │ │
│ │ │ net can be │ │ │ │ │
│ │ │ used for │ │ │ │ │
│ │ │ creating │ │ │ │ │
│ │ │ credential │ │ │ │ │
│ │ │ types. │ │ │ │ │
├─────────────────┼──────────────────────────────────┼────────────────┼───────────┼────────┼────────────┼──────────┤
│managed_by_tower │ bool │ Indicating if │ True │ False │ True │ False │
│ │ │ the credential │ │ │ │ │
│ │ │ type is a │ │ │ │ │
│ │ │ tower built-in │ │ │ │ │
│ │ │ type. │ │ │ │ │
├─────────────────┼──────────────────────────────────┼────────────────┼───────────┼────────┼────────────┼──────────┤
│inputs │ structured_input │ The inputs │ False │ False │ True │ False │
│ │ │ field. │ │ │ │ │
├─────────────────┼──────────────────────────────────┼────────────────┼───────────┼────────┼────────────┼──────────┤
│injectors │ structured_input │ The injectors │ False │ False │ True │ False │
│ │ │ field. │ │ │ │ │
└─────────────────┴──────────────────────────────────┴────────────────┴───────────┴────────┴────────────┴──────────┘
API Specification
class tower_cli.resources.credential_type.Resource
A resource for credential types.
copy(pk=None, **kwargs)
Copy an object.
Parameters
• pk (int) – Primary key of the resource object to be copied
• **kwargs – Keyword arguments of fields whose given value will override the
original value.
Returns
loaded JSON of the copied new resource object.
Return type
dict
create(**kwargs)
Create an object.
Parameters
• fail_on_found (bool) – Flag that if set, the operation fails if an object matching
the unique criteria already exists.
• force_on_exists (bool) – Flag that if set, then if a match is found on unique
fields, other fields will be updated to the provided values.; If unset, a match
causes the request to be a no-op.
• **kwargs – Keyword arguements which, all together, will be used as POST body to
create the resource object.
Returns
A dictionary combining the JSON output of the created resource, as well as two extra
fields: “changed”, a flag indicating if the resource is created successfully; “id”,
an integer which is the primary key of the created object.
Return type
dict
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
modify(pk=None, create_on_missing=False, **kwargs)
Modify an already existing object.
Parameters
• pk (int) – Primary key of the resource to be modified.
• create_on_missing (bool) – Flag that if set, a new object is created if pk is not
set and objects matching the appropriate unique criteria is not found.
• **kwargs – Keyword arguements which, all together, will be used as PATCH body to
modify the resource object. if pk is not set, key-value pairs of **kwargs which
are also in resource’s identity will be used to lookup existing reosource.
Returns
A dictionary combining the JSON output of the modified resource, as well as two
extra fields: “changed”, a flag indicating if the resource is successfully updated;
“id”, an integer which is the primary key of the updated object.
Return type
dict
Credential
Description
This resource is used for managing credential resources in Tower.
Fields Table
┌────────────────┬──────────────────┬─────────────────┬───────────┬────────┬────────────┬──────────┐
│name │ type │ help_text │ read_only │ unique │ filterable │ required │
├────────────────┼──────────────────┼─────────────────┼───────────┼────────┼────────────┼──────────┤
│name │ String │ The name │ False │ True │ True │ True │
│ │ │ field. │ │ │ │ │
├────────────────┼──────────────────┼─────────────────┼───────────┼────────┼────────────┼──────────┤
│description │ String │ The │ False │ False │ True │ False │
│ │ │ description │ │ │ │ │
│ │ │ field. │ │ │ │ │
├────────────────┼──────────────────┼─────────────────┼───────────┼────────┼────────────┼──────────┤
│user │ Resource user │ The user │ False │ False │ True │ False │
│ │ │ field. │ │ │ │ │
├────────────────┼──────────────────┼─────────────────┼───────────┼────────┼────────────┼──────────┤
│team │ Resource team │ The team │ False │ False │ True │ False │
│ │ │ field. │ │ │ │ │
├────────────────┼──────────────────┼─────────────────┼───────────┼────────┼────────────┼──────────┤
│organization │ Resource │ The │ False │ False │ True │ False │
│ │ organization │ organization │ │ │ │ │
│ │ │ field. │ │ │ │ │
├────────────────┼──────────────────┼─────────────────┼───────────┼────────┼────────────┼──────────┤
│credential_type │ Resource │ The │ False │ False │ True │ True │
│ │ credential_type │ credential_type │ │ │ │ │
│ │ │ field. │ │ │ │ │
├────────────────┼──────────────────┼─────────────────┼───────────┼────────┼────────────┼──────────┤
│inputs │ structured_input │ The inputs │ False │ False │ True │ False │
│ │ │ field. │ │ │ │ │
└────────────────┴──────────────────┴─────────────────┴───────────┴────────┴────────────┴──────────┘
API Specification
class tower_cli.resources.credential.Resource
A resource for credentials.
copy(pk=None, **kwargs)
Copy an object.
Parameters
• pk (int) – Primary key of the resource object to be copied
• **kwargs – Keyword arguments of fields whose given value will override the
original value.
Returns
loaded JSON of the copied new resource object.
Return type
dict
create(**kwargs)
Create an object.
Parameters
• fail_on_found (bool) – Flag that if set, the operation fails if an object matching
the unique criteria already exists.
• force_on_exists (bool) – Flag that if set, then if a match is found on unique
fields, other fields will be updated to the provided values.; If unset, a match
causes the request to be a no-op.
• **kwargs – Keyword arguements which, all together, will be used as POST body to
create the resource object.
Returns
A dictionary combining the JSON output of the created resource, as well as two extra
fields: “changed”, a flag indicating if the resource is created successfully; “id”,
an integer which is the primary key of the created object.
Return type
dict
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
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
modify(pk=None, create_on_missing=False, **kwargs)
Modify an already existing object.
Parameters
• pk (int) – Primary key of the resource to be modified.
• create_on_missing (bool) – Flag that if set, a new object is created if pk is not
set and objects matching the appropriate unique criteria is not found.
• **kwargs – Keyword arguements which, all together, will be used as PATCH body to
modify the resource object. if pk is not set, key-value pairs of **kwargs which
are also in resource’s identity will be used to lookup existing reosource.
Returns
A dictionary combining the JSON output of the modified resource, as well as two
extra fields: “changed”, a flag indicating if the resource is successfully updated;
“id”, an integer which is the primary key of the updated object.
Return type
dict
Group
Description
This resource is used for managing group resources in Tower. It can also associate/disassociate one group
to/from another group.
Fields Table
┌────────────┬───────────┬────────────────┬───────────┬────────┬────────────┬──────────┐
│name │ type │ help_text │ read_only │ unique │ filterable │ required │
├────────────┼───────────┼────────────────┼───────────┼────────┼────────────┼──────────┤
│name │ String │ The name │ False │ True │ True │ True │
│ │ │ field. │ │ │ │ │
├────────────┼───────────┼────────────────┼───────────┼────────┼────────────┼──────────┤
│description │ String │ The │ False │ False │ True │ False │
│ │ │ description │ │ │ │ │
│ │ │ field. │ │ │ │ │
├────────────┼───────────┼────────────────┼───────────┼────────┼────────────┼──────────┤
│inventory │ Resource │ The inventory │ False │ False │ True │ True │
│ │ inventory │ field. │ │ │ │ │
├────────────┼───────────┼────────────────┼───────────┼────────┼────────────┼──────────┤
│variables │ variables │ Group │ False │ False │ True │ False │
│ │ │ variables, use │ │ │ │ │
│ │ │ “@” to get │ │ │ │ │
│ │ │ from file. │ │ │ │ │
└────────────┴───────────┴────────────────┴───────────┴────────┴────────────┴──────────┘
API Specification
class tower_cli.resources.group.Resource
A resource for groups.
associate(group, parent, **kwargs)
Associate this group with the specified group.
Parameters
• group (str) – Primary key or name of the child group to associate.
• parent (str) – Primary key or name of the parent group to associate to.
• inventory (str) – Primary key or name of the inventory the association should
happen in.
Returns
Dictionary of only one key “changed”, which indicates whether the association
succeeded.
Return type
dict
copy(pk=None, **kwargs)
Copy an object.
Parameters
• pk (int) – Primary key of the resource object to be copied
• **kwargs – Keyword arguments of fields whose given value will override the
original value.
Returns
loaded JSON of the copied new resource object.
Return type
dict
create(fail_on_found=False, force_on_exists=False, **kwargs)
Create a group.
Parameters
• parent (str) – Primary key or name of the group which will be the parent of
created group.
• fail_on_found (bool) – Flag that if set, the operation fails if an object matching
the unique criteria already exists.
• force_on_exists (bool) – Flag that if set, then if a match is found on unique
fields, other fields will be updated to the provided values.; If unset, a match
causes the request to be a no-op.
• **kwargs – Keyword arguements which, all together, will be used as POST body to
create the resource object.
Returns
A dictionary combining the JSON output of the created resource, as well as two extra
fields: “changed”, a flag indicating if the resource is created successfully; “id”,
an integer which is the primary key of the created object.
Return type
dict
Raises tower_cli.exceptions.UsageError – When inventory is not provided in **kwargs and
parent is not provided.
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
disassociate(group, parent, **kwargs)
Disassociate this group with the specified group.
Parameters
• group (str) – Primary key or name of the child group to disassociate.
• parent (str) – Primary key or name of the parent group to disassociate from.
• inventory (str) – Primary key or name of the inventory the disassociation should
happen in.
Returns
Dictionary of only one key “changed”, which indicates whether the disassociation
succeeded.
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
list(root=False, **kwargs)
Retrieve a list of groups.
Parameters
• root (bool) – Flag that if set, only root groups of a specific inventory will be
listed.
• parent (str) – Primary key or name of the group whose child groups will be listed.
• 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
Raises tower_cli.exceptions.UsageError – When root flag is on and inventory is not present
in **kwargs.
modify(pk=None, create_on_missing=False, **kwargs)
Modify an already existing object.
Parameters
• pk (int) – Primary key of the resource to be modified.
• create_on_missing (bool) – Flag that if set, a new object is created if pk is not
set and objects matching the appropriate unique criteria is not found.
• **kwargs – Keyword arguements which, all together, will be used as PATCH body to
modify the resource object. if pk is not set, key-value pairs of **kwargs which
are also in resource’s identity will be used to lookup existing reosource.
Returns
A dictionary combining the JSON output of the modified resource, as well as two
extra fields: “changed”, a flag indicating if the resource is successfully updated;
“id”, an integer which is the primary key of the updated object.
Return type
dict
Host
Description
This resource is used for managing host resources in Tower. It can also associate/disassociate a group
to/from a host.
Fields Table
┌───────────────────┬───────────┬────────────────────┬───────────┬────────┬────────────┬──────────┐
│name │ type │ help_text │ read_only │ unique │ filterable │ required │
└───────────────────┴───────────┴────────────────────┴───────────┴────────┴────────────┴──────────┘
│name │ String │ The name │ False │ True │ True │ True │
│ │ │ field. │ │ │ │ │
├───────────────────┼───────────┼────────────────────┼───────────┼────────┼────────────┼──────────┤
│description │ String │ The │ False │ False │ True │ False │
│ │ │ description │ │ │ │ │
│ │ │ field. │ │ │ │ │
├───────────────────┼───────────┼────────────────────┼───────────┼────────┼────────────┼──────────┤
│inventory │ Resource │ The inventory │ False │ False │ True │ True │
│ │ inventory │ field. │ │ │ │ │
├───────────────────┼───────────┼────────────────────┼───────────┼────────┼────────────┼──────────┤
│enabled │ bool │ The enabled │ False │ False │ True │ False │
│ │ │ field. │ │ │ │ │
├───────────────────┼───────────┼────────────────────┼───────────┼────────┼────────────┼──────────┤
│variables │ variables │ Host │ False │ False │ True │ False │
│ │ │ variables, use │ │ │ │ │
│ │ │ “@” to get │ │ │ │ │
│ │ │ from file. │ │ │ │ │
├───────────────────┼───────────┼────────────────────┼───────────┼────────┼────────────┼──────────┤
│insights_system_id │ String │ The │ False │ False │ True │ False │
│ │ │ insights_system_id │ │ │ │ │
│ │ │ field. │ │ │ │ │
└───────────────────┴───────────┴────────────────────┴───────────┴────────┴────────────┴──────────┘
API Specification
class tower_cli.resources.host.Resource
A resource for credentials.
associate(host, group)
Associate a group with this host.
Parameters
• host (str) – Primary key or name of the host to be associated.
• group (str) – Primary key or name of the group to associate.
Returns
Dictionary of only one key “changed”, which indicates whether the association
succeeded.
Return type
dict
copy(pk=None, **kwargs)
Copy an object.
Parameters
• pk (int) – Primary key of the resource object to be copied
• **kwargs – Keyword arguments of fields whose given value will override the
original value.
Returns
loaded JSON of the copied new resource object.
Return type
dict
create(**kwargs)
Create an object.
Parameters
• fail_on_found (bool) – Flag that if set, the operation fails if an object matching
the unique criteria already exists.
• force_on_exists (bool) – Flag that if set, then if a match is found on unique
fields, other fields will be updated to the provided values.; If unset, a match
causes the request to be a no-op.
• **kwargs – Keyword arguements which, all together, will be used as POST body to
create the resource object.
Returns
A dictionary combining the JSON output of the created resource, as well as two extra
fields: “changed”, a flag indicating if the resource is created successfully; “id”,
an integer which is the primary key of the created object.
Return type
dict
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
disassociate(host, group)
Disassociate a group from this host.
Parameters
• host (str) – Primary key or name of the host to be disassociated.
• group (str) – Primary key or name of the group to disassociate.
Returns
Dictionary of only one key “changed”, which indicates whether the disassociation
succeeded.
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
insights(pk=None, **kwargs)
List host insights.
Parameters
• pk (int) – Primary key of the target host.
• **kwargs – Keyword arguments list of available fields used for searching resource
objects.
Returns
A JSON object of host insights.
Return type
dict
list(group=None, host_filter=None, **kwargs)
Retrieve a list of hosts.
Parameters
• group (str) – Primary key or name of the group whose hosts will be listed.
• 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
list_facts(pk=None, **kwargs)
List all available facts of the given host.
Parameters
• pk (int) – Primary key of the target host.
• **kwargs – Keyword arguments list of available fields used for searching resource
objects.
Returns
A JSON object of all available facts of the given host.
Return type
dict
modify(pk=None, create_on_missing=False, **kwargs)
Modify an already existing object.
Parameters
• pk (int) – Primary key of the resource to be modified.
• create_on_missing (bool) – Flag that if set, a new object is created if pk is not
set and objects matching the appropriate unique criteria is not found.
• **kwargs – Keyword arguements which, all together, will be used as PATCH body to
modify the resource object. if pk is not set, key-value pairs of **kwargs which
are also in resource’s identity will be used to lookup existing reosource.
Returns
A dictionary combining the JSON output of the modified resource, as well as two
extra fields: “changed”, a flag indicating if the resource is successfully updated;
“id”, an integer which is the primary key of the updated object.
Return type
dict
Instance Group
Description
This resource is used for managing instance group resources in Tower. Note since instance groups are
read-only in Tower, only get and list methods are available for this resource.
Fields Table
┌──────────────────┬────────┬───────────────────┬───────────┬────────┬────────────┬──────────┐
│name │ type │ help_text │ read_only │ unique │ filterable │ required │
├──────────────────┼────────┼───────────────────┼───────────┼────────┼────────────┼──────────┤
│name │ String │ The name │ False │ False │ True │ False │
│ │ │ field. │ │ │ │ │
├──────────────────┼────────┼───────────────────┼───────────┼────────┼────────────┼──────────┤
│capacity │ int │ The capacity │ False │ False │ True │ False │
│ │ │ field. │ │ │ │ │
└──────────────────┴────────┴───────────────────┴───────────┴────────┴────────────┴──────────┘
│consumed_capacity │ int │ The │ False │ False │ True │ False │
│ │ │ consumed_capacity │ │ │ │ │
│ │ │ field. │ │ │ │ │
└──────────────────┴────────┴───────────────────┴───────────┴────────┴────────────┴──────────┘
API Specification
class tower_cli.resources.instance_group.Resource
A resource for instance groups.
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
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
Instance
Description
This resource is used for managing instance resources in Tower. Note since instances are read-only in
Tower, only get and list methods are available for this resource.
Fields Table
┌──────────────────┬────────┬───────────────────┬───────────┬────────┬────────────┬──────────┐
│name │ type │ help_text │ read_only │ unique │ filterable │ required │
├──────────────────┼────────┼───────────────────┼───────────┼────────┼────────────┼──────────┤
│uuid │ String │ The uuid │ False │ False │ True │ False │
│ │ │ field. │ │ │ │ │
├──────────────────┼────────┼───────────────────┼───────────┼────────┼────────────┼──────────┤
│hostname │ String │ The hostname │ False │ False │ True │ False │
│ │ │ field. │ │ │ │ │
├──────────────────┼────────┼───────────────────┼───────────┼────────┼────────────┼──────────┤
│version │ String │ The version │ False │ False │ True │ False │
│ │ │ field. │ │ │ │ │
├──────────────────┼────────┼───────────────────┼───────────┼────────┼────────────┼──────────┤
│capacity │ int │ The capacity │ False │ False │ True │ False │
│ │ │ field. │ │ │ │ │
├──────────────────┼────────┼───────────────────┼───────────┼────────┼────────────┼──────────┤
│consumed_capacity │ int │ The │ False │ False │ True │ False │
│ │ │ consumed_capacity │ │ │ │ │
│ │ │ field. │ │ │ │ │
└──────────────────┴────────┴───────────────────┴───────────┴────────┴────────────┴──────────┘
API Specification
class tower_cli.resources.instance.Resource
A resource for instances.
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
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
Inventory Script
Description
This resource is used for managing inventory script resources in Tower.
Fields Table
┌─────────────┬──────────────┬────────────────┬───────────┬────────┬────────────┬──────────┐
│name │ type │ help_text │ read_only │ unique │ filterable │ required │
├─────────────┼──────────────┼────────────────┼───────────┼────────┼────────────┼──────────┤
│name │ String │ The name │ False │ True │ True │ True │
│ │ │ field. │ │ │ │ │
├─────────────┼──────────────┼────────────────┼───────────┼────────┼────────────┼──────────┤
│description │ String │ The │ False │ False │ True │ False │
│ │ │ description │ │ │ │ │
│ │ │ field. │ │ │ │ │
├─────────────┼──────────────┼────────────────┼───────────┼────────┼────────────┼──────────┤
│script │ variables │ Script code to │ False │ False │ True │ True │
│ │ │ fetch │ │ │ │ │
│ │ │ inventory, │ │ │ │ │
│ │ │ prefix with │ │ │ │ │
│ │ │ “@” to use │ │ │ │ │
│ │ │ contents of │ │ │ │ │
│ │ │ file for this │ │ │ │ │
│ │ │ field. │ │ │ │ │
├─────────────┼──────────────┼────────────────┼───────────┼────────┼────────────┼──────────┤
│organization │ Resource │ The │ False │ False │ True │ True │
│ │ organization │ organization │ │ │ │ │
│ │ │ field. │ │ │ │ │
└─────────────┴──────────────┴────────────────┴───────────┴────────┴────────────┴──────────┘
API Specification
class tower_cli.resources.inventory_script.Resource
A resource for inventory scripts.
copy(pk=None, **kwargs)
Copy an object.
Parameters
• pk (int) – Primary key of the resource object to be copied
• **kwargs – Keyword arguments of fields whose given value will override the
original value.
Returns
loaded JSON of the copied new resource object.
Return type
dict
create(**kwargs)
Create an object.
Parameters
• fail_on_found (bool) – Flag that if set, the operation fails if an object matching
the unique criteria already exists.
• force_on_exists (bool) – Flag that if set, then if a match is found on unique
fields, other fields will be updated to the provided values.; If unset, a match
causes the request to be a no-op.
• **kwargs – Keyword arguements which, all together, will be used as POST body to
create the resource object.
Returns
A dictionary combining the JSON output of the created resource, as well as two extra
fields: “changed”, a flag indicating if the resource is created successfully; “id”,
an integer which is the primary key of the created object.
Return type
dict
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
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
modify(pk=None, create_on_missing=False, **kwargs)
Modify an already existing object.
Parameters
• pk (int) – Primary key of the resource to be modified.
• create_on_missing (bool) – Flag that if set, a new object is created if pk is not
set and objects matching the appropriate unique criteria is not found.
• **kwargs – Keyword arguements which, all together, will be used as PATCH body to
modify the resource object. if pk is not set, key-value pairs of **kwargs which
are also in resource’s identity will be used to lookup existing reosource.
Returns
A dictionary combining the JSON output of the modified resource, as well as two
extra fields: “changed”, a flag indicating if the resource is successfully updated;
“id”, an integer which is the primary key of the updated object.
Return type
dict
Inventory Source
Description
This resource is used for managing and executing inventory sources via Tower. Note inventory updates are
triggered via update method.
Fields Table
┌─────────────────────────┬────────────────────────────────────────────────────────────────────────────────┬──────────────────────────┬───────────┬────────┬────────────┬──────────┐
├─────────────────────────┼────────────────────────────────────────────────────────────────────────────────┼──────────────────────────┼───────────┼────────┼────────────┼──────────┤
├─────────────────────────┼────────────────────────────────────────────────────────────────────────────────┼──────────────────────────┼───────────┼────────┼────────────┼──────────┤
├─────────────────────────┼────────────────────────────────────────────────────────────────────────────────┼──────────────────────────┼───────────┼────────┼────────────┼──────────┤
├─────────────────────────┼────────────────────────────────────────────────────────────────────────────────┼──────────────────────────┼───────────┼────────┼────────────┼──────────┤
├─────────────────────────┼────────────────────────────────────────────────────────────────────────────────┼──────────────────────────┼───────────┼────────┼────────────┼──────────┤
├─────────────────────────┼────────────────────────────────────────────────────────────────────────────────┼──────────────────────────┼───────────┼────────┼────────────┼──────────┤
├─────────────────────────┼────────────────────────────────────────────────────────────────────────────────┼──────────────────────────┼───────────┼────────┼────────────┼──────────┤
├─────────────────────────┼────────────────────────────────────────────────────────────────────────────────┼──────────────────────────┼───────────┼────────┼────────────┼──────────┤
├─────────────────────────┼────────────────────────────────────────────────────────────────────────────────┼──────────────────────────┼───────────┼────────┼────────────┼──────────┤
└─────────────────────────┴────────────────────────────────────────────────────────────────────────────────┴──────────────────────────┴───────────┴────────┴────────────┴──────────┘
├─────────────────────────┼────────────────────────────────────────────────────────────────────────────────┼──────────────────────────┼───────────┼────────┼────────────┼──────────┤
├─────────────────────────┼────────────────────────────────────────────────────────────────────────────────┼──────────────────────────┼───────────┼────────┼────────────┼──────────┤
├─────────────────────────┼────────────────────────────────────────────────────────────────────────────────┼──────────────────────────┼───────────┼────────┼────────────┼──────────┤
├─────────────────────────┼────────────────────────────────────────────────────────────────────────────────┼──────────────────────────┼───────────┼────────┼────────────┼──────────┤
├─────────────────────────┼────────────────────────────────────────────────────────────────────────────────┼──────────────────────────┼───────────┼────────┼────────────┼──────────┤
├─────────────────────────┼────────────────────────────────────────────────────────────────────────────────┼──────────────────────────┼───────────┼────────┼────────────┼──────────┤
├─────────────────────────┼────────────────────────────────────────────────────────────────────────────────┼──────────────────────────┼───────────┼────────┼────────────┼──────────┤
├─────────────────────────┼────────────────────────────────────────────────────────────────────────────────┼──────────────────────────┼───────────┼────────┼────────────┼──────────┤
└─────────────────────────┴────────────────────────────────────────────────────────────────────────────────┴──────────────────────────┴───────────┴────────┴────────────┴──────────┘
API Specification
class tower_cli.resources.inventory_source.Resource(*args, **kwargs)
A resource for inventory sources.
copy(pk=None, **kwargs)
Copy an object.
Parameters
• pk (int) – Primary key of the resource object to be copied
• **kwargs – Keyword arguments of fields whose given value will override the
original value.
Returns
loaded JSON of the copied new resource object.
Return type
dict
create(**kwargs)
Create an object.
Parameters
• fail_on_found (bool) – Flag that if set, the operation fails if an object matching
the unique criteria already exists.
• force_on_exists (bool) – Flag that if set, then if a match is found on unique
fields, other fields will be updated to the provided values.; If unset, a match
causes the request to be a no-op.
• **kwargs – Keyword arguements which, all together, will be used as POST body to
create the resource object.
Returns
A dictionary combining the JSON output of the created resource, as well as two extra
fields: “changed”, a flag indicating if the resource is created successfully; “id”,
an integer which is the primary key of the created object.
Return type
dict
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
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
modify(pk=None, create_on_missing=False, **kwargs)
Modify an already existing object.
Parameters
• pk (int) – Primary key of the resource to be modified.
• create_on_missing (bool) – Flag that if set, a new object is created if pk is not
set and objects matching the appropriate unique criteria is not found.
• **kwargs – Keyword arguements which, all together, will be used as PATCH body to
modify the resource object. if pk is not set, key-value pairs of **kwargs which
are also in resource’s identity will be used to lookup existing reosource.
Returns
A dictionary combining the JSON output of the modified resource, as well as two
extra fields: “changed”, a flag indicating if the resource is successfully updated;
“id”, an integer which is the primary key of the updated object.
Return type
dict
monitor(pk, parent_pk=None, timeout=None, interval=0.5, outfile=<_io.TextIOWrapper name='<stdout>'
mode='w' encoding='UTF-8'>, **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 wiil 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
• tower_cli.exceptions.Timeout – When monitor time reaches time out.
• tower_cli.exceptions.JobFailure – When the job being monitored runs into failure.
status(pk, detail=False, **kwargs)
Retrieve the current inventory update 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
update(inventory_source, monitor=False, wait=False, timeout=None, **kwargs)
Update the given inventory source.
Parameters
• inventory_source (str) – Primary key or name of the inventory source to be
updated.
• monitor (bool) – Flag that if set, immediately calls monitor on the newly launched
inventory update rather than exiting with a success.
• wait (bool) – Flag that if set, monitor the status of the inventory update, but do
not print while it is in progress.
• timeout (int) – If provided with monitor flag set, this attempt will time out
after the given number of seconds.
• **kwargs – Fields used to override underlyingl inventory source fields when
creating and launching an inventory update.
Returns
Result of subsequent monitor call if monitor flag is on; Result of subsequent wait
call if wait flag is on; dictionary of “status” if none of the two flags are on.
Return type
dict
Raises tower_cli.exceptions.BadRequest – When the inventory source cannot be updated.
wait(pk, parent_pk=None, min_interval=1, max_interval=30, timeout=None, outfile=<_io.TextIOWrapper
name='<stdout>' mode='w' encoding='UTF-8'>, 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
• tower_cli.exceptions.Timeout – When wait time reaches time out.
• tower_cli.exceptions.JobFailure – When the job being waited on runs into failure.
Inventory Update
Description
This resource is used for managing and executing inventory updates via Tower.
Fields Table
┌─────────────────┬────────────────────────────────────────────────────────────────────────────────┬──────────────────┬───────────┬────────┬────────────┬──────────┐
├─────────────────┼────────────────────────────────────────────────────────────────────────────────┼──────────────────┼───────────┼────────┼────────────┼──────────┤
├─────────────────┼────────────────────────────────────────────────────────────────────────────────┼──────────────────┼───────────┼────────┼────────────┼──────────┤
├─────────────────┼────────────────────────────────────────────────────────────────────────────────┼──────────────────┼───────────┼────────┼────────────┼──────────┤
├─────────────────┼────────────────────────────────────────────────────────────────────────────────┼──────────────────┼───────────┼────────┼────────────┼──────────┤
├─────────────────┼────────────────────────────────────────────────────────────────────────────────┼──────────────────┼───────────┼────────┼────────────┼──────────┤
├─────────────────┼────────────────────────────────────────────────────────────────────────────────┼──────────────────┼───────────┼────────┼────────────┼──────────┤
├─────────────────┼────────────────────────────────────────────────────────────────────────────────┼──────────────────┼───────────┼────────┼────────────┼──────────┤
├─────────────────┼────────────────────────────────────────────────────────────────────────────────┼──────────────────┼───────────┼────────┼────────────┼──────────┤
└─────────────────┴────────────────────────────────────────────────────────────────────────────────┴──────────────────┴───────────┴────────┴────────────┴──────────┘
API Specification
class tower_cli.resources.inventory_update.Resource(*args, **kwargs)
A resource for inventory source updates.
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
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=<_io.TextIOWrapper name='<stdout>'
mode='w' encoding='UTF-8'>, **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 wiil 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
• tower_cli.exceptions.Timeout – When monitor time reaches time out.
• tower_cli.exceptions.JobFailure – When the job being monitored runs into failure.
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=<_io.TextIOWrapper
name='<stdout>' mode='w' encoding='UTF-8'>, 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
• tower_cli.exceptions.Timeout – When wait time reaches time out.
• tower_cli.exceptions.JobFailure – When the job being waited on runs into failure.
Inventory
Description
This resource is used for managing inventory resources in Tower.
Fields Table
┌────────────────────┬──────────────┬─────────────────────┬───────────┬────────┬────────────┬──────────┐
│name │ type │ help_text │ read_only │ unique │ filterable │ required │
├────────────────────┼──────────────┼─────────────────────┼───────────┼────────┼────────────┼──────────┤
│name │ String │ The name │ False │ True │ True │ True │
│ │ │ field. │ │ │ │ │
├────────────────────┼──────────────┼─────────────────────┼───────────┼────────┼────────────┼──────────┤
│description │ String │ The │ False │ False │ True │ False │
│ │ │ description │ │ │ │ │
│ │ │ field. │ │ │ │ │
├────────────────────┼──────────────┼─────────────────────┼───────────┼────────┼────────────┼──────────┤
│organization │ Resource │ The │ False │ False │ True │ True │
│ │ organization │ organization │ │ │ │ │
│ │ │ field. │ │ │ │ │
├────────────────────┼──────────────┼─────────────────────┼───────────┼────────┼────────────┼──────────┤
│variables │ variables │ Inventory │ False │ False │ True │ False │
│ │ │ variables, use │ │ │ │ │
│ │ │ “@” to get │ │ │ │ │
│ │ │ from file. │ │ │ │ │
├────────────────────┼──────────────┼─────────────────────┼───────────┼────────┼────────────┼──────────┤
│kind │ Choices: │ The kind │ False │ False │ True │ False │
│ │ ,smart │ field. Cannot │ │ │ │ │
│ │ │ be modified │ │ │ │ │
│ │ │ after created. │ │ │ │ │
├────────────────────┼──────────────┼─────────────────────┼───────────┼────────┼────────────┼──────────┤
│host_filter │ String │ The │ False │ False │ True │ False │
│ │ │ host_filter │ │ │ │ │
│ │ │ field. Only │ │ │ │ │
│ │ │ useful when │ │ │ │ │
│ │ │ kind=smart. │ │ │ │ │
├────────────────────┼──────────────┼─────────────────────┼───────────┼────────┼────────────┼──────────┤
│insights_credential │ Resource │ The │ False │ False │ True │ False │
│ │ credential │ insights_credential │ │ │ │ │
│ │ │ field. │ │ │ │ │
└────────────────────┴──────────────┴─────────────────────┴───────────┴────────┴────────────┴──────────┘
API Specification
class tower_cli.resources.inventory.Resource
A resource for inventories.
associate_ig(inventory, instance_group)
Associate an instance group with this inventory.
Parameters
• inventory (str) – Primary key or name of the inventory to associate to.
• instance_group (str) – Primary key or name of the instance group to be associated.
Returns
Dictionary of only one key “changed”, which indicates whether the association
succeeded.
Return type
dict
batch_update(pk=None, **kwargs)
Update all related inventory sources of the given inventory.
Parameters
• pk (int) – Primary key of the given inventory.
• **kwargs – Keyword arguments list of available fields used for searching resource
objects.
Returns
A JSON object of update status of the given inventory.
Return type
dict
copy(pk=None, **kwargs)
Copy an object.
Parameters
• pk (int) – Primary key of the resource object to be copied
• **kwargs – Keyword arguments of fields whose given value will override the
original value.
Returns
loaded JSON of the copied new resource object.
Return type
dict
create(**kwargs)
Create an object.
Parameters
• fail_on_found (bool) – Flag that if set, the operation fails if an object matching
the unique criteria already exists.
• force_on_exists (bool) – Flag that if set, then if a match is found on unique
fields, other fields will be updated to the provided values.; If unset, a match
causes the request to be a no-op.
• **kwargs – Keyword arguements which, all together, will be used as POST body to
create the resource object.
Returns
A dictionary combining the JSON output of the created resource, as well as two extra
fields: “changed”, a flag indicating if the resource is created successfully; “id”,
an integer which is the primary key of the created object.
Return type
dict
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
disassociate_ig(inventory, instance_group)
Disassociate an instance group with this inventory.
Parameters
• inventory (str) – Primary key or name of the inventory to associate to.
• instance_group (str) – Primary key or name of the instance group to be associated.
Returns
Dictionary of only one key “changed”, which indicates whether the association
succeeded.
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
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
modify(pk=None, create_on_missing=False, **kwargs)
Modify an already existing object.
Parameters
• pk (int) – Primary key of the resource to be modified.
• create_on_missing (bool) – Flag that if set, a new object is created if pk is not
set and objects matching the appropriate unique criteria is not found.
• **kwargs – Keyword arguements which, all together, will be used as PATCH body to
modify the resource object. if pk is not set, key-value pairs of **kwargs which
are also in resource’s identity will be used to lookup existing reosource.
Returns
A dictionary combining the JSON output of the modified resource, as well as two
extra fields: “changed”, a flag indicating if the resource is successfully updated;
“id”, an integer which is the primary key of the updated object.
Return type
dict
Job Template
Description
This resource is used for managing job template resources in Tower. It is also responsible to
associate/disassociate labels and notification templates to/from an existing job template. There is yet
another custom command, survey, used for getting survey specification of a job template.
Fields Table
┌─────────────────────────┬───────────────┬────────────────────┬───────────┬────────┬────────────┬──────────┐
│name │ type │ help_text │ read_only │ unique │ filterable │ required │
├─────────────────────────┼───────────────┼────────────────────┼───────────┼────────┼────────────┼──────────┤
│name │ String │ The name │ False │ True │ True │ True │
│ │ │ field. │ │ │ │ │
├─────────────────────────┼───────────────┼────────────────────┼───────────┼────────┼────────────┼──────────┤
│description │ String │ The │ False │ False │ True │ False │
│ │ │ description │ │ │ │ │
│ │ │ field. │ │ │ │ │
├─────────────────────────┼───────────────┼────────────────────┼───────────┼────────┼────────────┼──────────┤
│job_type │ Choices: │ The job_type │ False │ False │ True │ False │
│ │ run,check │ field. │ │ │ │ │
└─────────────────────────┴───────────────┴────────────────────┴───────────┴────────┴────────────┴──────────┘
│inventory │ Resource │ The inventory │ False │ False │ True │ False │
│ │ inventory │ field. │ │ │ │ │
├─────────────────────────┼───────────────┼────────────────────┼───────────┼────────┼────────────┼──────────┤
│project │ Resource │ The project │ False │ False │ True │ True │
│ │ project │ field. │ │ │ │ │
├─────────────────────────┼───────────────┼────────────────────┼───────────┼────────┼────────────┼──────────┤
│playbook │ String │ The playbook │ False │ False │ True │ True │
│ │ │ field. │ │ │ │ │
├─────────────────────────┼───────────────┼────────────────────┼───────────┼────────┼────────────┼──────────┤
│credential │ Resource │ The credential │ False │ False │ True │ False │
│ │ credential │ field. │ │ │ │ │
├─────────────────────────┼───────────────┼────────────────────┼───────────┼────────┼────────────┼──────────┤
│vault_credential │ Resource │ The │ False │ False │ True │ False │
│ │ credential │ vault_credential │ │ │ │ │
│ │ │ field. │ │ │ │ │
├─────────────────────────┼───────────────┼────────────────────┼───────────┼────────┼────────────┼──────────┤
│forks │ int │ The forks field. │ False │ False │ True │ False │
├─────────────────────────┼───────────────┼────────────────────┼───────────┼────────┼────────────┼──────────┤
│limit │ String │ The limit field. │ False │ False │ True │ False │
├─────────────────────────┼───────────────┼────────────────────┼───────────┼────────┼────────────┼──────────┤
│verbosity │ mapped_choice │ The verbosity │ False │ False │ True │ False │
│ │ │ field. │ │ │ │ │
├─────────────────────────┼───────────────┼────────────────────┼───────────┼────────┼────────────┼──────────┤
│extra_vars │ variables │ Extra variables │ False │ False │ True │ False │
│ │ │ used by Ansible │ │ │ │ │
│ │ │ in YAML or │ │ │ │ │
│ │ │ key=value │ │ │ │ │
│ │ │ format. Use @ to │ │ │ │ │
│ │ │ get YAML from a │ │ │ │ │
│ │ │ file. │ │ │ │ │
├─────────────────────────┼───────────────┼────────────────────┼───────────┼────────┼────────────┼──────────┤
│job_tags │ String │ The job_tags │ False │ False │ True │ False │
│ │ │ field. │ │ │ │ │
├─────────────────────────┼───────────────┼────────────────────┼───────────┼────────┼────────────┼──────────┤
│force_handlers │ bool │ The │ False │ False │ True │ False │
│ │ │ force_handlers │ │ │ │ │
│ │ │ field. │ │ │ │ │
├─────────────────────────┼───────────────┼────────────────────┼───────────┼────────┼────────────┼──────────┤
│skip_tags │ String │ The skip_tags │ False │ False │ True │ False │
│ │ │ field. │ │ │ │ │
├─────────────────────────┼───────────────┼────────────────────┼───────────┼────────┼────────────┼──────────┤
│start_at_task │ String │ The │ False │ False │ True │ False │
│ │ │ start_at_task │ │ │ │ │
│ │ │ field. │ │ │ │ │
├─────────────────────────┼───────────────┼────────────────────┼───────────┼────────┼────────────┼──────────┤
│timeout │ int │ The amount of │ False │ False │ True │ False │
│ │ │ time (in │ │ │ │ │
│ │ │ seconds) to run │ │ │ │ │
│ │ │ before the task │ │ │ │ │
│ │ │ is canceled. │ │ │ │ │
├─────────────────────────┼───────────────┼────────────────────┼───────────┼────────┼────────────┼──────────┤
│use_fact_cache │ bool │ If enabled, │ False │ False │ True │ False │
│ │ │ Tower will act │ │ │ │ │
│ │ │ as an Ansible │ │ │ │ │
│ │ │ Fact Cache │ │ │ │ │
│ │ │ Plugin; │ │ │ │ │
│ │ │ persisting facts │ │ │ │ │
│ │ │ at the end of a │ │ │ │ │
│ │ │ playbook run to │ │ │ │ │
│ │ │ the database and │ │ │ │ │
│ │ │ caching facts │ │ │ │ │
│ │ │ for use by │ │ │ │ │
│ │ │ Ansible. │ │ │ │ │
├─────────────────────────┼───────────────┼────────────────────┼───────────┼────────┼────────────┼──────────┤
│host_config_key │ String │ Allow │ False │ False │ True │ False │
│ │ │ Provisioning │ │ │ │ │
│ │ │ Callbacks using │ │ │ │ │
│ │ │ this host config │ │ │ │ │
│ │ │ key │ │ │ │ │
├─────────────────────────┼───────────────┼────────────────────┼───────────┼────────┼────────────┼──────────┤
│ask_diff_mode_on_launch │ bool │ Ask diff mode on │ False │ False │ True │ False │
│ │ │ launch. │ │ │ │ │
├─────────────────────────┼───────────────┼────────────────────┼───────────┼────────┼────────────┼──────────┤
│ask_variables_on_launch │ bool │ Prompt user for │ False │ False │ True │ False │
│ │ │ extra_vars on │ │ │ │ │
│ │ │ launch. │ │ │ │ │
├─────────────────────────┼───────────────┼────────────────────┼───────────┼────────┼────────────┼──────────┤
│ask_limit_on_launch │ bool │ Prompt user for │ False │ False │ True │ False │
│ │ │ host limits on │ │ │ │ │
│ │ │ launch. │ │ │ │ │
└─────────────────────────┴───────────────┴────────────────────┴───────────┴────────┴────────────┴──────────┘
│ask_tags_on_launch │ bool │ Prompt user for │ False │ False │ True │ False │
│ │ │ job tags on │ │ │ │ │
│ │ │ launch. │ │ │ │ │
├─────────────────────────┼───────────────┼────────────────────┼───────────┼────────┼────────────┼──────────┤
│ask_skip_tags_on_launch │ bool │ Prompt user for │ False │ False │ True │ False │
│ │ │ tags to skip on │ │ │ │ │
│ │ │ launch. │ │ │ │ │
├─────────────────────────┼───────────────┼────────────────────┼───────────┼────────┼────────────┼──────────┤
│ask_job_type_on_launch │ bool │ Prompt user for │ False │ False │ True │ False │
│ │ │ job type on │ │ │ │ │
│ │ │ launch. │ │ │ │ │
├─────────────────────────┼───────────────┼────────────────────┼───────────┼────────┼────────────┼──────────┤
│ask_verbosity_on_launch │ bool │ Prompt user for │ False │ False │ True │ False │
│ │ │ verbosity on │ │ │ │ │
│ │ │ launch. │ │ │ │ │
├─────────────────────────┼───────────────┼────────────────────┼───────────┼────────┼────────────┼──────────┤
│ask_inventory_on_launch │ bool │ Prompt user for │ False │ False │ True │ False │
│ │ │ inventory on │ │ │ │ │
│ │ │ launch. │ │ │ │ │
├─────────────────────────┼───────────────┼────────────────────┼───────────┼────────┼────────────┼──────────┤
│ask_credential_on_launch │ bool │ Prompt user for │ False │ False │ True │ False │
│ │ │ machine │ │ │ │ │
│ │ │ credential on │ │ │ │ │
│ │ │ launch. │ │ │ │ │
├─────────────────────────┼───────────────┼────────────────────┼───────────┼────────┼────────────┼──────────┤
│survey_enabled │ bool │ Prompt user for │ False │ False │ True │ False │
│ │ │ job type on │ │ │ │ │
│ │ │ launch. │ │ │ │ │
├─────────────────────────┼───────────────┼────────────────────┼───────────┼────────┼────────────┼──────────┤
│become_enabled │ bool │ The │ False │ False │ True │ False │
│ │ │ become_enabled │ │ │ │ │
│ │ │ field. │ │ │ │ │
├─────────────────────────┼───────────────┼────────────────────┼───────────┼────────┼────────────┼──────────┤
│diff_mode │ bool │ If enabled, │ False │ False │ True │ False │
│ │ │ textual changes │ │ │ │ │
│ │ │ made to any │ │ │ │ │
│ │ │ templated files │ │ │ │ │
│ │ │ on the host are │ │ │ │ │
│ │ │ shown in the │ │ │ │ │
│ │ │ standard output. │ │ │ │ │
├─────────────────────────┼───────────────┼────────────────────┼───────────┼────────┼────────────┼──────────┤
│allow_simultaneous │ bool │ The │ False │ False │ True │ False │
│ │ │ allow_simultaneous │ │ │ │ │
│ │ │ field. │ │ │ │ │
├─────────────────────────┼───────────────┼────────────────────┼───────────┼────────┼────────────┼──────────┤
│survey_spec │ variables │ On write commands, │ False │ False │ True │ False │
│ │ │ perform extra POST │ │ │ │ │
│ │ │ to the survey_spec │ │ │ │ │
│ │ │ endpoint. │ │ │ │ │
└─────────────────────────┴───────────────┴────────────────────┴───────────┴────────┴────────────┴──────────┘
API Specification
class tower_cli.resources.job_template.Resource
A resource for job templates.
associate_credential(job_template, credential)
Associate a credential with this job template.
Parameters
• job_template (str) – The job template to associate to.
• credential (str) – The credential to be associated.
Returns
Dictionary of only one key “changed”, which indicates whether the association
succeeded.
Return type
dict
associate_ig(job_template, instance_group)
Associate an instance group with this job_template.
Parameters
• job_template (str) – Primary key or name of the job_template to associate to.
• instance_group (str) – Primary key or name of the instance group to be associated.
Returns
Dictionary of only one key “changed”, which indicates whether the association
succeeded.
Return type
dict
associate_label(job_template, label)
Associate an label with this job template.
Parameters
• job_template (str) – The job template to associate to.
• label (str) – The label to be associated.
Returns
Dictionary of only one key “changed”, which indicates whether the association
succeeded.
Return type
dict
associate_notification_template(job_template, notification_template, status)
Associate a notification template from this job template.
Parameters
• job_template (str) – The job template to associate to.
• notification_template (str) – The notification template to be associated.
• status (str) – type of notification this notification template should be
associated to.
Returns
Dictionary of only one key “changed”, which indicates whether the association
succeeded.
Return type
dict
callback(pk=None, host_config_key='', extra_vars=None)
Contact Tower and request a provisioning callback using this job template.
Parameters
• pk (int) – Primary key of the job template to run provisioning callback against.
• host_config_key (str) – Key string used to authenticate the callback host.
• extra_vars (array of str) – Extra variables that are passed to provisioning
callback.
Returns
A dictionary of a single key “changed”, which indicates whether the provisioning
callback is successful.
Return type
dict
copy(pk=None, **kwargs)
Copy an object.
Parameters
• pk (int) – Primary key of the resource object to be copied
• **kwargs – Keyword arguments of fields whose given value will override the
original value.
Returns
loaded JSON of the copied new resource object.
Return type
dict
create(**kwargs)
Create an object.
Parameters
• fail_on_found (bool) – Flag that if set, the operation fails if an object matching
the unique criteria already exists.
• force_on_exists (bool) – Flag that if set, then if a match is found on unique
fields, other fields will be updated to the provided values.; If unset, a match
causes the request to be a no-op.
• **kwargs – Keyword arguements which, all together, will be used as POST body to
create the resource object.
Returns
A dictionary combining the JSON output of the created resource, as well as two extra
fields: “changed”, a flag indicating if the resource is created successfully; “id”,
an integer which is the primary key of the created object.
Return type
dict
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
disassociate_credential(job_template, credential)
Disassociate a credential from this job template.
Parameters
• job_template (str) – The job template to disassociate fom.
• credential (str) – The credential to be disassociated.
Returns
Dictionary of only one key “changed”, which indicates whether the disassociation
succeeded.
Return type
dict
disassociate_ig(job_template, instance_group)
Disassociate an instance group with this job_template.
Parameters
• job_template (str) – Primary key or name of the job_template to associate to.
• instance_group (str) – Primary key or name of the instance group to be associated.
Returns
Dictionary of only one key “changed”, which indicates whether the association
succeeded.
Return type
dict
disassociate_label(job_template, label)
Disassociate an label from this job template.
Parameters
• job_template (str) – The job template to disassociate from.
• label (str) – The label to be disassociated.
Returns
Dictionary of only one key “changed”, which indicates whether the disassociation
succeeded.
Return type
dict
disassociate_notification_template(job_template, notification_template, status)
Disassociate a notification template from this job template.
Parameters
• job_template (str) – The job template to disassociate from.
• notification_template (str) – The notification template to be disassociated.
• status (str) – type of notification this notification template should be
disassociated from.
Returns
Dictionary of only one key “changed”, which indicates whether the disassociation
succeeded.
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
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
modify(pk=None, create_on_missing=False, **kwargs)
Modify an already existing object.
Parameters
• pk (int) – Primary key of the resource to be modified.
• create_on_missing (bool) – Flag that if set, a new object is created if pk is not
set and objects matching the appropriate unique criteria is not found.
• **kwargs – Keyword arguements which, all together, will be used as PATCH body to
modify the resource object. if pk is not set, key-value pairs of **kwargs which
are also in resource’s identity will be used to lookup existing reosource.
Returns
A dictionary combining the JSON output of the modified resource, as well as two
extra fields: “changed”, a flag indicating if the resource is successfully updated;
“id”, an integer which is the primary key of the updated object.
Return type
dict
survey(pk=None, **kwargs)
Get the survey specification of a resource object.
Parameters
• pk (int) – Primary key of the resource to retrieve survey from. 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 survey if
pk is not provided.
Returns
loaded JSON of the retrieved survey specification of the resource object.
Return type
dict
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 The False False True False
job_template job_template
field.
────────────────────────────────────────────────────────────────────────────────────────────────
job_explanation String The False False True False
job_explanation
field.
────────────────────────────────────────────────────────────────────────────────────────────────
created String The created False False True False
field.
────────────────────────────────────────────────────────────────────────────────────────────────
status String The status False False True False
field.
────────────────────────────────────────────────────────────────────────────────────────────────
elapsed String The elapsed False False True False
field.
┌────────────────┬──────────────┬─────────────────┬───────────┬────────┬────────────┬──────────┐
│ │ │ │ │ │ │ │
--
AUTHOR
Alan Rominger, Luke Sneeringer, Aaron Tan
COPYRIGHT
2017, Ansible by Red Hat
Oct 31, 2017 TOWER_CLI(1)