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:

$ 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

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

Notes

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.

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.

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:

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:

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:

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:

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.

[general]
<configuration name 1> = <value 1>
<configuration name 2> = <value 2>
...

>>> 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.

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

API Specification

Credential Type

Description

This resource is used for managing credential type resources in Tower.

Fields Table

API Specification

Credential

Description

This resource is used for managing credential resources in Tower.

Fields Table

API Specification

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

API Specification

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

API Specification

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

API Specification

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

API Specification

Inventory Script

Description

This resource is used for managing inventory script resources in Tower.

Fields Table

API Specification

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

Inventory Update

Description

This resource is used for managing and executing inventory updates via Tower.

Fields Table

API Specification

Inventory

Description

This resource is used for managing inventory resources in Tower.

Fields Table

API Specification

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

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

API Specification

Label

Description

This resource is used for managing label resources in Tower.

Fields Table

API Specification

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

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

Organization

Description

This resource is used for managing organization resources in Tower. It can also perform some associations/disassociations.

Fields Table

API Specification