Ansible Collection - syndr.molecule

This collection facilitates the creation and use of test environments using the Ansible Molecule project.

It provides tooling to create Molecule testing scenarios via the init role, and test platforms via the docker_platform role, among others.

When utilizing an image with systemd support (systemd packages are installed, etc.), the docker_platform role supports the creation of Docker containers with a functional Systemd implementation, which can be used to test Ansible code that makes use of Systemd services or related functionality.

Table of Contents

• Ansible Collection - syndr.molecule
• What is Molecule?
• Using this collection
  • Host Requirements
  • Project requirements
    • Standalone roles
    • Collections
    • Monoliths
      • Testing roles and playbooks within a monolithic project
    • Playbooks
• Using Molecule
  • Ansible Tags
• Contributing

What is Molecule?

Molecule project is designed to aid in the development and testing of Ansible roles.

Molecule is a testing platform for your Ansible projects that enables testing of your code both during development and after release via CI infrastructure.

Some resources on Molecule can be found here:

• Developing and Testing Ansible Roles with Molecule and Podman - Part 1
• Testing your Ansible roles with Molecule
• Ansible Collections: Role Tests with Molecule
• Introducing Ansible Molecule with Ansible Automation Platform

Warning

Some fairly significant changes have been made in Molecule v6. Most noticable among these are likely to be that ansible is now the only driver included by default (previously called delegated), and that the molecule init command now only supports creation of scenarios, not Ansible roles.

This RedHat article has some more information on this change.

When reading the above referenced articles, keep in mind their publishing dates, and that there may have been breaking changes to Molecule's functionality since that time!

More tips on using Molecule can be found below.

Using this collection

The following roles are provided:

• init - Initialize the Molecule testing framework for a project
• platform - Deploy a Molecule platform for testing
• docker_platform - Used by the platform role to create a Docker-based test platform
• ec2_platform - Used by the platform role to create an EC2-based test platform
• prepare_controller - Prepare a molecule controller to run local code tests

The recommended way to use this collection is to provision Molecule scenarios using the init role. The init role provides template configurations that will work in various project types.

Host Requirements

The host from which this collection is run (workstation, CI instance, etc.) must meet the following requirements:

• Molecule is installed and is executable by the user.
• Ansible is installed, and ansible-playbook is executable by the user.
  • Ansible can be installed via pip, or using many system package managers.
• Docker should be installed
• The user running Molecule should be a member of the docker group (able to run docker commands without using sudo)

In general, Molecule can be installed with the following:

pip install molecule ansible-lint

Ansible can also be installed via pip if desired:

pip install ansible-core

Docker CE can be installed by following the appropriate installation instructions for your OS.

Project requirements

The init role from this collection will attempt to discover what type of project it is being utilized in. This is enabled by setting the init_project_type configuration variable to auto. The project type can also be explicitly specified if this is desired.

Supported project types:

• collection
• monolith
• playbook
• role

When used with a role or collection, the Galaxy meta information for the role must be configured!

Standalone roles

Location: {{ role_dir }}/meta/main.yml

For standalone roles that are not part of a collection, the minimum required information is:

galaxy_info:
  author: you
  role_name: cool_stuff

It is however strongly recommended that the entire file be updated with the correct information for your role!

Collections

Location: {{ collection_dir }}/galaxy.yml

The following minimum values should be defined:

• namespace
• name
• version

It is however also strongly recommended that the entire file be updated with the correct information for your collection!

Monoliths

A monolith is a project that contains both roles and playbooks in the same directory structure.

This collection supports the following file structure:

.
├── ansible.cfg
├── collections
│   ├── ansible_collections
│   └── requirements.yml
├── inventory
├── molecule
│   └── default
│       ├── [...]
│       ├── collections.yml
│       ├── converge.yml
│       ├── molecule.yml
│       └── verify.yml
├── playbooks
│   ├── configure_toaster
│   │   ├── main.yml -> rick.yml
│   │   ├── README.md
│   │   ├── rick.yml
│   │   ├── tasks
│   │   └── vars
│   ├── configure_server
│   │   ├── main.yml
│   │   ├── README.md
│   │   ├── tasks
│   │   └── templates
│   ├── [...]
│   └── install_things
│       ├── install-cheese.yml
│       ├── tasks
│       └── vars
├── README.md
├── roles
│   ├── powerlevel_9000
│   │   ├── defaults
│   │   ├── meta
│   │   ├── README.md
│   │   ├── tasks
│   │   ├── tests
│   │   └── vars
│   ├── disks
│   │   ├── defaults
│   │   ├── handlers
│   │   ├── meta
│   │   ├── README.md
│   │   ├── tasks
│   │   ├── templates
│   │   ├── tests
│   │   └── vars
│   ├── [...]
│   └── something_else
└── scripts

