awx Documentation

File: README.md Copy Chapter

[!CAUTION]
The last release of this repository was released on Jul 2, 2024.
Releases of this project are now paused during a large scale refactoring.
For more information, follow the Forum and - more specifically - see the various communications on the matter:

• Blog: Upcoming Changes to the AWX Project
• Streamlining AWX Releases Primary update
• Refactoring AWX into a Pluggable, Service-Oriented Architecture
• Upcoming changes to AWX Operator installation methods
• AWX UI and credential types transitioning to the new pluggable architecture

AWX provides a web-based user interface, REST API, and task engine built on top of Ansible. It is one of the upstream projects for Red Hat Ansible Automation Platform.

To install AWX, please view the Install guide.

To learn more about using AWX, view the AWX docs site.

The AWX Project Frequently Asked Questions can be found here.

The AWX logos and branding assets are covered by our trademark guidelines.

Contributing Copy Chapter

• Refer to the Contributing guide to get started developing, testing, and building AWX.
• All code submissions are made through pull requests against the devel branch.
• All contributors must use git commit --signoff for any commit to be merged and agree that usage of --signoff constitutes agreement with the terms of DCO 1.1
• Take care to make sure no merge commits are in the submission, and use git rebase vs. git merge for this reason.
• If submitting a large code change, it's a good idea to join discuss via the Ansible Forum. This helps everyone know what's going on, and it also helps save time and effort if the community decides some changes are needed.

Reporting Issues Copy Chapter

If you're experiencing a problem that you feel is a bug in AWX or have ideas for improving AWX, we encourage you to open an issue and share your feedback. But before opening a new issue, we ask that you please take a look at our Issues guide.

Code of Conduct Copy Chapter

We require all of our community members and contributors to adhere to the Ansible code of conduct. If you have questions or need assistance, please reach out to our community team at [email protected]

Get Involved Copy Chapter

We welcome your feedback and ideas via the Ansible Forum.

For a full list of all the ways to talk with the Ansible Community, see the AWX Communication guide.

File: awx/ui/README.md Copy Chapter

Instruction to build ui directly from this directory

Set src of the ui repo Copy Chapter

Via GIT Copy Section

export UI_GIT_REPO=https://<git repo>

or

export UI_GIT_REPO=git@<git repo>

optionally set branch (default is main)

export UI_GIT_BRANCH=main

Via symlink to existing clone Copy Section

NOTE: UI_LOCAL have higher precedence than UI_GIT_REPO, if UI_LOCAL is set, UI_GIT_REPO will be ignored.

export UI_LOCAL = /path/to/your/ui

Build Copy Chapter

make ui

Rebuild Copy Chapter

make -B ui

Clean Copy Chapter

make clean/ui

File: awx_collection/tools/README.md Copy Chapter

Collection tools Copy Chapter

Tools used for building, maintaining, and testing the collection.

Template Galaxy Copy Section

The template_galaxy.yml playbook ran as a pre-requisite for building the collection.

make awx_collection_build

Generate Copy Section

This will template resource modules (like group, for groups in inventory) from a boilerplate template.
It is intended as a tool for writing new modules or enforcing consistency.

Integration Testing Copy Section

These instructions assume you have ansible-core and the collection installed.
To install the collection in-place (to pick up any local changes to source)
the make symlink_collection will symlink the awx_collection/ folder to
the appropriate place under ~/.ansible/collections.

This is a shortcut for quick validation of tests that bypasses ansible-test.
To use this, you need the ~/.tower_cli.cfg config file populated,
which can be done via the deprecated tower-cli login or manually
writing it, where the format looks like:

[general]
host = https://localhost:8043/
verify_ssl = false
username = admin
password = password

TODO: adjust playbook to allow using environment variables as well.

To run some sample modules:

ansible-playbook -i localhost, awx_collection/tools/integration_testing.yml

To run just one module (the most common use case), use the -e test=<name>.

ansible-playbook -i localhost, awx_collection/tools/integration_testing.yml -e test=host

If you want to run all the tests, then you need to pass in the whole list.
This will take significant time and is not ideal from an error-handling perspective,
but this is a way to do it:

ansible-playbook -i localhost, awx_collection/tools/integration_testing.yml -e test=$(ls -1Am awx_collection/tests/integration/targets/ | tr -d '[:space:]')

Depending on the module, you may need special dependencies.
For instance, the rrule lookup plugins need pytz.
These will be satisfied if you install requirements in awx_collection/requirements.txt.

File: awx_collection/README.md Copy Chapter

AWX Ansible Collection

This Ansible collection allows for easy interaction with an AWX server via Ansible playbooks.

This source for this collection lives in the awx_collection folder inside of the
AWX GitHub repository.
The previous home for this collection was inside the folder lib/ansible/modules/web_infrastructure/ansible_tower in the Ansible repo,
as well as other places for the inventory plugin, module utils, and
doc fragment.

Building and Installing Copy Chapter

