Tower CLI Guide - PCC-IT International

AWX Command Line Interface

awx is the official command-line client for AWX and Red Hat Ansible Tower. It:

Uses naming and structure consistent with the AWX HTTP API
Provides consistent output formats with optional machine-parsable formats
To the extent possible, auto-detects API versions, available endpoints, and feature support across multiple versions of AWX and Red Hat Ansible Tower.

Potential uses include:

Configuring and launching jobs/playbooks
Checking on the status and output of job runs
Managing objects like organizations, users, teams, etc…

Basic Usage

Installation

On Red Hat Enterprise Linux 7, the AWX CLI can be installed via yum:

yum-config-manager --add-repo https://releases.ansible.com/ansible-tower/cli/ansible-tower-cli-el7.repo
yum install ansible-tower-cli

On CentOS 7, the AWX CLI can be installed via yum:

yum-config-manager --add-repo https://releases.ansible.com/ansible-tower/cli/ansible-tower-cli-centos7.repo
yum install ansible-tower-cli

On Red Hat Enterprise Linux 8, the AWX CLI can be installed via dnf:

dnf config-manager --add-repo https://releases.ansible.com/ansible-tower/cli/ansible-tower-cli-el8.repo
dnf install ansible-tower-cli

On CentOS 8, the AWX CLI can be installed via dnf:

dnf config-manager --add-repo https://releases.ansible.com/ansible-tower/cli/ansible-tower-cli-centos8.repo
dnf install ansible-tower-cli

On all other platforms, it can be installed via pip (python3 or python are required):

pip3 install --user https://releases.ansible.com/ansible-tower/cli/ansible-tower-cli-latest.tar.gz

Synopsis

awx commands follow a simple format:

awx []   []
awx --help

The resource is a type of object within AWX (a noun), such as users or organizations.

The action is the thing you want to do (a verb). Resources generally have a base set of actions (get, list, create, modify, and delete), and have options corresponding to fields on the object in AWX. Some resources have special actions, like job_templates launch.

Getting Started

Using awx requires some initial configuration. Here is a simple example for interacting with an AWX or Red Hat Ansible Tower server:

awx --conf.host https://awx.example.org \
    --conf.username joe --conf.password secret \
    --conf.insecure \
    users list

There are multiple ways to configure and authenticate with an AWX or Red Hat Ansible Tower server. For more details, see Authentication.

By default, awx prints valid JSON for successful commands. Certain commands (such as those for printing job stdout) print raw text and do not allow for custom formatting. For details on customizing awx’s output format, see Output Formatting.

Resources and Actions

To get a list of available resources:

awx --conf.host https://awx.example.org --help

To get a description of a specific resource, and list its available actions (and their arguments):

awx --conf.host https://awx.example.org users --help
awx --conf.host https://awx.example.org users create --help

Note

The list of resources and actions may vary based on context. For example, certain resources may not be available based on role-based access control (e.g., if you do not have permission to launch certain Job Templates, launch may not show up as an action for certain job_templates objects.

Global Options

awx accepts global options that control overall behavior. In addition to CLI flags, most global options have a corresponding environment variable that may be used to set the value. If both are provided, the command line option takes priority.

A few of the most important ones are:

-h, --help: Prints usage information for the awx tool
-v, --verbose: prints debug-level logs, including HTTP(s) requests made
-f, --conf.format: used to specify a custom output format (the default is json)
--conf.host, TOWER_HOST: the full URL of the AWX/Red Hat Ansible Tower host (i.e., https://my.awx.example.org)
-k, --conf.insecure, TOWER_VERIFY_SSL: allows insecure server connections when using SSL
--conf.username, TOWER_USERNAME: the AWX username to use for authentication
--conf.password, TOWER_PASSWORD: the AWX password to use for authentication
--conf.token, TOWER_OAUTH_TOKEN: an OAuth2.0 token to use for authentication

Authentication

Generating a Personal Access Token

The preferred mechanism for authenticating with AWX and Red Hat Ansible Tower is by generating and storing an OAuth2.0 token. Tokens can be scoped for read/write permissions, are easily revoked, and are more suited to third party tooling integration than session-based authentication.

awx provides a simple login command for generating a personal access token from your username and password.

TOWER_HOST=https://awx.example.org \
    TOWER_USERNAME= alice \
    TOWER_PASSWORD= secret \
    awx login

As a convenience, the awx login -f human command prints a shell-formatted token value:

export TOWER_OAUTH_TOKEN=6E5SXhld7AMOhpRveZsLJQsfs9VS8U

By ingesting this token, you can run subsequent CLI commands without having to specify your username and password each time:

export TOWER_HOST=https://awx.example.org
$(TOWER_USERNAME=alice TOWER_PASSWORD=secret awx login -f human)
awx config

Working with OAuth2.0 Applications

AWX and Red Hat Ansible Tower allow you to configure OAuth2.0 applications scoped to specific organizations. To generate an application token (instead of a personal access token), specify the Client ID and Client Secret generated when the application was created.

TOWER_USERNAME=alice TOWER_PASSWORD=secret awx login \
    --conf.client_id  --conf.client_secret 

OAuth2.0 Token Scoping

By default, tokens created with awx login are write-scoped. To generate a read-only token, specify --scope read:

TOWER_USERNAME=alice TOWER_PASSWORD=secret \
    awx login --conf.scope read

Session Authentication

If you do not want or need to generate a long-lived token, awx allows you to specify your username and password on every invocation:

TOWER_USERNAME=alice TOWER_PASSWORD=secret awx jobs list
awx --conf.username alice --conf.password secret jobs list

SIGN UP