## File: README.md

[](https://github.com/ansible/awx/actions/workflows/ci.yml) [](https://codecov.io/github/ansible/awx) [](https://docs.ansible.com/projects/ansible/latest/community/code_of_conduct.html) [](https://github.com/ansible/awx/blob/devel/LICENSE.md) [](https://forum.ansible.com/tag/awx)
[](https://chat.ansible.im/#/welcome) [](https://forum.ansible.com)



> [!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](https://forum.ansible.com/) and - more specifically - see the various communications on the matter:
>
> * [Blog: Upcoming Changes to the AWX Project](https://www.ansible.com/blog/upcoming-changes-to-the-awx-project/)
> * [Streamlining AWX Releases](https://forum.ansible.com/t/streamlining-awx-releases/6894) Primary update
> * [Refactoring AWX into a Pluggable, Service-Oriented Architecture](https://forum.ansible.com/t/refactoring-awx-into-a-pluggable-service-oriented-architecture/7404)
> * [Upcoming changes to AWX Operator installation methods](https://forum.ansible.com/t/upcoming-changes-to-awx-operator-installation-methods/7598)
> * [AWX UI and credential types transitioning to the new pluggable architecture](https://forum.ansible.com/t/awx-ui-and-credential-types-transitioning-to-the-new-pluggable-architecture/8027)

AWX provides a web-based user interface, REST API, and task engine built on top of [Ansible](https://github.com/ansible/ansible). It is one of the upstream projects for [Red Hat Ansible Automation Platform](https://www.ansible.com/products/automation-platform).

To install AWX, please view the [Install guide](./INSTALL.md).

To learn more about using AWX, view the [AWX docs site](https://docs.ansible.com/projects/awx/en/latest/).

The AWX Project Frequently Asked Questions can be found [here](https://www.ansible.com/awx-project-faq).

The AWX logos and branding assets are covered by [our trademark guidelines](https://github.com/ansible/awx-logos/blob/master/TRADEMARKS.md).

Contributing
------------

- Refer to the [Contributing guide](./CONTRIBUTING.md) 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](./DCO_1_1.md)
- 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](https://forum.ansible.com/tag/awx). 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
----------------

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](./ISSUES.md).

Code of Conduct
---------------

We require all of our community members and contributors to adhere to the [Ansible code of conduct](https://docs.ansible.com/projects/ansible/latest/community/code_of_conduct.html). If you have questions or need assistance, please reach out to our community team at [codeofconduct@ansible.com](mailto:codeofconduct@ansible.com)

Get Involved
------------

We welcome your feedback and ideas via the [Ansible Forum](https://forum.ansible.com/tag/awx).

For a full list of all the ways to talk with the Ansible Community, see the [AWX Communication guide](https://docs.ansible.com/projects/awx/en/latest/contributor/communication.html).

---

## File: awx/ui/README.md

# Instruction to build ui directly from this directory

## Set src of the ui repo

### Via GIT

```bash
export UI_GIT_REPO=https://<git repo>
```

or

```bash
export UI_GIT_REPO=git@<git repo>
```

optionally set branch (default is main)

```bash
export UI_GIT_BRANCH=main
```

### Via symlink to existing clone

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

```bash
export UI_LOCAL = /path/to/your/ui
```

## Build

```bash
make ui
```

## Rebuild

```bash
make -B ui
```

## Clean

```bash
make clean/ui
```

---

## File: awx_collection/tools/README.md

## Collection tools

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

### Template Galaxy

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

```
make awx_collection_build
```

### Generate

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

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

# AWX Ansible Collection

[comment]: # (*******************************************************)
[comment]: # (*                                                     *)
[comment]: # (*             WARNING                                 *)
[comment]: # (*                                                     *)
[comment]: # (*  This file is templated and not to be               *)
[comment]: # (*  edited directly! Instead modify:                   *)
[comment]: # (*  tools/roles/template_galaxy/templates/README.md.j2 *)
[comment]: # (*                                                     *)
[comment]: # (*  Changes to the base README.md file are refreshed   *)
[comment]: # (*  upon build of the collection                       *)
[comment]: # (*******************************************************)

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](https://github.com/ansible/ansible/tree/stable-2.9/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

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

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

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](https://pypi.org/project/ansible-tower-cli/).
 - 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 `dict`s

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

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

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](https://github.com/ansible/awx/blob/devel/awx_collection/README.md#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

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

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

Usage Examples
==============

Verifying CLI Configuration
---------------------------

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

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

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

.. code:: bash

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

Importing an SSH Key
--------------------

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

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

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

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

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

To print results in YAML, specify ``-f yaml``:

.. code:: bash

    awx jobs list -f yaml

Human-Readable (Tabular) Formatting
-----------------------------------

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

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

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