Ansible Testing Guide

This project helps you create fully functional SystemD Docker containers for testing your Ansible roles. You can also use libvirt to automatically set up Windows virtual machines to test your roles using WinRM. It’s meant to be used locally on a Linux machine that has Docker (and optionally libvirt) installed.

Configuration

To set up your testing environment, check defaults/main.yml. Here, you can define your containers and customize them to your preferences.

• Specify a work_dir for temporary files, which will be deleted when running destroy.
• Identify the containers you want to start.

Key Functions

This role includes tasks to create and destroy containers and virtual machines. It goes through your list of containers or virtual_machines defined in vars.yml to create instances. Each Molecule scenario can use either containers or virtual machines, not both.

• Linux: Creates Docker containers that run with /sbin/init for full SystemD functionality.
• Windows: Sets up a VM with an unattended Windows installation and configures WinRM for Ansible during initial startup.

Note: Creating Windows VMs is resource-intensive and can take over 10 minutes.

Contributing

If you have other systems to test, you can submit a pull request with additional Dockerfiles or libvirt configurations.

How to Contribute

1. Fork the project on GitHub: Fork Here
2. Clone your fork on your Linux system.
3. Create a symlink to your fork in your Molecule scenario (e.g., ./molecule/default/).
4. Make changes, test your role, and when satisfied, commit and create a pull request.
5. Use GitHub Actions locally for quick feedback with act: Act Installation.

GitHubName=YourName
YourRoleDir=/This/Is/Your/Role/Directory/MyRole
YourRoleName=MyRole
WhereYourForkIs=/This/Is/Where/You/Clone/Your/Fork

# Clone your fork
cd $WhereYourForkIs
git clone https://github.com/$GitHubName/ansible-testing.git

# Symlink your local version in your Molecule scenario
cd $YourRoleDir/molecule/default
ln -s $WhereYourForkIs/ansible-testing drpsychick.ansible_testing

# Comment out role in requirements and delete downloaded version
sed -i -e 's/^ /# /' requirements.yml
rm -rf ~/.cache/molecule/$YourRoleName/default/roles/drpsychick.ansible_testing

When you run molecule, it will use the symlink for the drpsychick.ansible_testing role. Remember to commit your changes regularly, and create a pull request when done so others can benefit from your improvements.

Usage

Requirements:

• Linux (as it runs containers in privileged mode and binds to /sys/fs/cgroup)
• Docker
• libvirt (for Windows VMs)

Testing with Docker Containers (Linux)

You need to install molecule and molecule-docker using pip:

pip3 install -U molecule molecule-docker

Using Ansible Molecule

Create a new role with

molecule init role <name>

or initialize a Molecule scenario in an existing role directory with

molecule init scenario default

Download example files:

for f in create destroy molecule requirements vars; do
  curl -o molecule/default/$f.yml https://raw.githubusercontent.com/DrPsychick/ansible-testing/main/docs/molecule/default/$f.yml
done

Modify molecule/default/vars.yml to set up your containers and adjust the platforms in molecule/default/molecule.yml.

Run Molecule commands:

# Individually
molecule dependency
molecule create
molecule prepare
molecule converge
molecule idempotence
molecule verify
molecule cleanup
molecule destroy

# Or all at once
molecule test

Standalone

Create your own playbook or use the one in tests:

ansible-galaxy install -r requirements.yml

# Edit the YAML file as needed
echo "[defaults]
roles_path = .." > ansible.cfg

# Create containers
ansible-playbook tests/create.yml

# Destroy containers
ansible-playbook tests/destroy.yml

Testing with Windows VMs

Requirements:

• Install libvirt, libvirt-clients, virtinst
• Ansible Galaxy community.libvirt
• Install python3-winrm for Ansible's WinRM connectivity
• Refer to defaults/main.yml
  • Download the desired Windows Image (set up with Windows 2016).
  • Get the VirtIO ISO.
  • Place both ISOs into the libvirt_iso_dir.

Use libvirt as a User

Create writable pools for images and ISOs, ensuring proper permissions:

sudo virsh pool-create-as myisos dir --target /mydir/libvirt/isos
sudo virsh pool-edit isos # set permissions

sudo virsh pool-create-as myimages dir --target /mydir/libvirt/images
sudo virsh pool-edit images2 # set permissions

Update your variables in molecule/libvirt/vars.yml:

libvirt_image_dir: "/mydir/libvirt/images"
libvirt_iso_dir: "/mydir/libvirt/isos"
libvirt_disk_pool: "myimages"

Running with Ansible Molecule

Initialize a new role or scenario as mentioned above. Download the example files for Windows VMs like this:

for f in create destroy molecule requirements vars; do
  curl -o molecule/libvirt/$f.yml https://raw.githubusercontent.com/DrPsychick/ansible-testing/main/docs/molecule/libvirt/$f.yml
done

Then run the scenario:

molecule test -s libvirt

Standalone for Windows VMs

ansible-galaxy install -r requirements.yml

# Modify to fit your needs
echo "[defaults]
roles_path = .." > ansible.cfg

# Create the VM
ansible-playbook tests/create_vm.yml

# Destroy the VM
ansible-playbook tests/destroy_vm.yml

Speeding Up Provisioning with Predefined Windows Images

1. Create a qcow2 image or set up a VM once with an unattended installation.
2. Zip the ready-to-use VM: zip windows2016-clean.qcow2.zip windows2016.qcow2 (keep the filename consistent and in the zip root).
3. Move the zip to libvirt_iso_dir or provide it via URL (disk_image_url).

Test Locally with Different Ansible Versions

Ensure you have python3-venv installed:

# Specify the Ansible version
ANSIBLE_VERSION=15

# Create a virtual environment
python3 -m venv .venv
. .venv/bin/activate
pip3 install --upgrade pip setuptools wheel
pip3 install --requirement requirements-ansible_${ANSIBLE_VERSION}.txt

molecule test

This guide provides a straightforward overview of setting up testing environments for Ansible roles using Docker and Windows VMs. Follow the steps to efficiently conduct your testing and contribute back to the project.