Documentation

10. Introduction to tower-cli

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.

Note

The tower-cli software is an open source project currently under development and, until a complete implementation occurs, only implements a subset of Tower’s features.

10.1. License

While Tower is commercially licensed software, tower-cli is an open source project. Specifically, this project is licensed under the Apache 2.0 license. Pull requests, contributions, and tickets filed in GitHub are warmly welcomed.

10.2. Capabilities

tower-cli sends commands to the Tower API. It is capable of retrieving, creating, modifying, and deleting most objects 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

10.3. Installation

tower-cli is available as a package on PyPI.

The preferred way to install is through pip:

$ pip install ansible-tower-cli

The main branch of this project may also be consumed directly from source.

For more information on tower-cli, refer to the project page at: https://github.com/ansible/tower-cli/

10.4. Configuration

tower-cli can edit its own configuration or users can directly edit the configuration file, allowing configuration to be set in multiple ways.

10.4.1. Set configuration with tower-cli config

The preferred way to set configuration is with the tower-cli config command.

$ tower-cli config key value

By issuing the tower-cli config command without arguments, you can view a full list of configuration options and where they are set. The default behavior allows environment variables to override your tower-cli.cfg settings, but they will not override configuration values that are passed in on the command line at runtime. The available environment variables and their corresponding Tower configuration keys are as follows:

  • 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

You will generally need to set at least three configuration options–host, username, and password–which correspond to the location of your Ansible Tower instance and your credentials to authenticate to Tower.

$ tower-cli config host tower.example.com
$ tower-cli config username leeroyjenkins
$ tower-cli config password myPassw0rd

10.4.2. Write to the config files directly

The configuration file can also be edited directly. A configuration file is a simple file with keys and values, separated by : or =:

host: tower.example.com
username: admin
password: p4ssw0rd

10.4.3. File Locations

The order of precedence for configuration file locations is as follows, from least to greatest:

  • internal defaults

  • /etc/tower/tower_cli.cfg (written using tower-cli config --global)

  • ~/.tower_cli.cfg (written using tower-cli config)

  • run-time parameters

10.4.4. Usage

tower-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 (use 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.

Examples of actions and resources include (but are not limited to):

10.4.4.1. User Actions

# 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 protected]

# 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

10.4.4.2. Job Actions

# Launch a job.
$ tower-cli job launch --job-template=144

# Monitor a job.
$ tower-cli job monitor 95

10.4.4.3. Group Actions

# Get a list of groups.
$ tower-cli group list

# Sync a group by the groupID.
$ tower-cli group sync $groupID

When in doubt, check the help for more options:

$ tower-cli # help
$ tower-cli user --help # resource specific help
$ tower-cli user create --help # command specific help

10.4.4.4. Workflow Actions

Starting with Tower 3.1.0 and Tower-CLI 3.1.0, workflow networks can be managed from Tower-CLI either by normal CRUD actions or by using a YAML file that defines the workflow network.

# Print out the schema for a workflow
$ tower-cli workflow schema workflow_name

# Create the network defined in file "schema.yml"
$ tower-cli workflow schema workflow_name @schema.yml

The following is an example of what a schema might look like.

- 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

For more details, see the tower-cli workflow doc at https://github.com/ansible/tower-cli/blob/master/docs/WORKFLOWS.md

10.4.5. Specify extra variables

There are a number of ways to pass extra variables to the Tower server when launching a job:

  • Pass data in a file using the flag --extra-vars="@filename.yml"

  • Include yaml data at runtime with the flag --extra-vars="var: value"

  • A command line editor automatically pops up when the job template is marked to prompt on launch

  • If the job template has extra variables, these are not over-ridden

These methods can also be combined. For instance, if you give the flag multiple times on the command line, specifying a file in addition to manually giving extra variables, these two sources are combined and sent to the Tower server.

# Launch a job with extra variables from filename.yml, and also a=5
$ tower-cli job launch --job-template=1 --extra-vars="a=5 b=3" \
                                        --extra-vars="@filename.yml"

# Create a job template with that same set of extra variables
$ tower-cli job_template create --name=test_job_template --project=1 \
                                --inventory=1 --playbook=helloworld.yml \
                                --machine-credential=1 --extra-vars="a=5 b=3" \
                                --extra-vars="@filename.yml"

You may not combine multiple sources when modifying a job template. Whitespace can be used in strings like --extra-vars="a='white space'", and list-valued parameters can be sent as JSON or YAML, but not key=value pairs. For instance, --extra-vars="a: [1, 2, 3, 4, 5]" sends the parameter "a" with that list as its value.

Note

Additional strict extra_vars validation was added in Ansible Tower 3.0.0. extra_vars passed to the job launch API are only honored if one of the following is true:

  • They correspond to variables in an enabled survey

  • ask_variables_on_launch is set to True

10.4.6. SSL warnings

By default, tower-cli raises an error if the SSL certificate of the Tower server cannot be verified. To allow unverified SSL connections, set the config variable, verify_ssl = false. To allow it for a single command to override verify_ssl if set to true, add the --insecure flag:

# Disable insecure connection warnings permanently
$ tower-cli config verify_ssl false

# Disable insecure connection warnings for just this command
$ tower-cli job_template list --insecure