AWX is the open source version of Ansible Tower. It’s a powerful tool, but unfortunately AWX has no in place upgrade capability. If you want to upgrade your AWX to the latest version it takes a bit of trickery (the easy way out being just to pay for Ansible Tower.)
Essentially to upgrade AWX you need to spin up a completely new instance and then migrate your data over to it. Fortunately there is a script out there that makes doing this a bit easier.
Below are my notes for how I upgraded my instance of AWX from version 1.0.6 to 2.1.0.
Create temporary AWX migration server
Spin up new server with ansible installed, then clone AWX
git clone https://github.com/ansible/awx.git cd awx git clone https://github.com/ansible/awx-logos.git
Modify AWX install to expose 5432 externally:
edit installer/roles/local_docker/tasks/standalone.yml and add
ports:
- "5432:5432"
right above the when: pg_hostname is not defined or pg_hostname == ''
line. Complete stanza looks like this:
- name: Activate postgres container
docker_container:
name: postgres
state: started
restart_policy: unless-stopped
image: "{{ postgresql_image }}"
volumes:
- "{{ postgres_data_dir }}:/var/lib/postgresql/data:Z"
env:
POSTGRES_USER: "{{ pg_username }}"
POSTGRES_PASSWORD: "{{ pg_password }}"
POSTGRES_DB: "{{ pg_database }}"
PGDATA: "/var/lib/postgresql/data/pgdata"
ports:
- "5432:5432"
when: pg_hostname is not defined or pg_hostname == ''
register: postgres_container_activate
Make sure you have port 5432 open on your host-based firewall.
Install AWX on the new host. Verify you can log into the empty instance and that it’s the version you want to upgrade to.
Prepare original AWX server to send
Kill the AWX postgres container on the source machine, and re-run awx installer after modifying it to expose its postgres port as described above.
Install tower-cli (this can be on either source or destination servers)
sudo pip install ansible-tower-cli
Configure tower-cli
tower-cli config username SRC_AWX_USERNAME towercli config password SRC_AWX_PASSWORD towercli config host SRC_AWX_HOST
Make sure to use full ansible URL as accessed from a browser for both source and destination
Install awx-migrate:
git clone https://github.com/autops/awx-migrate.git
Update awx-migrate/awx-migrate-wrapper with correct source and destination info
Run awx-migrate-wrapper. It will generate json files with your configuration.
Migrate database to temporary server
Modify tower-cli config, set host, username and password to that of the destination AWX instance
tower-cli config username DEST_AWX_USERNAME towercli config password DEST_AWX_PASSWORD towercli config host: DEST_AWX_HOST
Send JSON info to destination:
tower-cli send awx-data.json
You will now have a fresh new, updated AWX instance working, with imported database, on the destination host. Confirm you can log into it with the admin account you set it up with.
Prepare original AWX server to receive
Now, on the source, remove the old AWX docker containers:
sudo docker rm -f postgres awx_task awx_web memcached rabbitmq
Move / delete the database folder the postgres docker container was using (as defined in awx installer inventory) in my case:
/var/lib/awx /var/db/pgsqldocker
Remove and re-install AWX folder with a fresh git checkout
rm -rf awx git clone https://github.com/ansible/awx.git cd awx git clone https://github.com/ansible/awx-logos.git
Re-run the AWX installer to re-create a blank database on the source host, modify the new awx/installer/inventory as needed. Also modify installer/roles/local_docker/tasks/standalone.yml
as outlined above.
cd awx/installer sudo ansible-playbook -i inventory install.yml
Migrate from temporary AWX server back to source AWX server
Once a new, empty version of awx is running on the source host, start the awx-migrate process in reverse to migrate the database on the destination instance back to the source. Modify awx-migrate-wrapper and tower-cli to switch src and destination (the destination has become the source and the source has become the destination)
Use awx-migrate-wrapper to generate new ansible version json files (don’t confuse them with the old json files – best to delete / move all json files before running awx-migrate-wrapper)
Modify tower-cli to point to original AWX URL
Run tower-cli send awx-data.json
Once completed, log in as the admin account. Input LDAP BIND password under settings, then delete any imported LDAP users.
Cleanup
You may want to remove the exposed postgres database ports. Simply undo the changes you made in awx/installer/roles/local_docker/tasks/standalone.yml to remove the Ports part of the first play, then remove your postgres container and re-install AWX with install.yml
Also remember to delete the JSON files generated with awx-migrate as they contain all your credentials in plaintext.
Success.
hello,
this script will decrypt the users passwords as well, which will be in stdout, how do you manage this?
Thanks
In my case all my users are LDAP based, so I didn’t really worry about it. But you are right, it decrypts everything – it’s the only way to transfer the database. So the way I handle it is by deleting all the JSON files after the migration is completed.
It doesn’t work for custom credentials, passwords and few other things. I think this is mentioned in the tower-cli documents also. Also, it is recommended to export individual configurations like credentials, inventories, templates etc instead of exporting entire content altogether. I did it earlier and it failed to import because of missing dependencies.
Could you please confirm why the temporary awx environment was built? I think we get a .json file which we can import later.
It’s for testing. I wanted the temp environment so I could test everything without destroying the original prod environment. You can skip that step if you’re really confident the JSON exported everything you need.