Setting up Ansible AWX using a docker environment - Part 1 (the Ansible approach)

A guide on how to get Ansible AWX (open source version of Ansible Tower) running in an isolated docker environment.

Pre-setup

System requirements

Supported Operating Systems:

  • Red Hat Enterprise Linux 6 64-bit
  • Red Hat Enterprise Linux 7 64-bit
  • CentOS 6 64-bit
  • CentOS 7 64-bit
  • Ubuntu 12.04 LTS 64-bit
  • Ubuntu 14.04 LTS 64-bit

Hardware requirements:

  • 2 CPUs minimum for Tower installations
  • 20 GB hard disk
  • 4 GB RAM minimum for Tower installations

For Amazon EC2:

  • Instance size of m3.medium or larger
  • An instance size of m3.xlarge or larger if there are more than 100 host

Software requirements:

  • docker on the host where Ansible AWX will be setup
  • docker-compose Python module installed

Steps

  git clone https://github.com/ansible/awx.git
  cd installer

Inventory file

The inventory file found inside the installer directory contains a lot of properties used for building the Ansible AWX containers.

The default file provided can be seen at: https://github.com/ansible/awx/blob/devel/installer/inventory

Here are a few of them. Username, passwords, data directory’s, ports can be updated accordingly to your environment setup.

Key Default Comments
dockerhub_base ansible By default the base will be used
awx_task_hostname awx hostname of task docker container
awx_web_hostname awxweb hostname of web docker container
postgres_data_dir ~/.awx/pgdocker path to where the postgres data directory is found on the localhost
host_port 80 http port of the web container exposed on the localhost
host_port_ssl 443 ssl port of the web container exposed on the localhost
pg_hostname postgresql hostname of the postgres database (leaving this commented will create a container running postgres)
pg_username awx postgres username
pg_password awxpass postgres password
pg_admin_password postgrespass postgres admin password
pg_database awx postgres database name
pg_port 5432 postgres database port exposed on localhost
admin_user admin web login username
admin_password password web login password
project_data_dir /var/lib/awx/projects By default this is commented out, and if enabled will allow you to host ansible playbooks locally (instead of SCM) using the set directory on the ‘awx_task’ container
docker_compose_dir ~/.awx/awxcompose Docker compose directory, generated at playbook runtime

PostgreSQL database

If you are planning to reuse an existing external database and not create an additional docker container for PostgreSQL. Make sure the pg_* properties are updated accordingly inside the inventory file.

Running the Ansible playbook

Once you are comfortable that the inventory file is correct, the next step is to run the playbook.

Make sure you are in the installer directory. Then invoke the following command.

  ansible-playbook -i inventory install.yml

Docker containers

If successful you should see 5 containers running. (Provided you did not change the default host-names in the inventory file)

Once the playbook has run take a look at ~/.awx/awxcompose (see inventory file, property=docker_compose_dir for the path)

At runtime of the playbook it generates this directory and the following files:

  • SECRET_KEY (AWX Secret key – It’s very important that this stay the same between upgrades or you will lose the ability to decrypt your credentials)
  • credentials.py
  • docker-compose.yml
  • environment.sh
  • nginx.conf

Accessing the web UI

Enter the following URL into a web-browser to access the web UI:

http://localhost

On initial page load, Ansible will show that it is upgrading components. So wait until that completes, and finally a login page will be displayed as below.

Again, provided you haven’t changed the default username/password.

You can login with admin/password

Once logged in you should see the dashboard where you can manage your Ansible environment.

Demo project

Post setup, a Demo project comes bundled with AWX.

This uses the hello world playbook from https://github.com/ansible/ansible-tower-samples/blob/master/hello_world.yml so make sure to give it a test.

Launch the demo project

This project executes an SCM update pulling the latest from the github repository, then runs the playbook.

  • Click on Templates

  • Click on the launch icon

The playbook console output will be displayed as below.

Errors and how to resolve them

  TASK [local_docker : Start the containers] 
  fatal: [localhost]: FAILED! => {"changed": false, "msg": "Failed to import the required Python library (Docker SDK for Python: docker (Python >= 2.7) or docker-py (Python 2.6)) on <host> Python /bin/python. Please read module documentation and install in the appropriate location, for example via `pip install docker` or `pip install docker-py` (Python 2.6). The error was: No module named docker"}                                      

Fix:

  pip uninstall docker docker-py

 Note

Make sure you have docker compose installed via pip, as it comes bundled with docker so no need to install additional docker Python modules

  Fatal: [localhost]: FAILED! => {"changed": false, "errors": [], "module_stderr": "Creating awx_rabbitmq ... \r\nCreating awx_memcached ... \r\nCreating awx_postgres  ... \r\n\r\u001b[1BCreating awx_web       ... \r\n\r\u001b[1B", "module<br>_stdout": "", "msg": "Error starting project unknown cause"}   <br>

Fix:

 Note

Make sure there are no conflicting ports being used on the localhost.

For example the awx_web container uses port 80 as default, and if you already have something already running on port 80 there will be a problem.

You can change the default ports in the inventory file.

Last updated on 2 Oct 2019
Published on 2 Oct 2019