lae.travis-lxc

This tool sets up and runs N LXC containers for testing Ansible roles in the Travis CI environment. This makes it easier to test across different operating systems.

How to Use

If you want to test your Ansible roles on Travis CI without using Docker (because Docker doesn’t emulate a full operating system), you should use LXC. This tool will help simplify the setup.

To start, a basic .travis.yml file to validate your role may look like this:

---
language: python
sudo: required
dist: bionic
install:
- pip install ansible
- ansible-galaxy install lae.travis-lxc,v0.9.0
- ansible-playbook tests/install.yml -i tests/inventory
before_script: cd tests/
script:
- ansible-playbook -i inventory deploy.yml --syntax-check
- ansible-playbook -i inventory deploy.yml
- 'ANSIBLE_STDOUT_CALLBACK=debug ANSIBLE_DISPLAY_SKIPPED_HOSTS=no ANSIBLE_DISPLAY_OK_HOSTS=no
  unbuffer ansible-playbook -vvi inventory deploy.yml &>play.log; printf "Idempotence: ";
  grep -A1 "PLAY RECAP" play.log | grep -qP "changed=0 .*failed=0 .*"
  && (echo "PASS"; exit 0) || (echo "FAIL"; cat play.log; exit 1)'
- ANSIBLE_STDOUT_CALLBACK=debug ansible-playbook -i inventory -v test.yml

You’ll see references to four files. You can customize your build process, but here’s a typical setup:

• tests/install.yml: runs lae.travis-lxc and any setup steps needed.
• tests/deploy.yml: runs the role you are testing.
• tests/test.yml: conducts validation tests on your deployment.
• tests/inventory: contains hostnames for the LXC containers.

The install.yml file could look like this:

---
- hosts: localhost
  connection: local
  roles:
    - lae.travis-lxc
  vars:
    test_profiles:
      - profile: debian-buster
      - profile: ubuntu-focal
      - profile: centos-7
      - profile: alpine-v3.11

- hosts: all
  tasks: []

The first part creates three containers with different distributions. The second part is where you can run other roles or pre-install tasks your role might not handle (like installing epel-release).

The deploy.yml file could be like this:

---
- hosts: all
  become: true
  any_errors_fatal: true
  roles:
    - ansible-role-strawberry-milk
  vars:
    number_of_cartons: 15

This outlines how to properly run your role. For more complex roles, you may want to split variables into the tests/group_vars folder and set up your inventory accordingly.

Your test.yml should include any tests you want to run:

---
- hosts: all
  tasks:
    - name: Ensure that the Strawberry Milk HTTP service is running
      uri:
        url: "http://{{ inventory_hostname }}:1515"
    - block:
      - name: Print out Strawberry Milk configuration
        shell: cat /etc/strawberry_milk.conf
        changed_when: false
      - name: Print out system logs
        shell: "cat /var/log/messages || cat /var/log/syslog || journalctl -xb"
      ignore_errors: yes

This can help check that a service is running, if a cluster is performing well, or if specific files exist. The tasks in the block section are for diagnostics, helping debug any issues, and will not cause the build to fail.

Finally, the inventory file could look like this:

debian-buster-01
ubuntu-focal-01
centos-7-01
alpine-v3-11-01

Hostnames are created from a prefix and suffix. By default, these are formed by the profile key in test_profiles and will look like {{ profile }}-{{ suffix }}, where the default suffix is 01.

When you have these files prepared, you're ready to test your role on Travis CI. If you want to expand your testing, let's look at a few more options.

Testing with Different Ansible Versions

You may want to test your role against various versions of Ansible. You can set this up in your .travis.yml file like this:

env:
- ANSIBLE_GIT_VERSION='devel'
- ANSIBLE_VERSION='~=2.9.0'
- ANSIBLE_VERSION='~=2.7.0'
install:
- if [ "$ANSIBLE_GIT_VERSION" ]; then pip install "https://github.com/ansible/ansible/archive/${ANSIBLE_GIT_VERSION}.tar.gz";
  else pip install "ansible${ANSIBLE_VERSION}"; fi
- ansible --version

Here, the install task will either use ANSIBLE_GIT_VERSION for the latest code or ANSIBLE_VERSION for a specific version that you can install via pip.

Improving Ansible Performance

You can adjust performance settings in tests/ansible.cfg:

[defaults]
callback_whitelist=profile_tasks
forks=20
internal_poll_interval = 0.001

This will help monitor which tasks take the longest to run. It's good to set forks to run multiple tasks at once, and internal_poll_interval can help with performance when running several tasks/loops.

Caching

You can cache LXC images to speed up the boot process, especially for multiple profiles. Add this to your .travis.yml to enable caching:

cache:
  directories:
  - "$HOME/lxc"
  pip: true

(Note: pip: true is included, but not necessary for this role.)

Role Variables

To choose what distributions to test, use test_profiles. Supported profiles include:

test_profiles:
  - profile: alpine-v3.11
  - profile: alpine-v3.10
  - profile: debian-buster
  - profile: ubuntu-focal

There are older profiles that may still work, but are not actively supported:

test_profiles:
  - profile: debian-jessie
  - profile: centos-6

You can also change the default naming convention for test containers, add extra packages, and configure caching for specific profiles.

Contributors

Musee Ullah (@lae, lae@lae.is)
Wilmar den Ouden (@wilmardo)

Stability

This role is still in a pre-1.0 phase, meaning it may not be stable. If you find any issues, please report them with a short description and relevant logs for us to fix.

Remember to pin to a specific version while using this role to avoid problems with future updates that might break your tests.