Provided by: ansible-tower-cli_3.3.0-1.1_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 familiar with ansible-tower-cli’s dependency tree, we suggested building
source in a fresh virtual environment to prevent any dependency conflict.
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 futher details, please see api_ref and
cli_ref.
It is assumed you have a Tower backend available to talk to and Tower CLI installed.
Please see the 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 details necessary for Tower CLI to communicate to Tower. With these
prerequisites, run
$ tower-cli config host tower.example.com
$ tower-cli login username
Password:
The first Tower CLI command, tower-cli config, writes the connection information to a
configuration file (~/.tower-cli.cfg, by default), and subsequent commands and API calls
will read this file, extract connection information and interact with Tower. See details
of Tower CLI configuration in api_ref and tower-cli config --help.
The second command, tower-cli login, will prompt you for your password and will acquire an
OAuth2 token (which will also be saved to a configuration file) with write scope. You can
also request read scope for read-only access:
$ tower-cli login username --scope read
Password:
NOTE:
Older versions of Tower (prior to 3.3) do not support OAuth2 token authentication, and
instead utilize per-request basic HTTP authentication:
$ tower-cli config host tower.example.com
$ tower-cli config username user
$ tower-cli config username pass
Next, 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:
from 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.
CLI Reference
CLI invocation generally follows this format:
$ tower-cli {resource} {action} ...
The “resource” is a type of object within Tower (a noun), such as user, organization,
job_template, etc.; resource names are always singular in Tower CLI (so it is tower-cli
user, never tower-cli users).
The “action” is the thing you want to do (a verb). Most Tower CLI resources have the
following actions–get, list, create, modify, and delete–and have options corresponding to
fields on the object in Tower.
Some examples:
# List all users.
$ tower-cli user list
# List all non-superusers
$ tower-cli user list --is-superuser=false
# Get the user with the ID of 42.
$ tower-cli user get 42
# Get the user with the given username.
$ tower-cli user get --username=guido
# Create a new user.
$ tower-cli user create --username=guido --first-name=Guido \
--last-name="Van Rossum" --email=guido@python.org \
--password=password1234
# Modify an existing user.
# This would modify the first name of the user with the ID of "42" to "Guido".
$ tower-cli user modify 42 --first-name=Guido
# Modify an existing user, lookup by username.
# This would use "username" as the lookup, and modify the first name.
# Which fields are used as lookups vary by resource, but are generally
# the resource's name.
$ tower-cli user modify --username=guido --first-name=Guido
# Delete a user.
$ tower-cli user delete 42
# List all jobs
$ tower-cli job list
# List specific page of job list
$ tower-cli job list --page=1
# Launch a job.
$ tower-cli job launch --job-template=144
# Monitor a job.
$ tower-cli job monitor 95
# Filter job list for currently running jobs
$ tower-cli job list --status=running
# Export all objects
$ tower-cli receive --all
# Export all credentials
$ tower-cli receive --credential all
# Export a credential named "My Credential"
$ tower-cli receive --credential "My Credential"
# Import from a JSON file named assets.json
$ tower-cli send assets.json
# Import anything except an organization defined in a JSON file named assets.json
$ tower-cli send --prevent organization assets.json
# Copy all assets from one instance to another
$ tower-cli receive --tower-host tower1.example.com --all | tower-cli send --tower-host tower2.example.com
When in doubt, help is available!
$ tower-cli --help # help
$ tower-cli user --help # resource specific help
$ tower-cli user create --help # command specific help
In specific, tower-cli --help lists all available resources in the current version of
Tower CLI:
$ tower-cli --help
Usage: tower-cli [OPTIONS] COMMAND [ARGS]...
Options:
--version Display tower-cli version.
--help Show this message and exit.
Commands:
ad_hoc Launch commands based on playbook given at...
config Read or write tower-cli configuration.
credential Manage credentials within Ansible Tower.
credential_type Manage credential types within Ansible Tower.
empty Empties assets from Tower.
group Manage groups belonging to an inventory.
host Manage hosts belonging to a group within an...
instance Check instances within Ansible Tower.
instance_group Check instance groups within Ansible Tower.
inventory Manage inventory within Ansible Tower.
inventory_script Manage inventory scripts within Ansible...
inventory_source Manage inventory sources within Ansible...
job Launch or monitor jobs.
job_template Manage job templates.
label Manage labels within Ansible Tower.
node Manage nodes inside of a workflow job...
notification_template Manage notification templates within Ansible...
organization Manage organizations within Ansible Tower.
project Manage projects within Ansible Tower.
receive Export assets from Tower.
role Add and remove users/teams from roles.
schedule Manage schedules within Ansible Tower.
send Import assets into Tower.
setting Manage settings within Ansible Tower.
team Manage teams within Ansible Tower.
user Manage users within Ansible Tower.
version Display version information.
workflow Manage workflow job templates.
workflow_job Launch or monitor workflow jobs.
and tower-cli {resource} --help lists all available actions:
$ tower-cli user --help
Usage: tower-cli user [OPTIONS] COMMAND [ARGS]...
Manage users within Ansible Tower.
Options:
--help Show this message and exit.
Commands:
copy Copy a user.
create Create a user.
delete Remove the given user.
get Return one and exactly one user.
list Return a list of users.
modify Modify an already existing user.
and tower-cli {resource} {action} --help shows details of the usage of this action:
$ tower-cli user create --help
Usage: tower-cli user create [OPTIONS]
Create a user.
Fields in the resource's --identity tuple are used for a lookup; if a
match is found, then no-op (unless --force-on-exists is set) but do not
fail (unless --fail-on-found is set).
Field Options:
--username TEXT [REQUIRED] The username field.
--password TEXT The password field.
--email TEXT [REQUIRED] The email field.
--first-name TEXT The first_name field.
--last-name TEXT The last_name field.
--is-superuser BOOLEAN The is_superuser field.
--is-system-auditor BOOLEAN The is_system_auditor field.
Local Options:
--fail-on-found If used, return an error if a matching record already
exists. [default: False]
--force-on-exists If used, if a match is found on unique fields, other
fields will be updated to the provided values. If False,
a match causes the request to be a no-op. [default:
False]
Global Options:
--certificate TEXT Path to a custom certificate file that will
be used throughout the command. Overwritten
by --insecure flag if set.
--insecure Turn off insecure connection warnings. Set
config verify_ssl to make this permanent.
--description-on Show description in human-formatted output.
-v, --verbose Show information about requests being made.
-f, --format [human|json|yaml|id]
Output format. The "human" format is
intended for humans reading output on the
CLI; the "json" and "yaml" formats provide
more data, and "id" echos the object id
only.
-p, --tower-password TEXT Password to use to authenticate to Ansible
Tower. This will take precedence over a
password provided to `tower config`, if any.
-u, --tower-username TEXT Username to use to authenticate to Ansible
Tower. This will take precedence over a
username provided to `tower config`, if any.
-h, --tower-host TEXT The location of the Ansible Tower host.
HTTPS is assumed as the protocol unless
"http://" is explicitly provided. This will
take precedence over a host provided to
`tower config`, if any.
--use-token Turn on Tower's token-based authentication.
No longer supported in Tower 3.3 and above
Other Options:
--help Show this message and exit.
There are generally 3 categories of options for each action to take: field options, local
options and global options. Field options can be seen as wrappers around actual resource
fields exposed by Tower REST API. They are generally used to create and modify resources
and filter when searching for specific resources; local options are action-specific
options, they provide fine-grained modification of the behavior of a resource action. for
example, --fail-on-found option of a create action will fail the command if a matching
record already exists in Tower backend; global options are used to set runtime
configuration settings, functioning the same way as context manager
tower_cli.conf.Settings.runtime_values in api-ref-conf.
Config Command Options
key-value options available for tower-cli config <key> <value> command
┌──────────────────┬──────────────────────────┬──────────────────────────┐
│Key │ Value Type/Default │ Description │
├──────────────────┼──────────────────────────┼──────────────────────────┤
│col or │ Boolean/’true’ │ Whether to use colored │
│ │ │ output for highlighting │
│ │ │ or not. │
├──────────────────┼──────────────────────────┼──────────────────────────┤
│for mat │ String with options │ Output format. The │
│ │ (‘human’, ‘json’, │ “human” format is │
│ │ ‘yaml’)/’human’ │ intended for humans │
│ │ │ reading output on the │
│ │ │ CLI; the “json” and │
│ │ │ “yaml” formats provide │
│ │ │ more data. │
├──────────────────┼──────────────────────────┼──────────────────────────┤
│hos t │ String/’127.0.0.1 ‘ │ The location of the │
│ │ │ Ansible Tower host. │
│ │ │ HTTPS is assumed as the │
│ │ │ protocol unless “‐ │
│ │ │ http://” is explicitly │
│ │ │ provided. │
├──────────────────┼──────────────────────────┼──────────────────────────┤
│ │ String/’’ │ Password to use to │
│`` │ │ authenticate to Ansible │
│pas sword `` │ │ Tower. │
├──────────────────┼──────────────────────────┼──────────────────────────┤
│ │ String/’’ │ Username to use to │
│`` │ │ authenticate to Ansible │
│use rname `` │ │ Tower. │
├──────────────────┼──────────────────────────┼──────────────────────────┤
│ver ify_s sl │ Boolean/’true’ │ Whether to force │
│ │ │ verified SSL │
│ │ │ connections. │
└──────────────────┴──────────────────────────┴──────────────────────────┘
│ │ Boolean/’false’ │ Whether to show │
│`` │ │ information about │
│ver bose` ` │ │ requests being made. │
├──────────────────┼──────────────────────────┼──────────────────────────┤
│des cript ion_o n │ Boolean/’false’ │ Whether to show │
│ │ │ description in │
│ │ │ human-formatted output. │
├──────────────────┼──────────────────────────┼──────────────────────────┤
│cer tific ate │ 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 _toke n │ Boolean/’false’ │ Whether to use │
│ │ │ token-based │
│ │ │ authentication. │
└──────────────────┴──────────────────────────┴──────────────────────────┘
Environment Variables
All of the above options can also be set using environment variables. The default
behavior is to allow environment variables to override your tower-cli.cfg settings, but
they will not override config values that are passed in on the command line at runtime.
Below is a table of the available environment variables.
Variable Mapping
┌─────────────────────┬──────────────────┐
│Environment Variable │ Tower Config Key │
├─────────────────────┼──────────────────┤
│TOWER_COLOR │ color │
├─────────────────────┼──────────────────┤
│TOWER_FORMAT │ format │
├─────────────────────┼──────────────────┤
│TOWER_HOST │ host │
├─────────────────────┼──────────────────┤
│TOWER_PASSWORD │ password │
├─────────────────────┼──────────────────┤
│TOWER_USERNAME │ username │
├─────────────────────┼──────────────────┤
│TOWER_VERIFY_SSL │ verify_ssl │
├─────────────────────┼──────────────────┤
│TOWER_VERBOSE │ verbose │
├─────────────────────┼──────────────────┤
│TOWER_DESCRIPTION_ON │ description_on │
├─────────────────────┼──────────────────┤
│TOWER_CERTIFICATE │ certificate │
├─────────────────────┼──────────────────┤
│TOWER_USE_TOKEN │ use_token │
└─────────────────────┴──────────────────┘
Notes
• Under the hood we use the SSL functionality of requests, however the current requests
version has checkings on a deprecated SSL certificate field commonName (deprecated by
RFC 2818). In order to prevent any related usage issues, please make sure to add
subjectAltName field to your own certificate in use. We will update help docs as soon as
changes are made on the requests side.
Versioning of tower-cli
Tower-CLI is a command-line interface and python library to interact with Ansible Tower
and AWX. Only versions of tower-cli can successfully interact with only a certain subset
of versions of Ansible Tower or AWX, and this document is meant to outline the policy.
API Versions
Ansible Tower and AWX communicate with clients through a particular API version, so that
each version forms a stable API for Ansible Tower. Each version of tower-cli also has a
corresponding API version.
Supported Versions with Ansible Tower
The following table summarizes the policy of supported versions.
┌──────────┬─────────────┬───────────────────┐
│tower-cli │ API version │ Tower version │
├──────────┼─────────────┼───────────────────┤
│3.1.x │ v1 │ 3.2.x and earlier │
├──────────┼─────────────┼───────────────────┤
│current │ v2 │ 3.2.x and later │
└──────────┴─────────────┴───────────────────┘
This means that the release series 3.1.x is still open for fixes in order to support
communication with the v1 API and all Tower versions that support that. Many elements of
functionality are removed in the transition to v2, so they are no longer carried with the
current tower-cli version.
Policy with AWX Versions
Compatibility between tower-cli and the AWX project is only considered for the most recent
development version of tower-cli and most recent version of AWX.
API Version Upgrade Guide
If you upgrade tower-cli across an API version change, existing scripts will be broken.
This section highlights the most major backward-incompatible changes that need to be taken
into account in order to migrate your scripts.
API v1->v2
In API v2, credentials have a new related model “credential_type”. This enables custom
credential types, and that old types now need to reference the build-in credential types
instead of the old flat-text kind field.
Additionally, to allow fully arbitrary credential types, the fields used by the credential
in creating the necessary runtime environment are now nested inside of a dictionary called
inputs.
old:
$ tower-cli credential create --name="AWS creds" --team=Ops --kind=aws --username=your_username --password=password
new:
$ tower-cli credential create --name="AWS creds" --team=Ops --credential-type="Amazon Web Services" --inputs='{"username": "your_username", "password": "password"}'
When attaching credentials to job templates, the related link structure has changed.
API v1 options:
• –machine-credential
• –cloud-credential
• –network-credential
API v2 options:
• –credential
• –vault-credential
• Related many-to-many extra_credentials
In order to add “extra” credentials (what used to be cloud credential), use the
association method, tower-cli job_template associate_credential ….
In API v2, only “manual” groups can be created directly. The parameters that used to be
provided to a group to sync to a cloud source now must be directly given to its inventory
source.
old:
$ tower-cli group create --name=EC2 --credential="AWS creds" --source=ec2 --description="EC2 hosts" --inventory=Production
new:
$ tower-cli inventory_source create --name=EC2 --credential="AWS creds" --source=ec2 --description="EC2 hosts" --inventory=Production
To run an inventory update, use the tower-cli inventory_source update command.
Version-specific Secondary Install
In order to use different versions of tower-cli simultaneously in order to interact with
different servers hosting different API versions, you can use this tool packaged in the
source code.
For example:
$ make install_v1
This will install a new CLI entry point, tower-cli-v1, which will behave the same as
tower-cli. However, this installation will persist even after upgrading the main program.
This also provides the python package tower_cli_v1.
Important note: the configuration file is also separate from the secondary install, so you
must re-enter your URL and credentials.
If you want to be sure that you re-install tower-cli-v1, you can do:
$ make v1-refresh
The v1 install is only possible with the v1 branch in the source tree. The master branch
currently tracks API v2, and the prior instructions will work for a v2 secondary install,
replacing v1 with v2.
Notification Template Management
Introduction - What Notification Templates Are
Starting with Ansible Tower 3.0, users can create and associate notification templates to
job templates. Whenever a job template undergoes a successful/unsuccessful job run, all
its related notification templates will send out notifications to corresponding
notification receiver, indicating the status of job run.
Managing Notification Templates with tower-cli
To see the commands available for notification templates, see tower-cli
notification_template --help. Within a specific command, get the help text with tower-cli
notification_template <command> --help.
Notification templates suppport all typical CRUD operations that control other resources
through tower-cli: get, list, create, modify and delete. On the other hand, uses can use
new command tower-cli job_template associate_notification and tower-cli job_tempate
disassociate_notification to (dis)associate an existing notification to/from a job
template.
Basic Operations
CRUD operations on notification templates are basically the same as that of typicall
existing resources, e.g. inventory. There are, however, some points due to the nature of
notification templates that needs to be careful with:
• There are two options in create, --job-template and --status, which controls the create
mode: providing these options will create a new notification template and associate it
with the specified job template. Notification templates will be created isolatedly if
these options are not provided. You can find more information in Tower’s official
documentation.
• When looking at the help text of certain notification template commands, note a large
portion of the available options are prefixed by a label like [slack]. These are special
configuration-related options which are composing elements of a notification template’s
destination configuration. You can find more information about those options in Tower’s
official documentations. These options plus --notification-configuration option form
configuration-related options.
• Configuration-related options are not functioning options in get, list and delete,
meaning they will be ignored under these commands even provided.
• The label prefixing configuration-related options indicate the type of notification
destination this option is used for. When creating a new notification template with
certain destination type (controlled by --notification-type option), all non-default
related configuration-related options must be provided.
• When modifying an existing notification template, not every configuration-related option
has to be provided(but encryped fields must, even you are not changing it!). But if this
modification modifies destination type, all non-default related configuration-related
options must be provided.
• --notification-configuration option provides a json file specifying the configuration
details. All other configuration-related options will be ignored if
`–notification-configuration`` is provided.
Detailed Example
# Create a notification template in isolation.
tower-cli notification_template create --name foo --description bar --notification-type slack --channels a --channels b --token hey --organization Default
# Create a notification template under an existing job template.
tower-cli notification_template create --name foo --description bar --notification-type slack --channels a --channels b --token hey --job-template 5 --organization Default
# Get exactly one notification template.
tower-cli notification_template get --name foo
# Get a list of notification templates under certain criteria.
tower-cli notification_template list --notification-type irc
# Modify an existing notification.
tower-cli notification_template modify --description foo --token hi 17
# Delete an existing notification template.
tower-cli notification_template delete --name foo
# Associate a job template with an existing notification template.
tower-cli job_template associate_notification_template --job-template 5 --notification-template 3
# Disassociate a job template with an existing notification template.
tower-cli job_template disassociate_notification_template --job-template 5 --notification-template 3
Role Management
Introduction - What Roles Are
Starting with Ansible Tower 3.0, roles are the objects used to manage permissions to
various resources within Tower. Each role represents:
• A type of permission like “use”, “update”, or “admin”
• A resource that this permission applies to, like an inventory or credential
This is “Role Based Access Control” or RBAC. Each role may have several users associated
with it, where each of the users gains the specified type of permission. Teams may also be
associated with a role, in which case all users who are members of the team receive the
specified type of permission.
Managing Roles with tower-cli
To see the commands available for roles, see tower-cli roles. Within a specific command,
get the help text with tower-cli roles list --help.
The arguments for all role commands follow the same pattern, although not all arguments
are mandatory for all commands. The structure follows the following pattern:
tower-cli role <action> --type <choice> --user/team <name/pk> --resource <name/pk>
Roles do not have the typical CRUD operations that control other resources through
tower-cli. Roles can not be deleted or created on their own, because they are tied to the
resource that they reference. The next section covers what the possible actions are.
Basic Operations
The primary use case for roles is adding or removing users and teams from roles. In the
following example, a user is added to the project “use” role.
tower-cli role grant --type use --user test_user --project test_project
In the above command “test_user” is the username of a user to receive the new permission,
“test_project” is the name of the project they are receiving permission for, and “use” is
the type of permission they are receiving. Specifically, this allows test_user to use
test_project in a job template.
In a similar fashion, to remove the user from that role:
tower-cli role revoke --type use --user test_user --project test_project
To list the roles on that project:
tower-cli role list --project test_project
Detailed Example
The following commands will create an inventory and user and demonstrate the different
role commands on them.
# Create the inventory and list its roles
tower-cli inventory create --name 'test_inventory' --organization 'Default'
tower-cli role list --inventory 'test_inventory'
tower-cli role get --type 'use' --inventory 'test_inventory'
# Create a user, give access to the inventory and take it away
tower-cli user create --username 'test_user' --password 'pa$$' --email 'user@example.com'
tower-cli role grant --type 'use' --user 'test_user' --inventory 'test_inventory'
tower-cli role list --user 'test_user' --type 'use'
tower-cli role revoke --type 'use' --user 'test_user' --inventory 'test_inventory'
# Create a team, give access to the inventory and take it away
tower-cli team create --name 'test_team' --organization 'Default'
tower-cli role grant --type 'use' --team 'test_team' --inventory 'test_inventory'
tower-cli role list --team 'test_team' --type 'use'
tower-cli role revoke --type 'use' --team 'test_team' --inventory 'test_inventory'
Organization and Team Roles
For assigning users to teams and organizations, include the team or organization flag, and
it will be acted on as the resource. Note that teams can be either the resource or the
role grantee, depending of whether the --team or the --target-team flag is used.
The following example appoints test_user to the member role of a team and of an
organization.
tower-cli role grant --user 'test_user' ---target-team 'test_team' --type 'member'
tower-cli role grant --organization 'Default' --user 'test_user' --type 'member'
These commands are redundant with the tower-cli organization and team associate and
disassociate commands.
Survey Management
This feature is added in v3.1.0, and v3.1.3 or higher, at least, is recommended.
get help: tower-cli job_template survey --help
View a Survey
The name of the job template is known (“survey jt” in this example), and the survey
definition is desired.
tower-cli job_template survey --name="survey jt"
Example output, this is the survey spec:
{
"description": "",
"spec": [
{
"required": true,
"min": null,
"default": "v3.1.3",
"max": null,
"question_description": "enter a version of tower-cli to install",
"choices": "v3.0.0\nv3.0.1\nv3.0.2\nv3.1.0\nv3.1.1\nv3.1.2\nv3.1.3",
"new_question": true,
"variable": "version",
"question_name": "Tower-cli version",
"type": "multiplechoice"
},
{
"required": true,
"min": null,
"default": "click\ncolorama\nrequests\nsix\nPyYAML",
"max": null,
"question_description": "which package requirements would you like to install/check",
"choices": "click\ncolorama\nrequests\nsix\nPyYAML",
"new_question": true,
"variable": "packages",
"question_name": "Package requirements",
"type": "multiselect"
}
],
"name": ""
}
Save a survey
Use the job template modify command to do this. In order to create a functional survey you
must do two things:
• Save the survey spec - use the --survey-spec option
• Enable the survey - use the --survey-enabled option
Example of enabling the survey on a job template:
tower-cli job_template modify --name="hello world infinity" --survey-enabled=true
The --survey-spec option can get the spec from a file by prepending the @ character. If
this character is not used, it is assumed that you are giving the JSON data in-line.
Copy a survey to another template
The following example saves a survey spec to a file, and then uploads that survey spec to
another job template.
# Save the survey spec to file in local directory
tower-cli job_template survey --name="survey jt" > s.json
# Upload that survey to another job template
tower-cli job_template modify --name="another jt" --survey-spec=@s.json --survey-enabled=true
The next example using one line to do the same thing on the command line.
tower-cli job_template modify --name="another jt" --survey-spec="$(tower-cli job_template survey --name='survey jt')" --survey-enabled=true
Workflows
Workflows can also have surveys and follow the same pattern. Example:
tower-cli workflow survey --name="workflow with survey"
Workflow Management
These docs show how to populate an example workflow in Tower and how to automate the
creation or copying of workflows.
Normal CRUD
Workflows and workflow nodes can be managed as normal tower-cli resources.
Workflow Creation
Create an empty workflow:
tower-cli workflow create --name="workflow1" --organization="Default" --description="example description"
Check the existing workflows with the standard list or get commands.
tower-cli workflow list --description-on
Node Creation
Create nodes inside the workflow These all become “root” nodes and will spawn jobs on
workflow launch without any dependencies on other nodes. These commands create 2 root
nodes.
tower-cli node create -W workflow1 --job-template="Hello World"
tower-cli node create -W workflow1 --job-template="Hello World"
List the nodes inside of the workflow
tower-cli node list -W workflow1
Node Association
From the list command, you can find the ids of nodes you want to link
assocate_success_node will cause the 2nd node to run on success of the first node. The
following command causes node 2 to run on the event of successful completion of node 1.
tower-cli node assocate_success_node 1 2
This operation is only possible when node 2 is a root node. See the Tower documentation
for the limitations on the types of node connections allowed.
Auto-creation of the success node, only knowing the parent node id:
tower-cli node assocate_success_node 8 --job-template="Hello world"
Corresponding disassociate commands are also available. Disassociating a node from another
node will make it a root node.
Node Network Bulk Management
To print out a YAML representation of the nodes of a workflow, you can use the following
command. JSON format is also allowed.
tower-cli workflow schema workflow1
Here, “workflow1” is the name of the workflow.
Creating/updating a Schema Definition
To bulk-create or buld-update a workflow node network, use the workflow schema command.
The schema is JSON or YAML content, and can be passed in the CLI argument, or pointed to a
file. The schema is passed as a second positional argument, where the first argument
references the workflow.
tower-cli workflow schema workflow2 @schema.yml
The schema can be provided without using a file:
tower-cli workflow schema workflow2 '[{"job_template": "Hello world"}]'
The Schema definition defines the hierarchy structure that connects the nodes. Names, as
well as other valid parameters for node creation, are acceptable inside of the node’s
entry inside the schema definition.
Links must be declared as a list under a key that starts with “success”, “failure”, or
“always”. The following is an example of a valid schema definition.
Example schema.yml file:
- job_template: Hello world
failure:
- inventory_source: AWS servers (AWS servers - 42)
success:
- project: Ansible Examples
always:
- job_template: Echo variable
success:
- job_template: Scan localhost
This style may be useful to apply in a script to create a workflow network with a
tower-cli command after the constituent resources like the job templates and projects were
created by preceding tower-cli commands.
Differences with Machine Formatted Schemas
After writing a workflow schema, you may notice differences in how tower-cli subsequently
echos the schema definition back to you. The following is what tower-cli might return
after writing the above example.
- failure_nodes:
- inventory_source: 42
job_template: 45
success_nodes:
- always_nodes:
- job_template: 55
success_nodes:
- job_template: 44
project: 40
Note that the root node data starts with “failure_nodes”, instead of the name of the job
template. This will not impact functionality, and manually changing the order will not
impact functionality either.
Although this format is harder to read, it does the same thing as the previous schema. The
ability to both echo and create schemas can be used to copy the contents of one workflow
to another.
As an example, consider 2 workflows. The first has a name “workflow1”, and has its node
network populated. The second is named “workflow2” and is empty. The following commands
will copy the structure from the first to the second.
tower-cli workflow schema workflow1 > schema.yml
tower-cli workflow schema workflow2 @schema.yml
Idempotence
The workflow schema feature populates the workflow node network based on the hierarchy
structure. Before creating each node, it attempts to find an existing node with the
specified properties in that location in the tree, and will not create a new node if it
exists. Also, if an existing node has no correspondence in the schema, the entire sub-tree
based on that node will be deleted.
Thus, after running the schema command, the resulting workflow topology will always be
exactly the same as what is specified in the given schema file. To continue with the
previous example, subsequent invocations of:
tower-cli workflow schema workflow2 @schema.yml
tower-cli workflow schema workflow2 @schema.yml
should not change the network of workflow2, since schema.yml file itself remains
unchanged. However
tower-cli workflow schema workflow2 @new_schema.yml
will modify topology of workflow2 to exactly the same as what is specified in
new_schema.yml.
Launching Workflow Jobs
Use the workflow_job resource to launch workflow jobs. This supports the use of
extra_vars, which can contain answers to survey questions. The --monitor and --wait flag
are available to poll the server until workflow job reaches a completed status. The
--monitor option will print rolling updates of the jobs that ran as part of the workflow.
Here is an example of using those features:
tower-cli workflow_job launch -W "echo Hello World" -e a=1 --monitor
Example Commands
Examples here are intended to give concrete examples of how the CLI can be used in an
automated way. It can also help with testing or the defining of feature requests.
Expect the setup script to take up to 2 minutes to run. Most of this time is waiting for
the project source control to sync the examples from github to the tower server.
Setup
You should have a version of tower running and configured in the CLI in order to run any
scripts or commands here. With your specific data, that can done by the following
commands:
$ tower-cli config host tower.example.com
$ tower-cli config username leeroyjenkins
$ tower-cli config password myPassw0rd
Jobs demonstrated in the script do not connect to another machine, and do not require
valid machine credentials, so tower-cli config information should be all the unique
information necessary.
Create Fake Data
You may want to reference the fake data creator for examples on how to create different
types of resources.
If you want to run the script, which auto-populates your Tower server with a small set of
fake data, run the following:
# Populate the server with fake data and run test jobs
$ cd docs/source/cli_ref/examples/
$ source fake_data_creator.sh
Cleaning Up
The teardown script removes all of the objects that the CLI can easily remove. This is not
a perfect cleanup, but it performs well enough to get the system ready to run the fake
data creator script again.
# Delete the data that was created (with some exceptions)
$ source fake_data_teardown.sh
Warnings
It is strongly suggested that you only run these scripts on testing versions of an Ansible
Tower host in order to avoid unintended naming conflicts.
Python Module Use Example
This bash script example borrows fake data elements from the tower populator script. The
tower_populator script provides an example of how to use the tower-cli python modules.
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.
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 │ Description │
│ │ Default │ │
├───────────────┼──────────────────────────┼──────────────────────────┤
│color │ Boolean/’true’ │ Whether to use colored │
│ │ │ output for highlighting │
│ │ │ or not. │
├───────────────┼──────────────────────────┼──────────────────────────┤
│format │ String with options │ Output format. The │
│ │ (‘human’, ‘json’, │ “human” format is │
│ │ ‘yaml’)/’human’ │ intended for 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. No │
│ │ │ longer supported in │
│ │ │ Tower 3.3 and above │
└───────────────┴──────────────────────────┴──────────────────────────┘
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.
• environment: Values from magic environment variables.
• runtime: keyworded arguments 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.
API Reference Table of Contents
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 will
time out.
• interval (float) – Polling interval to refresh content from Tower.
• outfile (file) – Alternative file than stdout to write job stdout
to.
• **kwargs – Keyword arguments used to look up job resource object to
monitor if pk is not provided.
Returns
A dictionary combining the JSON output of the finished job resource
object, as well as two extra fields: “changed”, a flag indicating if
the job resource object is finished as expected; “id”, an integer
which is the primary key of the job resource object being monitored.
Return type
dict
Raises
• 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
┌─────────────────┬──────────────────────────────────┬──────────────┬───────────┬────────┬────────────┬──────────┐
└─────────────────┴──────────────────────────────────┴──────────────┴───────────┴────────┴────────────┴──────────┘
├─────────────────┼──────────────────────────────────┼──────────────┼───────────┼────────┼────────────┼──────────┤
├─────────────────┼──────────────────────────────────┼──────────────┼───────────┼────────┼────────────┼──────────┤
├─────────────────┼──────────────────────────────────┼──────────────┼───────────┼────────┼────────────┼──────────┤
├─────────────────┼──────────────────────────────────┼──────────────┼───────────┼────────┼────────────┼──────────┤
├─────────────────┼──────────────────────────────────┼──────────────┼───────────┼────────┼────────────┼──────────┤
└─────────────────┴──────────────────────────────────┴──────────────┴───────────┴────────┴────────────┴──────────┘
API Specification
class tower_cli.resources.credential_type.Resource
A resource for credential types.
copy(pk=None, new_name=None, **kwargs)
Copy an object.
Parameters
• pk (int) – Primary key of the resource object to be copied
• new_name – The new name to give the resource if deep copying via
the API
• **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 arguments 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 arguments 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 │ The user │ False │ False │ True │ False │
│ │ user │ field. │ │ │ │ │
├────────────────┼──────────────────┼─────────────────┼───────────┼────────┼────────────┼──────────┤
│team │ Resource │ The team │ False │ False │ True │ False │
│ │ team │ 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, new_name=None, **kwargs)
Copy an object.
Parameters
• pk (int) – Primary key of the resource object to be copied
• new_name – The new name to give the resource if deep copying via
the API
• **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 arguments 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 arguments 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 │ False │ False │ True │ True │
│ │ inventory │ 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, new_name=None, **kwargs)
Copy an object.
Parameters
• pk (int) – Primary key of the resource object to be copied
• new_name – The new name to give the resource if deep copying via
the API
• **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 arguments 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 arguments 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 │ False │ False │ True │ True │
│ │ inventory │ 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(**kwargs)
Associate a group with this host.
Parameters
• host (str) – Primary key or name of the host to associate to.
• group (str) – Primary key or name of the group to be associated.
Returns
Dictionary of only one key “changed”, which indicates whether the
associate succeeded.
Return type
dict
copy(pk=None, new_name=None, **kwargs)
Copy an object.
Parameters
• pk (int) – Primary key of the resource object to be copied
• new_name – The new name to give the resource if deep copying via
the API
• **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 arguments 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(**kwargs)
Disassociate a group with this host.
Parameters
• host (str) – Primary key or name of the host to disassociate to.
• group (str) – Primary key or name of the group to be disassociated.
Returns
Dictionary of only one key “changed”, which indicates whether the
disassociate 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 arguments 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 │ False │ False │ True │ True │
│ │ │ to 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, new_name=None, **kwargs)
Copy an object.
Parameters
• pk (int) – Primary key of the resource object to be copied
• new_name – The new name to give the resource if deep copying via
the API
• **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 arguments 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 arguments 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, new_name=None, **kwargs)
Copy an object.
Parameters
• pk (int) – Primary key of the resource object to be copied
• new_name – The new name to give the resource if deep copying via
the API
• **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 arguments 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 arguments 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 will
time out.
• interval (float) – Polling interval to refresh content from Tower.
• outfile (file) – Alternative file than stdout to write job stdout
to.
• **kwargs – Keyword arguments used to look up job resource object to
monitor if pk is not provided.
Returns
A dictionary combining the JSON output of the finished job resource
object, as well as two extra fields: “changed”, a flag indicating if
the job resource object is finished as expected; “id”, an integer
which is the primary key of the job resource object being monitored.
Return type
dict
Raises
• 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 will
time out.
• interval (float) – Polling interval to refresh content from Tower.
• outfile (file) – Alternative file than stdout to write job stdout
to.
• **kwargs – Keyword arguments used to look up job resource object to
monitor if pk is not provided.
Returns
A dictionary combining the JSON output of the finished job resource
object, as well as two extra fields: “changed”, a flag indicating if
the job resource object is finished as expected; “id”, an integer
which is the primary key of the job resource object being monitored.
Return type
dict
Raises
• 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(**kwargs)
Associate an ig 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
associate 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, new_name=None, **kwargs)
Copy an object.
Parameters
• pk (int) – Primary key of the resource object to be copied
• new_name – The new name to give the resource if deep copying via
the API
• **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 arguments 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(**kwargs)
Disassociate an ig with this inventory.
Parameters
• inventory (str) – Primary key or name of the inventory to
disassociate to.
• instance_group (str) – Primary key or name of the instance_group to
be disassociated.
Returns
Dictionary of only one key “changed”, which indicates whether the
disassociate 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 arguments 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
┌─────────────────────────┬───────────────┬────────────────────┬───────────┬────────┬────────────┬──────────┐
├─────────────────────────┼───────────────┼────────────────────┼───────────┼────────┼────────────┼──────────┤
├─────────────────────────┼───────────────┼────────────────────┼───────────┼────────┼────────────┼──────────┤
├─────────────────────────┼───────────────┼────────────────────┼───────────┼────────┼────────────┼──────────┤
├─────────────────────────┼───────────────┼────────────────────┼───────────┼────────┼────────────┼──────────┤
├─────────────────────────┼───────────────┼────────────────────┼───────────┼────────┼────────────┼──────────┤
├─────────────────────────┼───────────────┼────────────────────┼───────────┼────────┼────────────┼──────────┤
├─────────────────────────┼───────────────┼────────────────────┼───────────┼────────┼────────────┼──────────┤
├─────────────────────────┼───────────────┼────────────────────┼───────────┼────────┼────────────┼──────────┤
├─────────────────────────┼───────────────┼────────────────────┼───────────┼────────┼────────────┼──────────┤
├─────────────────────────┼───────────────┼────────────────────┼───────────┼────────┼────────────┼──────────┤
├─────────────────────────┼───────────────┼────────────────────┼───────────┼────────┼────────────┼──────────┤
├─────────────────────────┼───────────────┼────────────────────┼───────────┼────────┼────────────┼──────────┤
├─────────────────────────┼───────────────┼────────────────────┼───────────┼────────┼────────────┼──────────┤
├─────────────────────────┼───────────────┼────────────────────┼───────────┼────────┼────────────┼──────────┤
└─────────────────────────┴───────────────┴────────────────────┴───────────┴────────┴────────────┴──────────┘
├─────────────────────────┼───────────────┼────────────────────┼───────────┼────────┼────────────┼──────────┤
├─────────────────────────┼───────────────┼────────────────────┼───────────┼────────┼────────────┼──────────┤
├─────────────────────────┼───────────────┼────────────────────┼───────────┼────────┼────────────┼──────────┤
├─────────────────────────┼───────────────┼────────────────────┼───────────┼────────┼────────────┼──────────┤
├─────────────────────────┼───────────────┼────────────────────┼───────────┼────────┼────────────┼──────────┤
├─────────────────────────┼───────────────┼────────────────────┼───────────┼────────┼────────────┼──────────┤
├─────────────────────────┼───────────────┼────────────────────┼───────────┼────────┼────────────┼──────────┤
├─────────────────────────┼───────────────┼────────────────────┼───────────┼────────┼────────────┼──────────┤
├─────────────────────────┼───────────────┼────────────────────┼───────────┼────────┼────────────┼──────────┤
├─────────────────────────┼───────────────┼────────────────────┼───────────┼────────┼────────────┼──────────┤
├─────────────────────────┼───────────────┼────────────────────┼───────────┼────────┼────────────┼──────────┤
├─────────────────────────┼───────────────┼────────────────────┼───────────┼────────┼────────────┼──────────┤
├─────────────────────────┼───────────────┼────────────────────┼───────────┼────────┼────────────┼──────────┤
├─────────────────────────┼───────────────┼────────────────────┼───────────┼────────┼────────────┼──────────┤
├─────────────────────────┼───────────────┼────────────────────┼───────────┼────────┼────────────┼──────────┤
├─────────────────────────┼───────────────┼────────────────────┼───────────┼────────┼────────────┼──────────┤
├─────────────────────────┼───────────────┼────────────────────┼───────────┼────────┼────────────┼──────────┤
└─────────────────────────┴───────────────┴────────────────────┴───────────┴────────┴────────────┴──────────┘
└─────────────────────────┴───────────────┴────────────────────┴───────────┴────────┴────────────┴──────────┘
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(**kwargs)
Associate an ig 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
associate succeeded.
Return type
dict
associate_label(**kwargs)
Associate a label with this job_template.
Parameters
• job_template (str) – Primary key or name of the job_template to
associate to.
• label (str) – Primary key or name of the label to be associated.
Returns
Dictionary of only one key “changed”, which indicates whether the
associate 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, new_name=None, **kwargs)
Copy an object.
Parameters
• pk (int) – Primary key of the resource object to be copied
• new_name – The new name to give the resource if deep copying via
the API
• **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 arguments 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(**kwargs)
Disassociate an ig with this job_template.
Parameters
• job_template (str) – Primary key or name of the job_template to
disassociate to.
• instance_group (str) – Primary key or name of the instance_group to
be disassociated.
Returns
Dictionary of only one key “changed”, which indicates whether the
disassociate succeeded.
Return type
dict
disassociate_label(**kwargs)
Disassociate a label with this job_template.
Parameters
• job_template (str) – Primary key or name of the job_template to
disassociate to.
• label (str) – Primary key or name of the label to be disassociated.
Returns
Dictionary of only one key “changed”, which indicates whether the
disassociate 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 arguments 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 │ True │ 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. │ │ │ │ │
└────────────────┴──────────────┴─────────────────┴───────────┴────────┴────────────┴──────────┘
API Specification
class tower_cli.resources.job.Resource(*args, **kwargs)
A resource for jobs.
This resource has ordinary list and get methods, but it does not have create or
modify. Instead of being created, a job is launched.
cancel(pk=None, fail_if_not_running=False, **kwargs)
Cancel a currently running job.
Parameters
• pk (int) – Primary key of the job resource to restart.
• fail_if_not_running (bool) – Flag that if set, raise exception if
the job resource cannot be canceled.
• **kwargs – Keyword arguments used to look up job resource object to
restart if pk is not provided.
Returns
A dictionary of two keys: “status”, which is “canceled”, and
“changed”, which indicates if the job resource has been successfully
canceled.
Return type
dict
Raises tower_cli.exceptions.TowerCLIError – When the job resource cannot be
canceled and fail_if_not_running flag is on.
delete(pk=None, fail_on_missing=False, **kwargs)
Remove the given object.
Parameters
• pk (int) – Primary key of the resource to be deleted.
• fail_on_missing (bool) – Flag that if set, the object’s not being
found is considered a failure; otherwise, a success with no change
is reported.
• **kwargs – Keyword arguments used to look up resource object to
delete if pk is not provided.
Returns
dictionary of only one field “changed”, which is a flag indicating
whether the specified resource is successfully deleted.
Return type
dict
get(pk=None, **kwargs)
Retrieve one and exactly one object.
Parameters
• pk (int) – Primary key of the resource to be read. Tower CLI will
only attempt to read that object if pk is provided (not None).
• **kwargs – Keyword arguments used to look up resource object to
retrieve if pk is not provided.
Returns
loaded JSON of the retrieved resource object.
Return type
dict
launch(job_template=None, monitor=False, wait=False, timeout=None, no_input=True,
extra_vars=None, **kwargs)
Launch a new job based on a job template.
Parameters
• job_template (str) – Primary key or name of the job template to
launch new job.
• monitor (bool) – Flag that if set, immediately calls monitor on the
newly launched job rather than exiting with a success.
• wait (bool) – Flag that if set, monitor the status of the job, but
do not print while job is in progress.
• timeout (int) – If provided with monitor flag set, this attempt
will time out after the given number of seconds.
• no_input (bool) – Flag that if set, suppress any requests for
input.
• extra_vars (array of strings) – yaml formatted texts that contains
extra variables to pass on.
• diff_mode (bool) – Specify diff mode for job template to run.
• limit (str) – Specify host limit for job template to run.
• tags (str) – Specify tagged actions in the playbook to run.
• skip_tags (str) – Specify tagged actions in the playbook to omit.
• job_type (str) – Specify job type for job template to run.
• verbosity (int) – Specify verbosity of the playbook run.
• inventory (str) – Specify machine credential for job template to
run.
• credential (str) – Specify machine credential for job template to
run.
Returns
Result of subsequent monitor call if monitor flag is on; Result of
subsequent wait call if wait flag is on; Result of subsequent status
call if none of the two flags are on.
Return type
dict
list(all_pages=False, **kwargs)
Retrieve a list of objects.
Parameters
• all_pages (bool) – Flag that if set, collect all pages of content
from the API when returning results.
• page (int) – The page to show. Ignored if all_pages is set.
• query (list) – Contains 2-tuples used as query parameters to filter
resulting resource objects.
• **kwargs – Keyword arguments list of available fields used for
searching resource objects.
Returns
A JSON object containing details of all resource objects returned by
Tower backend.
Return type
dict
monitor(pk, parent_pk=None, timeout=None, interval=0.5, outfile=<_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 will
time out.
• interval (float) – Polling interval to refresh content from Tower.
• outfile (file) – Alternative file than stdout to write job stdout
to.
• **kwargs – Keyword arguments used to look up job resource object to
monitor if pk is not provided.
Returns
A dictionary combining the JSON output of the finished job resource
object, as well as two extra fields: “changed”, a flag indicating if
the job resource object is finished as expected; “id”, an integer
which is the primary key of the job resource object being monitored.
Return type
dict
Raises
• 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
stdout(pk, start_line=None, end_line=None, **kwargs)
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.
Label
Description
This resource is used for managing label resources in Tower.
Fields Table
┌─────────────┬──────────────┬──────────────┬───────────┬────────┬────────────┬──────────┐
│name │ type │ help_text │ read_only │ unique │ filterable │ required │
├─────────────┼──────────────┼──────────────┼───────────┼────────┼────────────┼──────────┤
│name │ String │ The name │ False │ True │ True │ True │
│ │ │ field. │ │ │ │ │
├─────────────┼──────────────┼──────────────┼───────────┼────────┼────────────┼──────────┤
│organization │ Resource │ The │ False │ False │ True │ True │
│ │ organization │ organization │ │ │ │ │
│ │ │ field. │ │ │ │ │
└─────────────┴──────────────┴──────────────┴───────────┴────────┴────────────┴──────────┘
API Specification
class tower_cli.resources.label.Resource
A resource for labels.
copy(pk=None, new_name=None, **kwargs)
Copy an object.
Parameters
• pk (int) – Primary key of the resource object to be copied
• new_name – The new name to give the resource if deep copying via
the API
• **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 label.
Parameters
• job_template (str) – Primary key or name of the job template for
the created label to associate to.
• 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 arguments 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.TowerCLIError – When the label already exists
and fail_on_found flag is on.
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 arguments 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
Workflow Node
Description
This resource is used for managing workflow job template nodes in Tower. It can also used
for building workflow topology by associating/disassociating nodes.
Fields Table
┌──────────────────────┬────────────┬───────────────────────┬───────────┬────────┬────────────┬──────────┐
├──────────────────────┼────────────┼───────────────────────┼───────────┼────────┼────────────┼──────────┤
├──────────────────────┼────────────┼───────────────────────┼───────────┼────────┼────────────┼──────────┤
├──────────────────────┼────────────┼───────────────────────┼───────────┼────────┼────────────┼──────────┤
├──────────────────────┼────────────┼───────────────────────┼───────────┼────────┼────────────┼──────────┤
├──────────────────────┼────────────┼───────────────────────┼───────────┼────────┼────────────┼──────────┤
├──────────────────────┼────────────┼───────────────────────┼───────────┼────────┼────────────┼──────────┤
├──────────────────────┼────────────┼───────────────────────┼───────────┼────────┼────────────┼──────────┤
├──────────────────────┼────────────┼───────────────────────┼───────────┼────────┼────────────┼──────────┤
└──────────────────────┴────────────┴───────────────────────┴───────────┴────────┴────────────┴──────────┘
API Specification
class tower_cli.resources.node.Resource
A resource for workflow nodes.
associate_always_node(parent, child=None, **kwargs)
Add a node to always run after the parent is finished.
Parameters
• parent (int) – Primary key of parent node to associate always node
to.
• child (int) – Primary key of child node to be associated.
• **kwargs – Fields used to create child node if child is not
provided.
Returns
Dictionary of only one key “changed”, which indicates whether the
association succeeded.
Return type
dict
associate_failure_node(parent, child=None, **kwargs)
Add a node to run on failure.
Parameters
• parent (int) – Primary key of parent node to associate failure node
to.
• child (int) – Primary key of child node to be associated.
• **kwargs – Fields used to create child node if child is not
provided.
Returns
Dictionary of only one key “changed”, which indicates whether the
association succeeded.
Return type
dict
associate_success_node(parent, child=None, **kwargs)
Add a node to run on success.
Parameters
• parent (int) – Primary key of parent node to associate success node
to.
• child (int) – Primary key of child node to be associated.
• **kwargs – Fields used to create child node if child is not
provided.
Returns
Dictionary of only one key “changed”, which indicates whether the
association succeeded.
Return type
dict
copy(pk=None, new_name=None, **kwargs)
Copy an object.
Parameters
• pk (int) – Primary key of the resource object to be copied
• new_name – The new name to give the resource if deep copying via
the API
• **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 arguments 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_always_node(parent, child)
Remove an always node link.
Parameters
• parent (int) – Primary key of parent node to disassociate always
node from.
• child (int) – Primary key of child node to be disassociated.
Returns
Dictionary of only one key “changed”, which indicates whether the
disassociation succeeded.
Return type
dict
disassociate_failure_node(parent, child)
Remove a failure node link.
Parameters
• parent (int) – Primary key of parent node to disassociate failure
node from.
• child (int) – Primary key of child node to be disassociated.
Returns
Dictionary of only one key “changed”, which indicates whether the
disassociation succeeded.
Return type
dict
disassociate_success_node(parent, child)
Remove success node.
Parameters
• parent (int) – Primary key of parent node to disassociate success
node from.
• child (int) – Primary key of child node to be disassociated.
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 arguments 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
Notification Template
Description
This resource is used for managing notification templates in Tower. Note most resource
fields, like username and host are effective based on notification_type. For example,
providing service_key when creating an email notification template is not effective as it
will be discarded.
Fields Table
┌───────────────────────────┬──────────────────────────────────────────────────┬────────────────────────────────────┬───────────┬────────┬────────────┬──────────┐
├───────────────────────────┼──────────────────────────────────────────────────┼────────────────────────────────────┼───────────┼────────┼────────────┼──────────┤
├───────────────────────────┼──────────────────────────────────────────────────┼────────────────────────────────────┼───────────┼────────┼────────────┼──────────┤
├───────────────────────────┼──────────────────────────────────────────────────┼────────────────────────────────────┼───────────┼────────┼────────────┼──────────┤
├───────────────────────────┼──────────────────────────────────────────────────┼────────────────────────────────────┼───────────┼────────┼────────────┼──────────┤
├───────────────────────────┼──────────────────────────────────────────────────┼────────────────────────────────────┼───────────┼────────┼────────────┼──────────┤
├───────────────────────────┼──────────────────────────────────────────────────┼────────────────────────────────────┼───────────┼────────┼────────────┼──────────┤
├───────────────────────────┼──────────────────────────────────────────────────┼────────────────────────────────────┼───────────┼────────┼────────────┼──────────┤
├───────────────────────────┼──────────────────────────────────────────────────┼────────────────────────────────────┼───────────┼────────┼────────────┼──────────┤
├───────────────────────────┼──────────────────────────────────────────────────┼────────────────────────────────────┼───────────┼────────┼────────────┼──────────┤
├───────────────────────────┼──────────────────────────────────────────────────┼────────────────────────────────────┼───────────┼────────┼────────────┼──────────┤
├───────────────────────────┼──────────────────────────────────────────────────┼────────────────────────────────────┼───────────┼────────┼────────────┼──────────┤
├───────────────────────────┼──────────────────────────────────────────────────┼────────────────────────────────────┼───────────┼────────┼────────────┼──────────┤
├───────────────────────────┼──────────────────────────────────────────────────┼────────────────────────────────────┼───────────┼────────┼────────────┼──────────┤
├───────────────────────────┼──────────────────────────────────────────────────┼────────────────────────────────────┼───────────┼────────┼────────────┼──────────┤
├───────────────────────────┼──────────────────────────────────────────────────┼────────────────────────────────────┼───────────┼────────┼────────────┼──────────┤
├───────────────────────────┼──────────────────────────────────────────────────┼────────────────────────────────────┼───────────┼────────┼────────────┼──────────┤
├───────────────────────────┼──────────────────────────────────────────────────┼────────────────────────────────────┼───────────┼────────┼────────────┼──────────┤
├───────────────────────────┼──────────────────────────────────────────────────┼────────────────────────────────────┼───────────┼────────┼────────────┼──────────┤
├───────────────────────────┼──────────────────────────────────────────────────┼────────────────────────────────────┼───────────┼────────┼────────────┼──────────┤
├───────────────────────────┼──────────────────────────────────────────────────┼────────────────────────────────────┼───────────┼────────┼────────────┼──────────┤
├───────────────────────────┼──────────────────────────────────────────────────┼────────────────────────────────────┼───────────┼────────┼────────────┼──────────┤
├───────────────────────────┼──────────────────────────────────────────────────┼────────────────────────────────────┼───────────┼────────┼────────────┼──────────┤
├───────────────────────────┼──────────────────────────────────────────────────┼────────────────────────────────────┼───────────┼────────┼────────────┼──────────┤
├───────────────────────────┼──────────────────────────────────────────────────┼────────────────────────────────────┼───────────┼────────┼────────────┼──────────┤
├───────────────────────────┼──────────────────────────────────────────────────┼────────────────────────────────────┼───────────┼────────┼────────────┼──────────┤
├───────────────────────────┼──────────────────────────────────────────────────┼────────────────────────────────────┼───────────┼────────┼────────────┼──────────┤
├───────────────────────────┼──────────────────────────────────────────────────┼────────────────────────────────────┼───────────┼────────┼────────────┼──────────┤
├───────────────────────────┼──────────────────────────────────────────────────┼────────────────────────────────────┼───────────┼────────┼────────────┼──────────┤
├───────────────────────────┼──────────────────────────────────────────────────┼────────────────────────────────────┼───────────┼────────┼────────────┼──────────┤
├───────────────────────────┼──────────────────────────────────────────────────┼────────────────────────────────────┼───────────┼────────┼────────────┼──────────┤
├───────────────────────────┼──────────────────────────────────────────────────┼────────────────────────────────────┼───────────┼────────┼────────────┼──────────┤
├───────────────────────────┼──────────────────────────────────────────────────┼────────────────────────────────────┼───────────┼────────┼────────────┼──────────┤
└───────────────────────────┴──────────────────────────────────────────────────┴────────────────────────────────────┴───────────┴────────┴────────────┴──────────┘
API Specification
class tower_cli.resources.notification_template.Resource
A resource for notification templates.
copy(pk=None, new_name=None, **kwargs)
Copy an object.
Parameters
• pk (int) – Primary key of the resource object to be copied
• new_name – The new name to give the resource if deep copying via
the API
• **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 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 arguments 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 arguments 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
Organization
Description
This resource is used for managing organization resources in Tower. It can also perform
some associations/disassociations.
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. │ │ │ │ │
└────────────┴────────┴──────────────┴───────────┴────────┴────────────┴──────────┘
API Specification
class tower_cli.resources.organization.Resource
associate(**kwargs)
Associate a user with this organization.
Parameters
• organization (str) – Primary key or name of the organization to
associate to.
• user (str) – Primary key or name of the user to be associated.
Returns
Dictionary of only one key “changed”, which indicates whether the
associate succeeded.
Return type
dict
associate_admin(**kwargs)
Associate an admin with this organization.
Parameters
• organization (str) – Primary key or name of the organization to
associate to.
• user (str) – Primary key or name of the user to be associated.
Returns
Dictionary of only one key “changed”, which indicates whether the
associate succeeded.
Return type
dict
associate_ig(**kwargs)
Associate an ig with this organization.
Parameters
• organization (str) – Primary key or name of the organization 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
associate succeeded.
Return type
dict
copy(pk=None, new_name=None, **kwargs)
Copy an object.
Parameters
• pk (int) – Primary key of the resource object to be copied
• new_name – The new name to give the resource if deep copying via
the API
• **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 arguments 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(**kwargs)
Disassociate a user with this organization.
Parameters
• organization (str) – Primary key or name of the organization to
disassociate to.
• user (str) – Primary key or name of the user to be disassociated.
Returns
Dictionary of only one key “changed”, which indicates whether the
disassociate succeeded.
Return type
dict
disassociate_admin(**kwargs)
Disassociate an admin with this organization.
Parameters
• organization (str) – Primary key or name of the organization to
disassociate to.
• user (str) – Primary key or name of the user to be disassociated.
Returns
Dictionary of only one key “changed”, which indicates whether the
disassociate succeeded.
Return type
dict
disassociate_ig(**kwargs)
Disassociate an ig with this organization.
Parameters
• organization (str) – Primary key or name of the organization to
disassociate to.
• instance_group (str) – Primary key or name of the instance_group to
be disassociated.
Returns
Dictionary of only one key “changed”, which indicates whether the
disassociate 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 arguments 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
Project
Description
This resource is used for managing and executing projects via Tower. Note project updates
are triggered via update method.
Fields Table
┌─────────────────────────┬───────────────┬──────────────────────────┬───────────┬────────┬────────────┬──────────┐
├─────────────────────────┼───────────────┼──────────────────────────┼───────────┼────────┼────────────┼──────────┤
├─────────────────────────┼───────────────┼──────────────────────────┼───────────┼────────┼────────────┼──────────┤
└─────────────────────────┴───────────────┴──────────────────────────┴───────────┴────────┴────────────┴──────────┘
├─────────────────────────┼───────────────┼──────────────────────────┼───────────┼────────┼────────────┼──────────┤
├─────────────────────────┼───────────────┼──────────────────────────┼───────────┼────────┼────────────┼──────────┤
├─────────────────────────┼───────────────┼──────────────────────────┼───────────┼────────┼────────────┼──────────┤
├─────────────────────────┼───────────────┼──────────────────────────┼───────────┼────────┼────────────┼──────────┤
├─────────────────────────┼───────────────┼──────────────────────────┼───────────┼────────┼────────────┼──────────┤
├─────────────────────────┼───────────────┼──────────────────────────┼───────────┼────────┼────────────┼──────────┤
├─────────────────────────┼───────────────┼──────────────────────────┼───────────┼────────┼────────────┼──────────┤
├─────────────────────────┼───────────────┼──────────────────────────┼───────────┼────────┼────────────┼──────────┤
├─────────────────────────┼───────────────┼──────────────────────────┼───────────┼────────┼────────────┼──────────┤
├─────────────────────────┼───────────────┼──────────────────────────┼───────────┼────────┼────────────┼──────────┤
└─────────────────────────┴───────────────┴──────────────────────────┴───────────┴────────┴────────────┴──────────┘
API Specification
class tower_cli.resources.project.Resource(*args, **kwargs)
A resource for projects.
copy(pk=None, new_name=None, **kwargs)
Copy an object.
Parameters
• pk (int) – Primary key of the resource object to be copied
• new_name – The new name to give the resource if deep copying via
the API
• **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(organization=None, monitor=False, wait=False, timeout=None,
fail_on_found=False, force_on_exists=False, **kwargs)
Create a project and, if related flags are set, monitor or wait the
triggered initial project update.
Parameters
• monitor (bool) – Flag that if set, immediately calls monitor on the
newly triggered project update rather than exiting with a success.
• wait (bool) – Flag that if set, monitor the status of the triggered
project update, but do not print while it is in progress.
• timeout (bool) – If provided with monitor flag set, this attempt
will time out after the given number of seconds.
• 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 arguments 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 project.
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 arguments 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 will
time out.
• interval (float) – Polling interval to refresh content from Tower.
• outfile (file) – Alternative file than stdout to write job stdout
to.
• **kwargs – Keyword arguments used to look up job resource object to
monitor if pk is not provided.
Returns
A dictionary combining the JSON output of the finished job resource
object, as well as two extra fields: “changed”, a flag indicating if
the job resource object is finished as expected; “id”, an integer
which is the primary key of the job resource object being monitored.
Return type
dict
Raises
• tower_cli.exceptions.Timeout – When monitor time reaches time out.
• tower_cli.exceptions.JobFailure – When the job being monitored runs
into failure.
status(pk=None, detail=False, **kwargs)
Print the status of the most recent update.
Parameters
• pk (int) – Primary key of the resource to retrieve status from.
• detail (bool) – Flag that if set, return the full JSON of the job
resource rather than a status summary.
• **kwargs – Keyword arguments used to look up resource object to
retrieve status from if pk is not provided.
Returns
full loaded JSON of the specified unified job if detail flag is on;
trimed JSON containing only “elapsed”, “failed” and “status” fields
of the unified job if detail flag is off.
Return type
dict
stdout(pk, start_line=None, end_line=None, **kwargs)
update(pk=None, create_on_missing=False, monitor=False, wait=False, timeout=None,
name=None, organization=None)
Update the given project.
Parameters
• pk (int) – Primary key of the project to be updated.
• monitor (bool) – Flag that if set, immediately calls monitor on the
newly launched project update rather than exiting with a success.
• wait (bool) – Flag that if set, monitor the status of the project
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.
• name (str) – Name of the project to be updated if pk is not set.
• organization (str) – Primary key or name of the organization the
project to be updated belonging to if pk is not set.
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.CannotStartJob – When the project 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.
Project Update
Description
This resource is used for managing and executing project updates via Tower.
Fields Table
┌────────────────┬──────────────────────────────────────────────────────────────────────────┬─────────────────┬───────────┬────────┬────────────┬──────────┐
├────────────────┼──────────────────────────────────────────────────────────────────────────┼─────────────────┼───────────┼────────┼────────────┼──────────┤
├────────────────┼──────────────────────────────────────────────────────────────────────────┼─────────────────┼───────────┼────────┼────────────┼──────────┤
├────────────────┼──────────────────────────────────────────────────────────────────────────┼─────────────────┼───────────┼────────┼────────────┼──────────┤
├────────────────┼──────────────────────────────────────────────────────────────────────────┼─────────────────┼───────────┼────────┼────────────┼──────────┤
├────────────────┼──────────────────────────────────────────────────────────────────────────┼─────────────────┼───────────┼────────┼────────────┼──────────┤
├────────────────┼──────────────────────────────────────────────────────────────────────────┼─────────────────┼───────────┼────────┼────────────┼──────────┤
├────────────────┼──────────────────────────────────────────────────────────────────────────┼─────────────────┼───────────┼────────┼────────────┼──────────┤
├────────────────┼──────────────────────────────────────────────────────────────────────────┼─────────────────┼───────────┼────────┼────────────┼──────────┤
├────────────────┼──────────────────────────────────────────────────────────────────────────┼─────────────────┼───────────┼────────┼────────────┼──────────┤
└────────────────┴──────────────────────────────────────────────────────────────────────────┴─────────────────┴───────────┴────────┴────────────┴──────────┘
API Specification
class tower_cli.resources.project_update.Resource(*args, **kwargs)
A resource for project 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 will
time out.
• interval (float) – Polling interval to refresh content from Tower.
• outfile (file) – Alternative file than stdout to write job stdout
to.
• **kwargs – Keyword arguments used to look up job resource object to
monitor if pk is not provided.
Returns
A dictionary combining the JSON output of the finished job resource
object, as well as two extra fields: “changed”, a flag indicating if
the job resource object is finished as expected; “id”, an integer
which is the primary key of the job resource object being monitored.
Return type
dict
Raises
• 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.
RBAC Role
Description
This resource is used for managing RBAC roles in Tower. More importantly, it can be used
for granting roles to and revoke roles from a user or team.
Fields Table
┌──────────────┬────────────────────────────────────────────────────┬───────────────┬───────────┬────────┬────────────┬──────────┐
├──────────────┼────────────────────────────────────────────────────┼───────────────┼───────────┼────────┼────────────┼──────────┤
├──────────────┼────────────────────────────────────────────────────┼───────────────┼───────────┼────────┼────────────┼──────────┤
├──────────────┼────────────────────────────────────────────────────┼───────────────┼───────────┼────────┼────────────┼──────────┤
├──────────────┼────────────────────────────────────────────────────┼───────────────┼───────────┼────────┼────────────┼──────────┤
├──────────────┼────────────────────────────────────────────────────┼───────────────┼───────────┼────────┼────────────┼──────────┤
└──────────────┴────────────────────────────────────────────────────┴───────────────┴───────────┴────────┴────────────┴──────────┘
├──────────────┼────────────────────────────────────────────────────┼───────────────┼───────────┼────────┼────────────┼──────────┤
├──────────────┼────────────────────────────────────────────────────┼───────────────┼───────────┼────────┼────────────┼──────────┤
├──────────────┼────────────────────────────────────────────────────┼───────────────┼───────────┼────────┼────────────┼──────────┤
├──────────────┼────────────────────────────────────────────────────┼───────────────┼───────────┼────────┼────────────┼──────────┤
├──────────────┼────────────────────────────────────────────────────┼───────────────┼───────────┼────────┼────────────┼──────────┤
├──────────────┼────────────────────────────────────────────────────┼───────────────┼───────────┼────────┼────────────┼──────────┤
└──────────────┴────────────────────────────────────────────────────┴───────────────┴───────────┴────────┴────────────┴──────────┘
API Specification
class tower_cli.resources.role.Resource
A resource for managing roles.
This resource has ordinary list and get methods, but it roles can not be created or
edited, instead, they are automatically generated along with the connected
resource.
copy(pk=None, new_name=None, **kwargs)
Copy an object.
Parameters
• pk (int) – Primary key of the resource object to be copied
• new_name – The new name to give the resource if deep copying via
the API
• **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
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
grant(fail_on_found=False, **kwargs)
Add a user or a team to a role. Required information: * Type of the role. *
Resource of the role, inventory, credential, or any other. * A user or a
team to add to the role.
Parameters
• fail_on_found (bool) – Flag that if set, the operation fails if a
user/team already has the role.
• **kwargs – The user to be associated and the role to associate.
Returns
parsed JSON of role grant.
Return type
dict
list(**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
revoke(fail_on_found=False, **kwargs)
Remove a user or a team from a role. Required information: * Type of the
role. * Resource of the role, inventory, credential, or any other. * A
user or a team to add to the role.
Parameters
• fail_on_found (bool) – Flag that if set, the operation fails if a
user/team dose not have the role.
• **kwargs – The user to be disassociated and the role to
disassociate.
Returns
parsed JSON of role revoke.
Return type
dict
Schedule
Description
This resource is used for managing schedule resources in Tower.
Fields Table
┌─────────────────────┬──────────────────┬──────────────────┬───────────┬────────┬────────────┬──────────┐
├─────────────────────┼──────────────────┼──────────────────┼───────────┼────────┼────────────┼──────────┤
├─────────────────────┼──────────────────┼──────────────────┼───────────┼────────┼────────────┼──────────┤
├─────────────────────┼──────────────────┼──────────────────┼───────────┼────────┼────────────┼──────────┤
├─────────────────────┼──────────────────┼──────────────────┼───────────┼────────┼────────────┼──────────┤
├─────────────────────┼──────────────────┼──────────────────┼───────────┼────────┼────────────┼──────────┤
├─────────────────────┼──────────────────┼──────────────────┼───────────┼────────┼────────────┼──────────┤
├─────────────────────┼──────────────────┼──────────────────┼───────────┼────────┼────────────┼──────────┤
├─────────────────────┼──────────────────┼──────────────────┼───────────┼────────┼────────────┼──────────┤
├─────────────────────┼──────────────────┼──────────────────┼───────────┼────────┼────────────┼──────────┤
└─────────────────────┴──────────────────┴──────────────────┴───────────┴────────┴────────────┴──────────┘
API Specification
class tower_cli.resources.schedule.Resource
A resource for schedules.
copy(pk=None, new_name=None, **kwargs)
Copy an object.
Parameters
• pk (int) – Primary key of the resource object to be copied
• new_name – The new name to give the resource if deep copying via
the API
• **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(*args, **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 arguments 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, *args, **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, *args, **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(*args, **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, *args, **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 arguments 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
Tower Configuration
Description
This resource is used for managing tower configurations in Tower.
Fields Table
┌──────┬───────────┬──────────────┬───────────┬────────┬────────────┬──────────┐
│name │ type │ help_text │ read_only │ unique │ filterable │ required │
├──────┼───────────┼──────────────┼───────────┼────────┼────────────┼──────────┤
│value │ variables │ The value │ False │ False │ True │ True │
│ │ │ field. │ │ │ │ │
└──────┴───────────┴──────────────┴───────────┴────────┴────────────┴──────────┘
API Specification
class tower_cli.resources.setting.Resource
A resource for Tower configurations.
copy(pk=None, new_name=None, **kwargs)
Copy an object.
Parameters
• pk (int) – Primary key of the resource object to be copied
• new_name – The new name to give the resource if deep copying via
the API
• **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
get(pk)
Return one and exactly one Tower setting.
Parameters
pk (int) – Primary key of the Tower setting to retrieve
Returns
loaded JSON of the retrieved Tower setting object.
Return type
dict
Raises tower_cli.exceptions.NotFound – When no specified Tower setting
exists.
list(**kwargs)
Retrieve a list of Tower settings.
Parameters
• category (str) – The category slug in which to look up indevidual
settings.
• **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(setting, value)
Modify an already existing Tower setting.
Parameters
• setting (str) – The name of the Tower setting to be modified.
• value (str) – The new value of the Tower setting.
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
Team
Description
This resource is used for managing teams and their users in Tower.
Fields Table
┌─────────────┬──────────────┬──────────────┬───────────┬────────┬────────────┬──────────┐
│name │ type │ help_text │ read_only │ unique │ filterable │ required │
├─────────────┼──────────────┼──────────────┼───────────┼────────┼────────────┼──────────┤
│name │ String │ The name │ False │ True │ True │ True │
│ │ │ field. │ │ │ │ │
├─────────────┼──────────────┼──────────────┼───────────┼────────┼────────────┼──────────┤
│organization │ Resource │ The │ False │ False │ True │ True │
│ │ organization │ organization │ │ │ │ │
│ │ │ field. │ │ │ │ │
├─────────────┼──────────────┼──────────────┼───────────┼────────┼────────────┼──────────┤
│description │ String │ The │ False │ False │ True │ False │
│ │ │ description │ │ │ │ │
│ │ │ field. │ │ │ │ │
└─────────────┴──────────────┴──────────────┴───────────┴────────┴────────────┴──────────┘
API Specification
class tower_cli.resources.team.Resource
A resource for teams.
associate(**kwargs)
Associate a user with this team.
Parameters
• team (str) – Primary key or name of the team to associate to.
• user (str) – Primary key or name of the user to be associated.
Returns
Dictionary of only one key “changed”, which indicates whether the
associate succeeded.
Return type
dict
copy(pk=None, new_name=None, **kwargs)
Copy an object.
Parameters
• pk (int) – Primary key of the resource object to be copied
• new_name – The new name to give the resource if deep copying via
the API
• **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 arguments 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(**kwargs)
Disassociate a user with this team.
Parameters
• team (str) – Primary key or name of the team to disassociate to.
• user (str) – Primary key or name of the user to be disassociated.
Returns
Dictionary of only one key “changed”, which indicates whether the
disassociate 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 arguments 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
User
Description
This resource is used for managing users in Tower.
Fields Table
┌──────────────────┬────────┬───────────────────┬───────────┬────────┬────────────┬──────────┐
│name │ type │ help_text │ read_only │ unique │ filterable │ required │
├──────────────────┼────────┼───────────────────┼───────────┼────────┼────────────┼──────────┤
│username │ String │ The username │ False │ True │ True │ True │
│ │ │ field. │ │ │ │ │
├──────────────────┼────────┼───────────────────┼───────────┼────────┼────────────┼──────────┤
│password │ String │ The password │ False │ False │ True │ False │
│ │ │ field. │ │ │ │ │
├──────────────────┼────────┼───────────────────┼───────────┼────────┼────────────┼──────────┤
│email │ String │ The email │ False │ True │ True │ True │
│ │ │ field. │ │ │ │ │
├──────────────────┼────────┼───────────────────┼───────────┼────────┼────────────┼──────────┤
│first_name │ String │ The │ False │ False │ True │ False │
│ │ │ first_name │ │ │ │ │
│ │ │ field. │ │ │ │ │
├──────────────────┼────────┼───────────────────┼───────────┼────────┼────────────┼──────────┤
│last_name │ String │ The │ False │ False │ True │ False │
│ │ │ last_name │ │ │ │ │
│ │ │ field. │ │ │ │ │
├──────────────────┼────────┼───────────────────┼───────────┼────────┼────────────┼──────────┤
│is_superuser │ bool │ The │ False │ False │ True │ False │
│ │ │ is_superuser │ │ │ │ │
│ │ │ field. │ │ │ │ │
├──────────────────┼────────┼───────────────────┼───────────┼────────┼────────────┼──────────┤
│is_system_auditor │ bool │ The │ False │ False │ True │ False │
│ │ │ is_system_auditor │ │ │ │ │
│ │ │ field. │ │ │ │ │
└──────────────────┴────────┴───────────────────┴───────────┴────────┴────────────┴──────────┘
API Specification
class tower_cli.resources.user.Resource
A resource for users.
copy(pk=None, new_name=None, **kwargs)
Copy an object.
Parameters
• pk (int) – Primary key of the resource object to be copied
• new_name – The new name to give the resource if deep copying via
the API
• **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 arguments 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 arguments 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
Workflow Job
Description
This resource is used for managing workflow jobs and launching workflow job templates via
Tower.
Fields Table
─────────────────────────────────────────────────────────────────────────────────────────────────────────
name type help_text read_only unique filterable required
─────────────────────────────────────────────────────────────────────────────────────────────────────────
workflow_job_template Resource The False False True True
workflow workflow_job_template
field.
─────────────────────────────────────────────────────────────────────────────────────────────────────────
extra_vars variables The extra_vars field. False False True False
─────────────────────────────────────────────────────────────────────────────────────────────────────────
created String The created field. False False True False
─────────────────────────────────────────────────────────────────────────────────────────────────────────
status String The status field. False False True False
┌──────────────────────┬───────────┬───────────────────────┬───────────┬────────┬────────────┬──────────┐
│ API Specification │ │ │ │ │ │ │
--
AUTHOR
Alan Rominger, Luke Sneeringer, Aaron Tan
COPYRIGHT
2019, Ansible by Red Hat
Oct 19, 2019 TOWER_CLI(1)