Playbook Pal

Ansible automatically configures computers and routers on a network. Administrators typically define the instructions to Ansible by manually editing text files. Red Hat offers Ansible Tower as a commercial web application for managing Ansible services. Tower simplifies system administration and configuration deployment, allowing you to launch Ansible playbooks and also providing user management and many useful statistics.

In August 2017, Red Hat placed the Ansible Tower source code under an Apache open source license and released it on GitHub [1] with the name of AWX. By placing the code in open source, Red Hat encourages the community to introduce improvements. New versions of AWX are expected to be released frequently; Red will take selected AWX versions and release them with long-term support under the Ansible Tower brand.

Red Hat explicitly does not recommend AWX for productive use. Whether you should choose Tower or AWX depends on your requirements: AWX is suitable primarily for evaluation and for smaller companies that have to pay meticulous attention to costs. Larger companies should continue to consider Ansible Tower, for which Red Hat provides comprehensive support. The only support for AWX is via IRC and the official mailing list.

Like Ansible Tower, AWX only helps the administrator to manage the systems. Administrators still need to create the playbooks with the actual configuration instructions manually. AWX also requires all playbooks to reside in a version control system. Currently, AWX can collect playbooks from Git, Mercurial, Subversion, and Red Hat Insights repositories. It is also possible to store the playbooks locally on the AWX computer. This, however, requires further work, in addition to Docker skills, and the developers do not support this procedure. If you do not yet store your playbooks in a version control system, you can use a Git repository by the AWX makers with a simple sample playbook for your first tests.

Installation

AWX is currently designed to run in a Docker container and thus in an isolated environment. Thankfully, the right container is created automatically during installation. At least for a test installation of AWX, you don't need any knowledge of Docker (this is also true of the rest of this article). The finished container with AWX can be served up either in a Docker environment or in an OpenShift cluster. Since commissioning via Docker is far quicker, I'll focus on the Docker option in this article.

To install AWX, you need Ansible 2.4 or higher, Docker, the docker-py Python module, GNU make, and Git. If your distribution only has an old Ansible version, as is the case with Ubuntu, you have to install Ansible manually. In Ubuntu, you can use the Ansible developer's repository for this purpose:

$ sudo apt-add-repository ppa:ansible/ansible
$ sudo apt-get update
$ sudo apt-get install ansible docker.io python-docker git make

In any case, make sure that the Docker daemon is running; in Ubuntu type:

sudo systemctl restart docker

Now download the source code of the current AWX version from GitHub and unzip the archive. Alternatively, you can clone the current state of development:

$ git clone https://github.com/ansible/awx.git

In any case, change to the installer subdirectory and open the inventory file in a text editor. Look for the line with dockerhub_version=latest at the beginning.

The latest setting means the latest version of AWX will run automatically. Behind dockerhub_version, you can also specify a specific AWX version, like dockerhub_version=1.0.1.

A web server that delivers the AWX user interface runs in the Docker container. This web server listens on port 80 by default. You can specify a different port by changing the port number in the host_port=80 line of the inventory file.

Configuring the Database

AWX parks its data in a PostgreSQL database. A suitable Docker container is automatically created during installation. By default, PostgreSQL stores the database contents in the /tmp/pgdocker directory on the host system. For your first tests with AWX, you can simply keep this default. However, since many distributions empty the /tmp directory on rebooting, you will want to choose a different location in production mode. To change the location, look for the line postgres_data_ dir= /tmp/pgdocker in the inventory file and change the directory, for example:

postgres_ data_ dir=/var/database/awx

Alternatively, AWX can also use an existing PostgreSQL database. Search for the following lines in the inventory file:

pg_username=awx
pg_password=awxpass
pg_database=awx
pg_port=5432

After pg_username= and pg_password=, replace the access information for the PostgreSQL database. pg_database= refers to the database name. pg_port= reveals the port where the PostgreSQL database can be accessed. Finally, add the line pg_hostname=postgresql. Replace postgresql with the hostname of the computer running the PostgreSQL database. The existence of the line pg_hostname is also a signal for AWX to use the PostgreSQL installation and not to set up a new one.

Docker experts can make further settings in the inventory file and, for example, run the Docker container on another system. The individual settings are documented in detail as comments in the inventory file. If in doubt, you should always leave the default settings as they are.

Commissioning

Now change to the installer subdirectory at the command line. The following command gives Ansible the order to start a Docker container with AWX:

$ sudo ansible-playbook -i inventory install.yml

The complete process takes a few minutes. As soon as you see the command line again, call sudo docker ps. This command should now list five containers and thus five isolated environments. The containers memcached, rabbitmq, and postgres run services of the same names, which AWX in turn uses for its purposes. The awx_web container contains the web server that delivers AWX. Its colleague awx_task performs some preparatory tasks. These tasks include, among other things, setting up the database. You cannot use AWX until all preparations have been completed. Check the progress with:

sudo docker logs -f awx_task

As long as lines beginning with Applying ... appear, preparation is still on-going.

You can then reach AWX in the browser, on the current system via the http://localhost address. If you have specified another port in inventory, you need to attach it accordingly. AWX will greet you with the login screen, where you can access AWX with a username of admin and password as the password.