Tutorial

How To Test Ansible Roles with Molecule on Ubuntu 18.04

Published on October 2, 2018

How To Test Ansible Roles with Molecule on Ubuntu 18.04

The author selected the Mozilla Foundation to receive a donation as part of the Write for DOnations program.

Introduction

Unit testing in Ansible is key to making sure roles function as intended. Molecule makes this process easier by allowing you to specify scenarios that test roles against different environments. Using Ansible under the hood, Molecule offloads roles to a provisioner that deploys the role in a configured environment and calls a verifier (such as Testinfra) to check for configuration drift. This ensures that your role has made all of the expected changes to the environment in that particular scenario.

In this guide, you will build an Ansible role that deploys Apache to a host and configures firewalld on CentOS 7. To test that this role works as intended, you will create a test in Molecule using Docker as a driver and Testinfra, a Python library for testing the state of servers. Molecule will provision Docker containers to test the role and Testinfra will verify that the server has been configured as intended. When you’re finished, you’ll be able to create multiple test cases for builds across environments and run these tests using Molecule.

Prerequisites

Before you begin this guide you’ll need the following:

One Ubuntu 18.04 server. Follow the steps in the Initial Server Setup with Ubuntu 18.04 guide to create a non-root sudo user, and make sure you can connect to the server without a password.
Docker installed on your server. Follow Steps 1 and 2 in How To Install and Use Docker on Ubuntu 18.04, including adding your non-root user to the docker group.
Python 3 and venv installed and configured on your server. Follow How To Install Python 3 and Set Up a Programming Environment on an Ubuntu 18.04 Server for guidance.
Familiarity with Ansible playbooks. For review, see Configuration Management 101: Writing Ansible Playbooks.

Step 1 — Preparing the Environment

If you’ve followed the prerequisites, you should have Python 3, venv, and Docker installed and correctly configured. Let’s begin by creating a virtual environment to test Ansible with Molecule.

Start by logging in as your non-root user and creating a new virtual environment:

python3 -m venv my_env

Activate it to ensure that your actions are restricted to that environment:

source my_env/bin/activate

Next, in your activated environment, install the wheel package, which provides the bdist_wheel setuptools extension that pip uses to install Ansible:

python3 -m pip install wheel

You can now install molecule and docker with pip. Ansible will be automatically installed as a dependency for Molecule:

python3 -m pip install molecule docker

Here is what each of these packages will do:

molecule: This is the main Molecule package that you will use to test roles. Installing molecule automatically installs Ansible, along with other dependencies, and enables the use of Ansible playbooks to execute roles and tests.
docker: This Python library is used by Molecule to interface with Docker. You will need this since you’re using Docker as a driver.

Next, let’s create a role in Molecule.

Step 2 — Creating a Role in Molecule

With your environment set up, you can use Molecule to create a basic role that you will use to test an installation of Apache. This role will create the directory structure and some initial tests, and specify Docker as the driver so that Molecule uses Docker to run its tests.

Create a new role called ansible-apache:

molecule init role -r ansible-apache -d docker

The -r flag specifies the name of the role while -d specifies the driver, which provisions the hosts for Molecule to use in testing.

Change into the directory of the newly created role:

cd ansible-apache

Test the default role to check if Molecule has been set up properly:

molecule test

You will see output that lists each of the default test actions. Before starting the test, Molecule validates the configuration file molecule.yml to make sure everything is in order. It also prints this test matrix, which specifies the order of test actions:

Output--> Validating schema /home/sammy/ansible-apache/molecule/default/molecule.yml.
Validation completed successfully.
--> Test matrix

└── default
    ├── lint
    ├── destroy
    ├── dependency
    ├── syntax
    ├── create
    ├── prepare
    ├── converge
    ├── idempotence
    ├── side_effect
    ├── verify
    └── destroy
...

We will discuss each test action in detail once you’ve created your role and customized your tests. For now, pay attention to the PLAY_RECAP for each test, and be sure that none of the default actions returns a failed status. For example, the PLAY_RECAP for the default 'create' action should look like this:

Output...
PLAY RECAP *********************************************************************
localhost                  : ok=5    changed=4    unreachable=0    failed=0

Let’s move on to modifying the role to configure Apache and firewalld.

Step 3 — Configuring Apache and Firewalld

To configure Apache and firewalld, you will create a tasks file for the role, specifying packages to install and services to enable. These details will be extracted from a variables file and template that you will use to replace the default Apache index page.