This collection templates the galaxy.yml file it uses.
Run make build_collection from the root folder of the AWX source tree.
This will create the tar.gz file inside the awx_collection folder
with the current AWX version, for example: awx_collection/awx-awx-9.2.0.tar.gz.

Installing the tar.gz involves no special instructions.

Running Copy Chapter

Non-deprecated modules in this collection have no Python requirements, but
may require the AWX CLI
in the future. The DOCUMENTATION for each module will report this.

You can specify authentication by host, username, and password.

These can be specified via (from highest to lowest precedence):

• direct module parameters
• environment variables (most useful when running against localhost)
• a config file path specified by the tower_config_file parameter
• a config file at ~/.tower_cli.cfg
• a config file at /etc/tower/tower_cli.cfg

Config file syntax looks like this:

[general]
host = https://localhost:8043
verify_ssl = true
username = foo
password = bar

Release and Upgrade Notes Copy Chapter

Notable releases of the awx.awx collection:

• 7.0.0 is intended to be identical to the content prior to the migration, aside from changes necessary to function as a collection.
• 11.0.0 has no non-deprecated modules that depend on the deprecated tower-cli PyPI.
• 19.2.1 large renaming purged "tower" names (like options and module names), adding redirects for old names
• 21.11.0 "tower" modules deprecated and symlinks removed.
• 25.0.0 "token" and "application" modules have been removed as oauth is no longer supported, use basic auth instead
• X.X.X added support of named URLs to all modules. Anywhere that previously accepted name or id can also support named URLs
• 0.0.1-devel is the version you should see if installing from source, which is intended for development and expected to be unstable.

The following notes are changes that may require changes to playbooks:

• The credential module no longer allows kind as a parameter; additionally, inputs must now be used with a variety of key/value parameters to go with it (e.g., become_method)

• The job_wait module no longer allows min_interval/ max_interval parameters; use interval instead

• The notification_template requires various notification configuration information to be listed as a dictionary under the notification_configuration parameter (e.g., use_ssl)

• In the inventory_source module, the source_project (when provided) lookup defaults to the specified organization in the same way the inventory is looked up

• The module tower_notification was renamed tower_notification_template. In ansible >= 2.10 there is a seamless redirect. Ansible 2.9 does not respect the redirect.

• When a project is created, it will wait for the update/sync to finish by default; this can be turned off with the wait parameter, if desired.

• Creating a "scan" type job template is no longer supported.

• Specifying a custom certificate via the TOWER_CERTIFICATE environment variable no longer works.

• Type changes of variable fields:

  • extra_vars in the tower_job_launch module worked with a list previously, but now only works with a dict type
  • extra_vars in the tower_workflow_job_template module worked with a string previously but now expects a dict
  • When the extra_vars parameter is used with the tower_job_launch module, the launch will fail unless ask_extra_vars or survey_enabled is explicitly set to True on the Job Template
  • The variables parameter in the tower_group, tower_host and tower_inventory modules now expects a dict type and no longer supports the use of @ syntax for a file

• Type changes of other types of fields:

  • inputs or injectors in the tower_credential_type module worked with a string previously but now expects a dict
  • schema in the tower_workflow_job_template module worked with a string previously but not expects a list of dicts

• tower_group used to also service inventory sources, but this functionality has been removed from this module; use tower_inventory_source instead.

• Specified tower_config file used to handle k=v pairs on a single line; this is no longer supported. Please use a file formatted as yaml, json or ini only.

• Some return values (e.g., credential_type) have been removed. Use of id is recommended.

• tower_job_template no longer supports the deprecated extra_vars_path parameter, please use extra_vars with the lookup plugin to replace this functionality.

• The notification_configuration parameter of tower_notification_template has changed from a string to a dict. Please use the lookup plugin to read an existing file into a dict.

• tower_credential no longer supports passing a file name to ssh_key_data.

• The HipChat notification_type has been removed and can no longer be created using the tower_notification_template module.

• Lookup plugins now always return a list, and if you want a scalar value use lookup as opposed to query

Running Unit Tests Copy Chapter

Tests to verify compatibility with the most recent AWX code are in awx_collection/test/awx.
These can be ran via the make test_collection command in the development container.

To run tests outside of the development container, or to run against
Ansible source, set up a dedicated virtual environment:

mkvirtualenv my_new_venv
# may need to replace psycopg3 with psycopg3-binary in requirements/requirements.txt
pip install -r requirements/requirements.txt -r requirements/requirements_dev.txt -r requirements/requirements_git.txt
make clean-api
pip install -e 
pip install -e .
pip install -e awxkit
py.test awx_collection/test/awx/

Running Integration Tests Copy Chapter

The integration tests require a virtualenv with ansible >= 2.9 and awxkit.
The collection must first be installed, which can be done using make install_collection.
You also need a configuration file, as described in the Running section.

How to run the tests:

# ansible-test must be run from the directory in which the collection is installed
cd ~/.ansible/collections/ansible_collections/awx/awx/
ansible-test integration

Licensing Copy Chapter

All content in this folder is licensed under the same license as Ansible,
which is the same as the license that applied before the split into an
independent collection.

File: awxkit/awxkit/cli/docs/source/authentication.rst Copy Chapter

.. _authentication:

Authentication

To authenticate to AWX, include your username and password in each command invocation as shown in the following examples:

.. code:: bash

CONTROLLER_USERNAME=alice CONTROLLER_PASSWORD=secret awx jobs list
awx --conf.username alice --conf.password secret jobs list

File: awxkit/awxkit/cli/docs/source/examples.rst Copy Chapter

Usage Examples

Verifying CLI Configuration Copy Chapter

To confirm that you've properly configured awx to point at the correct
AWX/|RHAT| host, and that your authentication credentials are correct, run:

.. code:: bash

awx config

.. note:: For help configuring authentication settings with the awx CLI, see :ref:authentication.

Printing the History of a Particular Job Copy Chapter

To print a table containing the recent history of any jobs named Example Job Template:

.. code:: bash

awx jobs list --all --name 'Example Job Template' \
    -f human --filter 'name,created,status'

Creating and Launching a Job Template Copy Chapter

Assuming you have an existing Inventory named Demo Inventory, here's how
you might set up a new project from a GitHub repository, and run (and monitor
the output of) a playbook from that repository:

.. code:: bash

awx projects create --wait \
    --organization 1 --name='Example Project' \
    --scm_type git --scm_url 'https://github.com/ansible/ansible-tower-samples' \
    -f human
awx job_templates create \
    --name='Example Job Template' --project 'Example Project' \
    --playbook hello_world.yml --inventory 'Demo Inventory' \
    -f human
awx job_templates launch 'Example Job Template' --monitor -f human

Updating a Job Template with Extra Vars Copy Chapter

.. code:: bash

awx job_templates modify 1 --extra_vars "@vars.yml"
awx job_templates modify 1 --extra_vars "@vars.json"

Importing an SSH Key Copy Chapter

.. code:: bash

awx credentials create --credential_type 'Machine' \
    --name 'My SSH Key' --user 'alice' \
    --inputs '{"username": "server-login", "ssh_key_data": "@~/.ssh/id_rsa"}'

Import/Export Copy Chapter

Intended to be similar to tower-cli send and tower-cli receive.

Exporting everything:

.. code:: bash

awx export

Exporting everything of some particular type or types:

.. code:: bash

awx export --users

Exporting a particular named resource:

.. code:: bash

awx export --users admin

Exporting a resource by id:

.. code:: bash

awx export --users 42

Importing a set of resources stored as a file:

.. code:: bash

awx import < resources.json

File: awxkit/awxkit/cli/docs/source/index.rst Copy Chapter

.. AWX CLI documentation master file, created by
sphinx-quickstart on Mon Jul 22 11:39:10 2019.
You can adapt this file completely to your liking, but it should at least
contain the root toctree directive.

AWX Command Line Interface

|prog| is the official command-line client for AWX and |RHAT|. 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 |RHAT|.

Potential uses include:

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

.. toctree::
:maxdepth: 3

usage
authentication
output
examples
reference

Indices and tables

• :ref:genindex
• :ref:modindex
• :ref:search

File: awxkit/awxkit/cli/docs/source/install.rst Copy Chapter

The preferred way to install the AWX CLI is through pip:

.. code:: bash

pip install "git+https://github.com/ansible/awx.git@$VERSION#egg=awxkit&subdirectory=awxkit"

...where $VERSION is the version of AWX you're running. To see a list of all available releases, visit: https://github.com/ansible/awx/releases

File: awxkit/awxkit/cli/docs/source/output.rst Copy Chapter

.. _formatting:

Output Formatting

By default, awx prints valid JSON for successful commands. The -f (or
--conf.format) global flag can be used to specify alternative output
formats.

YAML Formatting Copy Chapter

To print results in YAML, specify -f yaml:

.. code:: bash

awx jobs list -f yaml

Human-Readable (Tabular) Formatting Copy Chapter

|prog| also provides support for printing results in a human-readable
ASCII table format:

.. code:: bash

awx jobs list -f human
awx jobs list -f human --filter name,created,status
awx jobs list -f human --filter *

Custom Formatting with jq Copy Chapter

|prog| provides optional support for filtering results using the jq JSON
processor, but it requires an additional Python software dependency,
jq.

To use -f jq, you must install the optional dependency via pip install jq. Note that some platforms may require additional programs to
build jq from source (like libtool). See https://pypi.org/project/jq/ for instructions.

.. code:: bash

awx jobs list \
    -f jq --filter '.results[] | .name + " is " + .status'

For details on jq filtering usage, see the jq manual at https://stedolan.github.io/jq/

Colorized Output Copy Chapter

By default, |prog| prints colorized output using ANSI color codes. To disable
this functionality, specify --conf.color f or set the environment variable
CONTROLLER_COLOR=f.