Before we get stuck into installing AWX, it is worth briefly exploring what AWX is, and indeed isn't. AWX is a tool to be employed alongside Ansible. It does not duplicate or replicate, in any way, the features of Ansible—indeed, when Ansible playbooks are run from AWX, the ansible-playbook binary is being called behind the scenes. Rather, AWX should be considered a complementary tool that adds the following benefits, on which many enterprises depend:
- Rich role-based access control (RBAC)
- Integration with centralized login services (for example, LDAP or Active Directory)
- Secure credential management
- Auditability
- Accountability
- Lower barrier to entry for new operators
- Improved management of playbook version control
Most of the AWX code runs in a set of Docker containers, which makes it straightforward to deploy in most environments. However, as further proof that AWX is a complementary tool to Ansible, it is installed using the ansible-playbook command!
Given the use of Docker containers, it is possible to run AWX in OpenShift or other Kubernetes environments—however, for the sake of simplicity here, we will get started by installing it on a single Docker host. Before you proceed any further, you should ensure that your chosen host has the following:
- Docker, fully installed and working
- The docker-py module for your version of Python
- Access to Docker Hub
- Ansible 2.4 or newer
- Git 1.8.4 or newer
With these tools in place, we start simply by cloning the AWX repository from GitHub to the host on which it is to be installed:
git clone https://github.com/ansible/awx.git
Now, change into the installer directory under the cloned repository:
cd awx/installer
By now, the contents of this directory should be familiar to you—we have an inventory file, and a playbook on which to install AWX! Edit the inventory file before proceeding any further—as you will see, there are many variables that can be configured, and most of them are well documented in the comments on the inventory file. As a bare minimum to get started, I recommend setting the following variables:
| Variable name | Recommended value |
| admin_password | This is the default password for the admin user—you will need this the first time you log in, so be sure to set it to something memorable and secure! |
| pg_password | This is the password for the backend PostgreSQL database—be sure to set it to something unique and secure. |
| postgres_data_dir | This is the directory on the local filesystem where the PostgreSQL container will store its data—it defaults to a directory under /tmp which, on most systems, will be automatically cleaned up on a regular basis. This often destroys the PostgreSQL database, so set it to something safe (for example, /var/lib/awx/pgdocker). |
| project_data_dir | For uploading playbooks manually to AWX without the need for a version control system, the playbooks must sit somewhere on the filesystem. To prevent having to copy them into a container, this variable maps the local folder specified to the required one inside a container. For the examples in this book, we will use the default (the /var/lib/awx/projects folder). |
| rabbitmq_password | This is the password for the backend RabbitMQ service—be sure to set it to something unique and secure. |
| secret_key | This is the secret key used to encrypt credentials in the PostgreSQL database. It must be the same between upgrades of AWX, so be sure to store it somewhere secure as it will need to be set in future AWX inventories. Make this something long and secure. |
You will, by now, have spotted that the previous file contains many secret values that lend themselves well to being stored in a Vault, but are in fact stored in the clear in the inventory file. It is assumed that you will delete the previous inventory once installation is complete, and it is highly recommended you do so!
Once the inventory is edited to your satisfaction, simply run the following command to install AWX:
sudo ansible-playbook -i inventory install.yml
That's all there is to it—when the playbook run finishes, the installation process is complete. If this is the first time you have installed AWX, you might need to give the system a few minutes to settle as the Docker containers start up and database schema is created. Once this completes, however, you will be able to log into AWX. Note here that the AWX web interface (and indeed the API) run unencrypted using HTTP on port 80. It is left up to the individual enterprise to configure SSL access to AWX—the easiest way to do this is to firewall off port 80 from the outside world, and put an SSL offloading setup in front of it. This could be a load balancer, reverse proxy, or even the venerable stunnel utility. For example, if we have installed AWX on CentOS 7, we could perform the following process:
- First of all, let's install NGINX (note that this requires that the EPEL repository is installed and enabled for CentOS 7):
sudo yum install nginx
- Next, we're going to need an SSL certificate for NGINX to use. If you have one, copy the certificate and associated private key to the following locations:
- Certificate: /etc/pki/tls/certs/mastery.example.com.crt
- Private key: /etc/pki/tls/private/mastery.example.com.key
If you don't have an SSL certificate, you can easily generate a self-signed one to complete this example using the following command:
openssl req -x509 -nodes -newkey rsa:4096 -keyout /etc/pki/tls/private/mastery.example.com.key -out /etc/pki/tls/certs/mastery.example.com.crt -days 3650 -subj "/C=GB/CN=mastery.example.com"
- Tailor the details to match your system—for example, /CN=mastery.example.com is the common name of the certificate, and should match the hostname of the AWX system.
- Once your certificate is in place, create the /etc/nginx/conf.d/awx.conf file with the following contents:
server {
listen 443 ssl;
server_name mastery.example.com;
ssl on;
ssl_certificate /etc/pki/tls/certs/mastery.example.com.crt;
ssl_certificate_key /etc/pki/tls/private/mastery.example.com.key;
location / {
proxy_pass http://127.0.0.1:80;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}
}
- Now we will edit /etc/nginx/nginx.conf and change the lines telling it to listen on port 80 to another port that we are not using—one of the Docker containers created earlier will be listening on port 80 already, so the nginx service won't start if we don't reassign this. Here's an example:
server {
listen 81 default_server;
listen [::]:81 default_server;
- Enable and start the service:
sudo systemctl enable nginx.service
sudo systemctl start nginx.service
- Finally, we will open up port 443 on the local firewall to allow this traffic in:
sudo firewall-cmd --permanent --add-service=https
sudo firewall-cmd --reload
Now we have a fully configured AWX service, and users should be able to access it using SSL! As discussed, there are many ways to enable SSL encryption of the AWX service, and the previous code should be used as an example only.
When you first log into AWX, you will be presented with a dashboard screen and a menu bar down the left-hand side. It is through this menu bar that we will explore AWX and perform our first configuration work. Equally, it is worth noting that when AWX is first installed, some example content is populated to help you get up to speed quicker. Feel free to explore the demo content as the examples are different to those given in this book.
Let's get started on getting our first playbook integrated and running with AWX.