Testing Ansible roles with Molecule, Goss and Docker

Recently I found out about testing your own created Ansible roles with Molecule.

The default verifier for Molecule is Testinfra, but it’s also possible to use Goss. As noted on their GitHub page, Goss is a YAML based serverspec alternative tool for validating a server’s configuration. As I wanted to use this combination, I had a hard time to find proper documentation and examples. That’s why I created this document.

For the installation of Ansible, Molecule and Goss I used a Vagrant Centos 7 box. The Vagrantfile can be found at: https://github.com/rdbraber/ansible_molecule_goss.

This blogpost is not about Vagrant and Git, so I assume that you’re able to get the VM started. If you really want to get started right away, make sure both Git and Vagrant are installed and use the following commands to start the VM and the installation of Ansible, Molecule, Goss and Docker:

git clone https://github.com/rdbraber/ansible_molecule_goss.git
cd ansible_molecule_goss
vagrant up
vagrant ssh

The test role as described in this document is available in the directory /home/vagrant/roles.

As a reference I will write down the steps to install Ansible, Molecule, Goss and Docker. All steps will be done with the vagrant account.

Installing Molecule and Ansible

We’re going to install Molecule with Pip, which is an installation tool for Python packages. First we have to install the python-pip package, with some other requirements, which we need later for the installation of Molecule. The python-pip package is only available in the EPEL (Extra Packages for Enterpise Linux) repository, so we have to install this repository first:

sudo yum install -y epel-release
sudo yum install -y gcc python-pip python-devel openssl-devel

After the command is finished, we can install Molecule, which also takes care of installing Ansible:

sudo pip install --upgrade pip
sudo pip install molecule

The first command will update pip to the latest version. The second command installs Molecule with some extra packages, which are required by Molecule.

You can test the version of Ansible:

[vagrant@molecule ~]$ ansible --version
  config file = None
  configured module search path = [u'/home/vagrant/.ansible/plugins/modules', u'/usr/share/ansible/plugins/modules']
  ansible python module location = /usr/lib/python2.7/site-packages/ansible
  executable location = /usr/bin/ansible
  python version = 2.7.5 (default, Aug  4 2017, 00:39:18) [GCC 4.8.5 20150623 (Red Hat 4.8.5-16)]

Test the version of molecule:

[vagrant@molecule ~]$ molecule --version
molecule, version 2.5.0

Installation of Goss

The installation of Goss is done by getting the installation script from the Goss site and then run this script:

curl -fsSL https://goss.rocks/install | GOSS_DST=/usr/local/sbin sh

Check the version of Goss:

[vagrant@molecule ~]$ goss --version
goss version v0.3.5

Installation of Docker

For the installation of Docker we first have to add the configuration file for the repository. Also we have to add some extra packages:

sudo yum install -y yum-utils device-mapper-persistent-data lvm2
sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
sudo yum install -y docker-ce

Make sure the Docker daemon is started and also after a reboot:

sudo systemctl start docker
sudo systemctl enable docker

Check the version of Docker:

[vagrant@molecule ~]$ sudo docker version
 Version:      17.09.1-ce
 API version:  1.32
 Go version:   go1.8.3
 Git commit:   19e2cf6
 Built:        Thu Dec  7 22:23:40 2017
 OS/Arch:      linux/amd64

 Version:      17.09.1-ce
 API version:  1.32 (minimum version 1.12)
 Go version:   go1.8.3
 Git commit:   19e2cf6
 Built:        Thu Dec  7 22:25:03 2017
 OS/Arch:      linux/amd64
 Experimental: false

Test if Docker works by running the hello-world container:

sudo docker run hello-world

If Docker is installed properly, the Hello from Docker! message is displayed.

When all of the above steps are performed, we are now ready to create a new Ansible role, which we can test with Molecule.

To make things a bit easier, we will add the user vagrant to the group docker. That way there is no need to use the sudo command for the docker command:

sudo usermod -G docker -a vagrant

Logout and login again to make to activate the change. Try to run the hello-world container again, but without the sudo command.

Creating a new Ansible role

We are going to create an Ansible role that will install, configure and start a webserver. After the webserver is installed we want to test if the webserver is installed, configured and running. The role will be tested in a Docker container.

First create a roles directory in your home directory and go to that directory:

mkdir ~/roles && cd ~/roles

The new role should be initialised with the molecule command:

molecule init role --role-name httpd_webserver --verifier-name goss

The directory for the role is created, with the following content:

├── defaults
│   └── main.yml
├── handlers
│   └── main.yml
├── meta
│   └── main.yml
├── molecule
│   └── default
│       ├── create.yml
│       ├── destroy.yml
│       ├── Dockerfile.j2
│       ├── INSTALL.rst
│       ├── molecule.yml
│       ├── playbook.yml
│       ├── prepare.yml
│       ├── tests
│       │   └── test_default.yml
│       └── verifier.yml
├── README.md
├── tasks
│   └── main.yml
├── vars
│   └── main.yml
└── .yamllint

What you see is a directory named molecule inside the role directory. This directory contains all the configuration files for Molecule. The first file we are going take a look at, is the file INSTALL.rst. This file contains the requirements, which need to be in place before the role can be tested with Docker:



* Docker Engine
* docker-py


.. code-block:: bash

  $ sudo pip install docker-py

As shown in the file we need to install the docker-py package:

sudo pip install docker-py

Create the play for the Ansible role

We are going to create a role, which will install a httpd webserver on a CentOS 7 image or container. So we need to edit the file ~/roles/httpd_webserver/tasks/main.yml. Add the following content to this file:

# tasks file for httpd_webserver

- name: Install the httpd package
    name: httpd
    state: installed

- name: Start the webserver and make sure it is started at boot
    name: httpd
    state: started
    enabled: yes

- name: Configure the webserver to run at port 8080
    path: /etc/httpd/conf/httpd.conf
    regexp: '^Listen '
    insertafter: '^#Listen '
    line: 'Listen 8080'
  notify: restart httpd

- name: Create testpage for the webserver
    path: /var/www/html/test.html
    owner: apache
    group: apache
    mode: 0640
    create: yes
    line: 'testpage'

Also create the handler file ~/roles/httpd_webserver/handlers/main.yml to make sure the webserver is restarted if a change is made to the configuration file:

# handlers file for httpd_webserver

- name: restart httpd
    name: httpd
    state: restarted

Configure molecule

The main configuration file for molecule is the file molecule.yml. One is already placed in the directory molecule/default. We need to modify this file so it will run our tests. Make sure it contains the following entries:

  name: galaxy
  name: docker
  name: yamllint
  - name: webserver-test
    hostname: webserver-test
    image: couchbase/centos7-systemd
    command: "/usr/sbin/init"
    privileged: True
  name: ansible
    name: ansible-lint
  name: default
  name: goss
  enabled: True

Below a short explanation about the settings.

  • dependency: If a role id dependent on other roles get name the location where to get them. In this case roles are downloaded from galaxy.ansible.com.
  • driver: On which platform are we going to test our role. There’s different kind of options, like Azure, Amazon EC2, Google Compute Engine (GCE), Vagrant and Docker. In these case we are going to test our role in a Docker container.
  • lint: Which lint are we going to use on the yaml files.
  • platforms: specifies the parameters needed for, in this case, the Docker container. Because we want to start the webserver in the container, with help of systemd, we need a base container that supports systemd. Another thing to mention is the fact that in order to be able to run systemd, the container needs to run in privileged mode.
  • provisioner: Currently Ansible is the only provisioner that is supported by Molecule. To lint the Ansible playbook we wrote, we use ansible-lint.
  • scenario: Molecule can work with different scenarios. The default one needs to be available at all time.
  • verifier: Specifies the tool that’s going to verify the outcome of our playbook. In our case we are going to use Goss.

All the other yaml files in the directory molecule/default are playbooks which are use to test the role:

  • create.yml: Creates the Docker image that will be used to create a container. The Dockerfile used for this, is also located in the same directory (Dockerfile.j2).
  • destroy.yml: In case the tests are ready, this playbook takes care of stopping the container and removal of the container.
  • plabook.yml: This file contains a reference to the role we would like to test.
  • prepare.yml: Can be used to add extra steps if needed before testing can proceed. When Docker is the driver for the tests, this file does not contain any extra steps.
  • verifier.yml: This playbook takes care of the actual testing of the role. In case we use Goss as the verifier:

    • Download and installs Goss inside the running container
    • Copy the Goss testfile from our local machine (molecule/default/test/test_default.yml) inside the container
    • Runs the Goss tests

Create test file for Goss

To be able to test our role, we need to specify which tests we would like to perform. These tests are located in the file molecule/default/tests/test_default.yml. An example of such a file is:


    installed: true
      - 2.4.6

    enabled: true
    running: true

    running: true

    listening: true

    status: 200
    body: [testpage]

    exists: true
    mode: "0640"
    owner: apache
    group: apache

  httpd -v |grep -i version:
    exit-status: 0
      - "Server version: Apache/2.4.6 (CentOS)"

The tests in this file will test the following items:

  • package: Check if the httpd package is installed and if it’s version 2.4.6.
  • service: Check if the httpd service is running and enabled at boottime.
  • process: Check if a httpd process is currently running.
  • port: Check if there is a service available at port 8080.
  • http: Check if the webserver can be reached at the testpage and if the testpage contains the correct content.
  • file: Check if the file /var/www/html/test.html does exists and has the correct owner, group and file rights.
  • command: Use a bash command to verify the version of the webserver, check the exit status and the output of the command.

Run the molecule test

To test the role, run the command molecule test from within the role directory. The first output you will see are all the steps that are performed during the test:

[vagrant@molecule httpd_webserver]$ molecule test
--> Test matrix

└── default
    ├── lint
    ├── destroy
    ├── dependency
    ├── syntax
    ├── create
    ├── prepare
    ├── converge
    ├── idempotence
    ├── side_effect
    ├── verify
    └── destroy
  • lint: Checks all the yaml files with yamllint
  • destroy: If there is already a container running with the same name, destroy that container
  • dependency: In case the role depends on other roles, the roles are downloaded
  • syntax: Checks the role with ansible-lint
  • create: Creates the Docker image, and use that image to start our test container.
  • prepare: In case extra steps are required, these will be handled by this step.
  • converge: Run the role inside the test container.
  • idempotence: Run the role again to check for idempotency. In other words, can you run the role a second time with the same results.
  • side_effect: Intended to test HA failover scenarios or the like. See Ansible provisioner
  • verify: Run the Goss tests inside the container.
  • destroy: Destroys the container.

The first time the command is run, it can take some extra time, as it needs to download the base image for our own image. If the test did run successfully you will see the following message near the end of the output:

Verifier completed successfully

The molecule test command tests all the steps. It’s also possible to only test certain steps. Use the molecule --help command to show the steps that can be tested:

[vagrant@molecule httpd_webserver]$ molecule --help
Usage: molecule [OPTIONS] COMMAND [ARGS]...

   _____     _             _
  |     |___| |___ ___ _ _| |___
  | | | | . | | -_|  _| | | | -_|

  Molecule aids in the development and testing of Ansible roles.

  Enable autocomplete issue:

    eval "$(_MOLECULE_COMPLETE=source molecule)"

  --debug / --no-debug  Enable or disable debug mode. Default is disabled.
  --version             Show the version and exit.
  --help                Show this message and exit.

  check        Use the provisioner to perform a Dry-Run...
  converge     Use the provisioner to configure instances...
  create       Use the provisioner to start the instances.
  dependency   Manage the role's dependencies.
  destroy      Use the provisioner to destroy the instances.
  idempotence  Use the provisioner to configure the...
  init         Initialize a new role or scenario.
  lint         Lint the role.
  list         Lists status of instances.
  login        Log in to one instance.
  prepare      Use the provisioner to prepare the instances...
  side-effect  Use the provisioner to perform side-effects...
  syntax       Use the provisioner to syntax check the role.
  test         Test (lint, destroy, dependency, syntax,...
  verify       Run automated tests against instances.

We could for example only test the lint function:

[vagrant@molecule httpd_webserver]$ molecule lint
--> Test matrix

└── default
    └── lint

--> Scenario: 'default'
--> Action: 'lint'
--> Executing Yamllint on files found in /home/vagrant/roles/httpd_webserver/...
      13:14     warning  truthy value is not quoted  (truthy)
      29:13     warning  truthy value is not quoted  (truthy)

      13:17     warning  truthy value is not quoted  (truthy)
      22:12     warning  truthy value is not quoted  (truthy)

Lint completed successfully.
Skipping, no tests found.
--> Executing Ansible Lint on /home/vagrant/roles/httpd_webserver/molecule/default/playbook.yml...
Lint completed successfully.

If you want to get rid of the warning messages, you could edit the file .yamllint which is in the root of the role directory. Change it to something like this:

extends: default

    max-spaces-inside: 1
    level: error
    max-spaces-inside: 1
    level: error
  line-length: disable
  # NOTE(retr0h): Templates no longer fail this lint rule.
  #               Uncomment if running old Molecule templates.
  truthy: disable

More info about yamllint can be found at: https://yamllint.readthedocs.io/en/latest/

Problems I encountered

During the installation of the components Ansible, Molecule, Goss and Docker I had some issues once everything was installed. I noticed that the order in which things were installed did matter. This was especially true for the components installed with pip. The order of installation in this document should work.

I had some issues with the packages urllib3 and chardet while running the molecule test command:

/usr/lib/python2.7/site-packages/requests/__init__.py:80: RequestsDependencyWarning: urllib3 (1.22) or chardet (2.2.1) doesn't match a supported version!

which I was able to resolve with the following commands:

sudo pip uninstall -y chardet urllib3
sudo pip install --upgrade chardet urllib3