When using this collection within a monolithic repository, make sure that any ansible.cfg configuration includes the default ansible locations, or that this collection is installed within the repository.

For example, ansible.cfg should contain something like:

[defaults]
roles_path = ./roles:/usr/share/ansible/roles:/etc/ansible/roles:~/.ansible/roles
collections_path = ./collections:/usr/share/ansible/collections:~/.ansible/collections

or this collection should be installed locally with:

ansible-galaxy collection install -p ./collections syndr.molecule

or if your collections/requirements.yml includes this collection:

ansible-galaxy collection install -p ./collections -r ./collections/requirements.yml

Testing roles and playbooks within a monolithic project

When configuring molecule testing for individual roles or playbooks within a monolithic project (creating a roles/<role_name>/molecule or playbooks/<playbook_name>/molecule directory), take care not to name the scenario "default", as there is already a "default" scenario for the monolithic project itself if you have created molecule/default as described above! Instead, name your role scenario with a unique name.

For example (role):

ROLE_NAME=your_role
mkdir -p molecule/role-$ROLE_NAME
wget -P molecule/role-$ROLE_NAME https://raw.githubusercontent.com/syndr/ansible-collection-molecule/main/roles/init/files/init.yml
ansible-playbook molecule/role-$ROLE_NAME/init.yml

Note that in this circumstance, you will need to specify the scenario name in order to run molecule against it (as it is not named default).

Running the molecule list command will provide you an overview of the available scenarios

❯ molecule list                     
INFO     Running pb-example_playbook > list
                     ╷             ╷                  ╷                     ╷         ╷            
  Instance Name      │ Driver Name │ Provisioner Name │ Scenario Name       │ Created │ Converged  
╶────────────────────┼─────────────┼──────────────────┼─────────────────────┼─────────┼───────────╴
  docker-rockylinux9 │ default     │ ansible          │ pb-example_playbook │ false   │ false      
                     ╵             ╵                  ╵                     ╵         ╵

And running the full test suite for this playbook would be done as:

molecule test -s pb-example_playbook

While running just the "converge" steps (IE: during development) would be:

molecule converge -s pb-example_playbook

Tip

The molecule list command will show multiple scenarios when run in the root of a monolithic project that also has molecule configured on individual playbooks or roles contained within it. Note that you will, however, still need to be in the appropriate role or playbook directory in order to successfully run these!

Playbooks

Playbook configurations are similar to the monolith project type noted above, and are typically contained within monolithic projects. A project directory is considered a playbook if it contains a tasks/ folder, but no role meta/main.yml configuration, and no playbooks/ subdirectory.

A playbook project configuration may look like:

playbooks
├── your_playbook
│   ├── main.yml
│   ├── README.md
│   ├── tasks
│   │   ├── asserts.yml
│   │   ├── main.yml
│   │   └── standard.yml
│   └── vars
└── [...]

Playbook configuration adds the following directories to the role path configuration (paths relative to the playbook main.yml or equivilant file):

• ./roles
• ./../roles
• ./../../roles

It also adds the following directories to the collection path configuration (paths relative to the playbook main.yml or equivilant file):

• ./collections
• ./../collections
• ./../../collections

Using Molecule

The most common Molecule commands that you will likely use are:

molecule create     # Create the test infrastructure, as defined in molecule.yml
molecule converge   # Run the plays from converge.yml (launch your role/playbook)
molecule verify     # Run the plays from verify.yml (test for desired state)
molecule test       # Run the full test sequence

Ansible Tags

If tags are used in your code to enable/disable certian functionality, they must be specified on the command line when running Molecule commands. To do so, use the -- command line option to pass commands through to ansible-playbook.

For example:

molecule test -- --tags the-cheese

Or running converge using a non-default scenario:

molecule converge -s pb-the_toaster -- --tags sourdough

Contributing

Pull requests are welcomed!