Introduction

As the use of virtualization (VMs and containers) expands rapidly in many organizations, automation is needed for virtual server management to address the tedious and repetitive tasks. Ansible is a powerful tool for automation, deployment, and configuration management that has historically required living on the command line interface (CLI). The open-source version of Ansible Tower is AWX - a web-based user interface (UI) for Ansible. When we wanted to explore how AWX works we quickly realized that the existing AWX installation guides need an overwhelming amount of trial and error to make work. This blog presents how to execute a reliable installation process and also explains the automation of the process that reduced our installation to just running a single command. Our comparison and selection of an Ansible UI from a list of 4 options is documented in this blog if you want to learn about that effort.

AWX overview

AWX is a UI solution that sits on top of the Ansible CLI supporting functionality such as visualization of host management and running job status including Ansible playbooks, specification of job parameters, and login authentication. Since AWX is an open-source version of an enterprise product, it has very limited official documentation. During our testing we encountered issues such as insufficient dependency specs, failure to pull Docker images, and inability to visualize our AWX instance. There are many different unofficial guides, but unfortunately, very few of them work reliably without the need for debugging. This blog documents a simple and reliable method for installing AWX.

Prerequisites

Our goal was to deploy AWX on a management system that can connect to a workload environment for VM automation. The only prerequisites you need to get started is to have Ansible installed in the management system and to have your Docker Hub login credentials available. It is crucial to store your Docker Hub username and password in a file named secret.enc under the vars folder of the playbook in following format:

Then, you should encrypt the file using a command similar to the one below using Ansible Vault.

Testing system details

Table 1: System Details

Components to be deployed by the Installation Playbook

Table 2: Components to be Deployed

Installation Process

Figure 1: High-level Overview of the Components in the Installation

The goal is to have a running instance of AWX accessible with a browser. With this design, the user only needs one command to run the playbook that installs AWX. This command asks for the sudo permission so the playbook can use elevated privileges whenever necessary. A vault password is also requested to use the encrypted Docker Hub credentials described above for a successful login into Docker. Minikube and Docker are automatically installed by the installation playbook. Minikube is the backbone of this installation process and provides the resources that the AWX instance is installed on. Docker ensures that the Minikube pods are ready for initializing AWX. 

Here is an outline of the background process for the Ansible playbook:

1. The playbook installs the necessary prerequisites. 

2. The playbook logs into and sets up Docker.

3. A Minikube instance is run with specified configurations. 

Figure 2: Creation of Minikube Instance

4. An image pull secret is created and patched to the service account based on the Docker Hub credentials for successful image pulls.

Figure 3: Creation of an Image Pull Secret

5. AWX operator is deployed and it runs as a pod[PD1] .

Figure 4: Deployment of AWX Operator

Figure 5: Running AWX Operator Pod[SM2] 

6. AWX instance is deployed with 4 pods for the instance and 1 pod for postgres.

Figure 6: Deployment of AWX Instance

Figure 7: Deployment File (ansible-awx.yml)

Figure 8: Running Pods for AWX Instance and Postgres[SM3] 

7. Expose the port for the AWX instance through port forwarding and display the IP address and login information for accessing the instance.

After running the Ansible install AWX playbook, the login information including username, password, and IP address with port for the AWX instance will be displayed as a part of the detailed output. 

Figure 9: An Example of the Playbook Output with Login Information

Then, you can access the dashboard for AWX using your host’s IP address and port 32483 with login credentials provided from the above output. 

Figure 10: AWX Dashboard After a Successful Installation and Login

Common errors and solutions

A few errors that you may encounter during the installation process:

• ImagePullBackOff: Kubernetes fails to pull container images from Docker Hub. It is important to make sure that you are logged into Docker Hub successfully using Ansible Vault. You can also login manually using docker login, but it is less secure.
• Certificate and connection related errors: Ensure that VM resources are sufficient for running Minikube with predefined specifications. If multiple users are working on the same server with several Kubernetes clusters, such errors may also occur due to resource limitations.

Conclusion

This blog introduces a quicker and more convenient way to reliably install AWX. With a simple goal of having a running AWX instance on a server, this blog demonstrates a straightforward solution to achieve that goal while many other existing guides need much more customizations and configurations for the successful execution of an AWX deployment.