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: