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.

Reluctant Restart

The Docker daemon running in the background assumes the task of managing the containers. When installing AWX, Ansible set up the daemon so that it automatically boots the AWX containers when it starts. AWX is therefore available immediately after a restart of the computer – you only have to make sure that the Docker daemon starts when booting the system. Under Ubuntu, you can ensure the Docker daemon starts with:

sudo systemctl enable docker

Alternatively, start the daemon manually with sudo systemctl start docker.

In certain circumstances, the awx_task container will perform some tasks after a restart. During this time, you will only see an AWX is Upgrading message in the browser instead of the login screen. You can monitor the progress with:

sudo docker logs -f awx_task

just like you would during the installation. If you delete the directory with the database, or your distribution does, awx_task will automatically recreate the AWX database. If you have stored the database below /tmp/pgdocker, as suggested by default, and your distribution automatically discards the contents of /tmp after a restart, you will end up with a freshly installed AWX after every system start. If you happen to encounter an error while installing or configuring AWX, see the box entitled "Loop Fix."

Dashboard Overview

After logging in to the AWX user interface, you will be taken to the dashboard shown in Figure 1. AWX combines several individual actions to form jobs. The large graph in the middle shows how many of these jobs AWX executed recently. If the line unexpectedly rises or falls, a system may have started or terminated without you planning it. You can see which jobs AWX last executed in the box labeled Recently Run Jobs on the bottom right. A click in the upper-right corner on the heartbeat curve icon opens the Activity Stream.

This list shows all the individual actions performed in the past. This view is especially useful for troubleshooting. Click the icon again to return to the dashboard.

You are currently logged in as an all-powerful superuser who is allowed to tweak all the AWX bells and whistles. The first thing you will want to do is to change your password. To do so, click on the admin username in the upper right corner of the screen. Make sure that the Details button is enabled (and thus grayed). Then fill in the fields with your first and last name and your email address. Type your new password in Password and Confirm Password. In a production environment, you will also want to change your username in the Username field. (For the sake of simplicity, I will keep admin as the username for this article.) Press Save to save the changes.

On the left side of the page, you will find a gray bar with several symbols, which in turn lead to the various settings. A click on the hamburger symbol with the three dashes at the very top will fully extend the bar. Dashboard lets you return to the start page at any time.

Registering an Organization

AWX can manage the computers of several organizations or companies. To distinguish between the systems of different organizations in the user interface, you first need to tell AWX the names of the organizations. (Even if you are only managing the systems of one organization, you still have to provide an organization name.)

Click on Organizations in the main menu on the left-hand side of the page. By default AWX already knows an organization with the not totally creative name of Default. You can easily rename this default organization by clicking on the pencil icon (highlighted with the blue circle in Figure 2). Then change the name in the field and click Save. Add lets you add further organizations if required.

Creating an Inventory

Next, you need to tell AWX which computers to manage. AWX refers to these in more general terms as hosts. You need to make a note of all the hosts in an organization in an inventory. To create an inventory for your own organization, click on Inventories in the menu on the left. AWX has already created an inventory for you with the smart name Demo Inventory. You can simply ignore this and create a new inventory using Add. The Add Inventory form lets you configure settings for the new inventory (Figure 3). The inventory contains all the hosts of the organization defined under Organization. Clicking on the magnifying glass lets you select another inventory if necessary. Save the new inventory by pressing Save. In the lower part of the page, you will now find a list of all existing inventories. Clicking on a name opens the settings of the inventory in the upper area. At the moment, you should still be able to see the settings of the new inventory.

You now need to add all the hosts to the new inventory. An enterprise can contain quite a large number of hosts. To help you keep track, you can group the hosts. For example, you could put all the hosts from the Accounts department in the same group. To create a new group, click on the Groups button at the top and then click Add Group. Give the group at least one name, such as Accounts, and click Save. In the lower part of the screen, you will now find a list with all groups created in the inventory.

To define the hosts you wish to manage, click on the Hosts button in the top area. Use Add and New Host to add a new host. Enter the hostname. You can use its domain name and IP address. Finally, add the host to the inventory using Save. You can register additional hosts by following the same steps. You can also add a host to other groups once it has been saved. To add a host to another group, call Add in the group, click Existing Host, check the box to the left of the desired host, and select Save.

Unlike early Ansible Tower versions, AWX lets you add a host to an inventory directly. To do so, select Inventories from the menu on the left, click on the desired inventory, activate Hosts in the upper part, and add a new host via Add Host.

The way inventories are represented in AWX is somewhat confusing. Especially if you are using AWX for the first time, you will want to use the menu on the left to call up the inventories, and then click on the desired inventory. In the area at the top, you can now call up the groups and the hosts assigned to the inventory. A click on a group and then on Hosts lists all hosts contained in the group. At the top, you will also find a breadcrumb bar to help you navigate and find your way.

Storing Credentials

AWX, or the Ansible it uses, usually accesses the hosts via SSH. In order for this to work, you need to provide the access data to the hosts. AWX refers to the access data as a Credential. To store the credentials in AWX, open Credentials in the main menu on the left-hand side and click Add. Enter a name for the Credential in the corresponding field, and select the appropriate organization. You can use the name of the computer or computers for which the login data stored below applies.

Then click on the magnifying glass below Credential Type. Now select a procedure that AWX or Ansible can use to log on to the host. If access is via SSH, choose Machine and confirm by pressing Select. Additional fields now appear in which you then enter the login data. In the simplest case, Ansible logs in with the username and the password via SSH. The remaining fields remain empty. Under Privilege Escalation Method, you specify how Ansible can execute system commands after logging on to the host. With Ubuntu systems, for example, this is achieved with sudo. The username to be entered by Ansible is stored under Privilege Escalation Username, the password under Privilege Escalation Password. Press Save to save the settings. In the area at the bottom, you will now find all the credentials.

Creating Projects

AWX now knows which hosts it can access and how, but does not yet know what actions it has to perform. In Ansible, you define these actions in playbooks. AWX combines a collection of several playbooks to form a project. To create a project, go to Projects in the main menu on the left and click on Add. Enter a name for the project in the field and select the organization. Under SCM Type, select the version control system in which the playbooks are stored. For the SCM URL, enter the URL for the repository and fill out the remaining fields if required. If the repository with the playbooks requires authorization, first create a new suitable credential as described above, and then click on the magnifying glass next to SCM Credential and select the credential. For test purposes, the AWX developers offer a public GitHub repository with a simple playbook. Set the SCM Type to Git and select the address https://github.com/ansible/ansible-tower-samples as your SCM URL.

If you want to save the playbooks locally on your system, contrary to the developer's advice, you have to mount the directory with the playbooks in the ansible/awx_task and ansible/awx_web Docker containers. In both containers, the playbooks must appear in the /var/lib/awx/projects directory and at least be readable by the awx user. Once these conditions are met, set the SCM type to Manual in the AWX user interface.

Whatever else you do, save the project by pressing Save. If you have selected a version control repository, select Projects in the main menu again and then click on the cloud icon in the line for the project. AWX now retrieves the playbooks.

User Management

You can grant other people access to AWX. To do this, select Users in the menu on the left, click on Add, and fill out the form. The User Type setting defines which actions the person is allowed to perform. A system administrator, like you, can change all settings, and a normal user can only perform the actions you specify. After you click on Save, the new user appears in the list at the bottom of the page. You can change a user's data by clicking on the name in the list below. Users are usually only allowed to maintain the computers of their own organization. To let AWX know which user belongs to which organization, go to Organizations and then click on Users in the box. AWX now displays all users assigned to this organization in the area at the top. To add another user, click on Add and check the person's name. In the lower part of the form, assign one or more roles to the user. The roles determine what the person is allowed to do. If you click on Key on the right above the input field, AWX will show you which role allows which actions: While an Auditor can only see the current settings, the Admin can also change them. Member is only a member of the organization.

Creating and Starting Jobs

All the individual parts saved up to this point now need be glued together. Select Templates in the main menu on the left side of the page. Use Add to create a new job template (Figure 4). All the following settings can be changed by clicking on the magnifying glass icon. To execute a playbook, click the Run item below Job Type. Then select the desired inventory and project, and finally choose the playbook you wish to run. You'll need to select the credential that Ansible will use to log into the hosts.

To start the playbook, select Templates in the main menu and click on the job you wish to start in the line of the job template on the right side. In the background, Ansible now logs into the hosts and runs the selected playbook. AWX opens a new page with all the details and the output from Ansible. Select Jobs in the main menu to list all the jobs currently running.

If you want to execute a job automatically, switch to Templates in the main menu and click on the calendar symbol on the right side of a job template. Then schedule a new appointment with Add.

Conclusions

As a freely available counterpart to Ansible Tower, AWX not only offers a GUI, but also more options for organized and structured approach to Ansible, with user management, reporting, and workflows. As an open source project, AWX is less smooth than its commercial counterpart, but it is free of charge.

For additional information, see the official documentation for Ansible Tower, which also applies to AWX for the most part [2]. You can access the Ansible Tower documentation by clicking on the book symbol in the top right corner of AWX. Newcomers should first consult the Tower User Guide [3]. Even though AWX looks a little different from Ansible Tower, the settings shown in the Tower User Guide should be easy to find.