Ansible Docker Role Testing
adroit - Ansible Docker Role Testing
Heavily opinionated tool for testing Ansible roles using Docker containers.
Assumptions and limitations
These are the current assumptions about your Ansible codebase which might prevent you from using Adroit. They are subject to change or improve.
- You only deploy (or only want to test) on modern systems with systemd as their init system.
- You have a
baserole which other roles can build upon. (If you don't need this, you can just have an empty
- With the exception of depending on the base role, your Ansible roles are atomic, indepentent, and can be applied individually.
include_roleand dependencies defined in
metashould still work, though.
Feel free to open a Github issue about any limitations that prevent you from using Adroit.
How it works
- Adroit builds a core image based on your distro of choice.
- A container based on the core image is created. The
baserole will be applied to the container, and it is saved as the base image.
- For each role you want to test, a container based on the base image is started, and the role under test will be applied.
Adroit will check if the role playbook fails, and will also run the playbook a second time to test for idempotency - if there are any changes on the second run, we consider it a failure.
To properly test Ansible using Docker containers, systemd needs to be running inside the containers. This requires the containers to run in privileged mode. There is a security risk involved here, check your base images and playbooks accordingly.
In a virtualenv or whatever you prefer:
pip install adroit
In the root directory of your Ansible tree structure, which should at least contain a
roles directory, run this command:
adroit -d debian:stretch myrole
debian:stretch is the image you want to base your tests on. Currently supported are Debian, Ubuntu and CentOS.
Customizing your roles for testing
Certain tasks simply cannot be ran inside a Docker container - for example, mounting
hidepid=2. You should add a
when clause to these tasks. Example:
- when: ansible_virtualization_type != 'docker' import_tasks: configure_network.yml
If you need certain variables to be set which aren't in
vars but should be set during testing, you can create a file like
roles/myrole/testing/test_vars.yml and it will be applied when testing that particular role.
The contents of this repository is released under the MIT license. See the LICENSE file included for details.
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.