Still in the ansible-apache directory, create a tasks file for the role using nano or your favorite text editor:

nano tasks/main.yml

You’ll see that the file already exists. Delete what’s there and replace it with the following code to install the required packages and enable the correct services, HTML defaults, and firewall settings:

~/ansible-apache/tasks/main.yml

---
- name: "Ensure required packages are present"
  yum:
    name: "{{ pkg_list }}"
    state: present

- name: "Ensure latest index.html is present"
  template:
    src: index.html.j2
    dest: /var/www/html/index.html

- name: "Ensure httpd service is started and enabled"
  service:
    name: "{{ item }}"
    state: started
    enabled: true
  with_items: "{{ svc_list }}"

- name: "Whitelist http in firewalld"
  firewalld:
    service: http
    state: enabled
    permanent: true
    immediate: true

This playbook includes 4 tasks:

"Ensure required packages are present": This task will install the packages listed in the variables file under pkg_list. The variables file will be located at ~/ansible-apache/vars/main.yml and you will create it at the end of this step.
"Ensure latest index.html is present": This task will copy a template page, index.html.j2, and paste it over the default index file, /var/www/html/index.html, generated by Apache. You will also create the new template in this step.
"Ensure httpd service is started and enabled": This task will start and enable the services listed in svc_list in the variables file.
"Whitelist http in firewalld": This task will whitelist the http service in firewalld. Firewalld is a complete firewall solution present by default on CentOS servers. For the http service to work, you will need to expose the required ports. Instructing firewalld to whitelist a service ensures that it whitelists all of the ports that the service requires.

Save and close the file when you are finished.

Next, let’s create a templates directory for the index.html.j2 template page:

mkdir templates

Create the page itself:

nano templates/index.html.j2

Paste in the following boilerplate code:

~/ansible-apache/templates/index.html.j2

<div style="text-align: center">
    <h2>Managed by Ansible</h2>
</div>

Save and close the file.

The final step in completing the role is writing the variables file, which provides the names of packages and services to our main role playbook:

nano vars/main.yml

Paste over the default content with the following code, which specifies pkg_list and svc_list:

~/ansible-apache/vars/main.yml

---
pkg_list:
  - httpd
  - firewalld
svc_list:
  - httpd
  - firewalld

These lists contain the following information:

pkg_list: This contains the names of the packages that the role will install: httpd and firewalld.
svc_list: This contains the names of the services that the role will start and enable: httpd and firewalld.

Note: Make sure that your variables file doesn’t have any blank lines or your test will fail during linting.

Now that you’ve finished creating your role, let’s configure Molecule to test if it works as intended.

Step 4 — Modifying the Role for Running Tests

In our case, configuring Molecule involves modifying the Molecule configuration file molecule.yml to add platform specifications. Because you’re testing a role that configures and starts the httpd systemd service, you will need to use an image with systemd configured and privileged mode enabled. For this tutorial, you will use the milcom/centos7-systemd image available on Docker Hub. Privileged mode allows containers to run with almost all of the capabilities of their host machine.

Let’s edit molecule.yml to reflect these changes:

nano molecule/default/molecule.yml

Add the highlighted platform information:

~/ansible-apache/molecule/default/molecule.yml

---
dependency:
  name: galaxy
driver:
  name: docker
lint:
  name: yamllint
platforms:
  - name: centos7
    image: milcom/centos7-systemd
    privileged: true
provisioner:
  name: ansible
  lint:
    name: ansible-lint
scenario:
  name: default
verifier:
  name: testinfra
  lint:
    name: flake8

Save and close the file when you are done.

Now that you’ve successfully configured the test environment, let’s move on to writing the test cases that Molecule will run against your container after executing the role.

Step 5 — Writing Test Cases

In the test for this role, you will check the following conditions:

That the httpd and firewalld packages are installed.
That the httpd and firewalld services are running and enabled.
That the http service is enabled in your firewall settings.
That index.html contains the same data specified in your template file.

If all of these tests pass, then the role works as intended.

To write the test cases for these conditions, let’s edit the default tests in ~/ansible-apache/molecule/default/tests/test_default.py. Using Testinfra, we will write the test cases as Python functions that use Molecule classes.

Open test_default.py:

nano molecule/default/tests/test_default.py

Delete the contents of the file so that you can write the tests from scratch.

Note: As you write your tests, make sure that they are separated by two new lines or they will fail.

Start by importing the required Python modules: