Tower of Power

After the acquisition of Ansible by Linux behemoth Red Hat, the development path of both Ansible – a software provisioning, configuration management, and deployment automation solution – and Ansible Tower – a web-based console for managing complex Ansible deployments – changed. (Also see the "Configuration Management and Ansible" box.)

In true Red Hat style, in which open source projects are cherry picked, stabilized, hardened, and released with commercial support for their enterprise customers, the freely available version of Ansible Tower, AWX, has arrived.

To avoid the blurring of definitions, I quote the opening introduction to the AWX ReadMe file for clarity: "AWX provides a web-based user interface, REST API, and task engine built on top of Ansible. It is the upstream project for Tower, a commercial derivative of AWX."

I stumbled across AWX when looking for a way to manage multiple playbooks providing idempotency, of which my definition in this case was running playbooks every 20 minutes on multiple servers to provide assurance of the integrity of their configuration for security and uptime.

To be clear, by configuration management I mean the ability to affect configuration on servers (or devices) of all varieties in an automated, predictable, and, one hopes, more secure way.

As well as the API, AWX can happily integrate with your ChatOps software (several popular flavors are included) and fire off all sorts of notifications, with a view to your DevOps efforts being significantly reduced when it comes to managing your myriad of playbooks.

In this article, I show you how to install AWX and run a project. AWX is not intended for production use, but it should still provide you with lots of useful functionality within your other environments.

Spinning Plates

In this example I use a DigitalOcean "droplet" (their name for a server), which is very affordable to run for a few hours and then snapshot if you want to come back to a half-built solution later. A word to the wise, however: At the time of writing, even stopped droplets appeared to incur ongoing charges (unlike some cloud platforms), so destroy the droplet after creating a snapshot for posterity.

As mentioned, only a few relatively simple installation steps are required to fire up a handful of Docker containers. Your web interface is then automagically presented through a port on your host machine, with the initial credentials admin and password.

If you prefer, you can also effect a Kubernetes installation via Helm, the popular Kubernetes package manager, or indeed OpenShift or Docker Compose installations if you are that way inclined. For ease, I shall stick with Docker on this occasion. Should you decide to opt for an alternative installation route, you can find help on the AWX GitHub page [5].

System Requirements

The system that runs the AWX service will need to satisfy the following requirements:

• At least 4GB of memory
• At least 2 CPU cores
• At least 20GB of space
• A running Docker, OpenShift, or Kubernetes
• A minimum PostgreSQL v9.4 if you choose to use an external database

Attack of the Clones

The first step is to get hold of the good stuff by cloning the repository. With the Git package installed, you can run the command:

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

On my Ubuntu 18.04 droplet, I run the command

$ apt install ansible

to install Ansible itself. Everything is pretty much ready to go and almost to the point at which you can run your installation playbook.

It's Run Time!

Next, you need a run time to fire up your containers. Likely the wisest choice would be to install the Community Edition (CE) of Docker [6], but I am going to use the current package manager version, also known as docker.io:

$ apt install docker.io

To enter the installer directory that your git clone command created inside awx/, use:

$ cd awx/installer

I will not go into the many options that can be tweaked in the inventory file, but you can make many adjustments, such as installing awx on a remote host. As you would expect, the installation docs [5] can assist and are well put together.

In the awx/installer directory of your downloaded repository, simply run Ansible to start up the intricate installation process to create your AWX containers:

$ ansible-playbook -i inventory install.yml

If you tweaked the inventory file, this is where the changes are picked up. Go away, make a cup of tea, and come back a few minutes later. Listing 1 shows the end of the output for the playbook run.

TASK [local_docker : Activate AWX Web Container] ******************************************************
ok: [localhost]
TASK [local_docker : Activate AWX Task Container] *****************************************************
ok: [localhost]
TASK [local_docker : Create /var/lib/awx directory] ***************************************************
ok: [localhost]
TASK [local_docker : Create docker-compose.yml file] **************************************************
ok: [localhost]
TASK [local_docker : Start the containers] ************************************************************
ok: [localhost]
PLAY RECAP ******************************************************************
localhost                  : ok=11   changed=0    unreachable=0    failed=0

Now, run the

$ docker ps

command for another quick check (Figure 1). You can see that a number of AWX-related containers are running.

And Now

If you are installing AWX on a local machine, simply point your browser to http://localhost. (Clearly, I am assuming that you have a sane networking and firewall configuration.) On my droplet, however, I need to find my public IP address and point my browser there. You can type ip a on the droplet at the command line if you are not sure. (Not all cloud platforms expose the public IP address on the main network interface.)

As soon as you put the public IP address into your browser, you are presented a login screen. You will want to log in and change the default password, because the web interface currently is public to the Internet without any filtering.

If you get stuck, start following the logs in one of the containers with:

$ docker logs -f awx_task

This command should produce lots of scrolling output in your console.

Get It Together

The extensible AWX organizes through the concept of projects. You will probably see a Demo Project that offers some pointers, and you can configure that to look at a public Git repository on GitHub (with no credentials, for ease of use).

Once you have changed the password and logged in again, look to the navigation pane on the left and click Projects. Ignore the Demo Project and click the green plus sign on the top-right of that section to create a new project.

In Figure 2 you can see that I have added a name for the project, along with the URL of a super-simple Ansible playbook (Listing 2), which I will use as an example. As you can see in the listing, the GitHub repository [7] just contains some basic YAML that I will use as an Ansible playbook.

---
- hosts: localhost
  tasks:
  - name: Just complete as valid YAML please
    command: date +%F

Hold On a Minute

If you have followed the steps above verbatim, you have probably managed to save the new project but noticed at the bottom of the screen (Figure 3) a red exclamation mark to the left of the project name. When you create a project, I suspect AWX automatically tests the software configuration management (SCM) repository access, with or without credentials, and/or potentially runs it.

Because of the pointy-clicky nature of the powerful AWX, it is probably easier to let you work through the intricacies of your own projects. Showing a failure will therefore help you out the most. In Figure 4, you can see the AWX output when a job fails by clicking Jobs on the left-hand navigation pane.

By adjusting the SCM URL initially put into the project, you can now save your project without failure. Simply adjusting the playbook URL to https://github.com/chrisbinnie/DevSecOps removes the warning exclamation mark. As AWX tries to get access to the repo and process the job, you will see a pulsing green circle, which means it is working away in the background; I suspect it is pulling the latest code and running the job to see if it completes.

Job's a Good 'Un

Back on the main Jobs page again and clicking on the welcome "green" job (denoting success), you can see (Figure 5) that the simple playbook completed correctly this time. Look at the YAML (STDOUT) output, too, in the right-hand pane. You can drill down easily into more detail.

You can rerun the job by clicking the rocket icon, or you can delete it by clicking on the trash can.

The other aspect to familiarize yourself with is the templates configuration, which helps run jobs. Again, the template config is in the navigation pane and easy to find. I will leave you to explore that further.

Of course, you will want to know (immediately sometimes) about the successes and failures of your many playbooks. Figure 6 shows some of the options available under Notifications on the left-hand side. All the usual suspects are present and accounted for, along with good old email.

The End Is Nigh

If the AWX Apache License 2.0 suits your needs, consider how best you can deploy it. Running within containers, it is lightweight to deploy and its engine is undoubtedly sophisticated. Ultimately, it is a feature-filled piece of software that answers many configuration management questions. Even the user-based controls aspect makes accessing a playbook across multiple teams a worthwhile feature. I hope you get as much from AWX as I plan to in the future.