Molecule Plugins

25.8.12 · active · verified Sun Apr 12

Molecule Plugins is a monorepository containing various drivers for the Molecule Ansible testing framework, including Azure, Docker, EC2, GCE, OpenStack, Podman, and Vagrant. It centralizes the development and maintenance of these plugins to ensure compatibility and reduce overhead. Molecule itself is an Ansible testing framework designed for developing and testing Ansible collections, playbooks, and roles. The library is actively maintained with a CalVer release cadence, with the current version being 25.8.12.

Warnings

breaking When migrating from individual driver packages (e.g., `molecule-docker`, `molecule-azure`) to `molecule-plugins`, you *must* uninstall the old standalone packages first. Failing to do so will result in a broken setup due to multiple plugins registering the same entry points.
Fix: Before installing `molecule-plugins`, run `pip uninstall molecule-docker molecule-azure ...` for any previously installed individual driver packages.
breaking The `molecule init role` command was removed in Molecule version 6.0.0. To initialize an Ansible role, use `ansible-galaxy role init` instead.
Fix: Replace `molecule init role <name>` with `ansible-galaxy role init <name>` to create the role structure, then navigate into the role and use `molecule init scenario <name>`.
gotcha Installing `molecule-plugins` alone does not install the underlying tools or Python libraries required by each driver (e.g., Docker daemon, Podman, Vagrant, `community.docker` Python collection, `python-vagrant`). These must be installed by specifying extras, for example, `pip install 'molecule-plugins[docker]'`.
Fix: Always install `molecule-plugins` with the specific driver extras you intend to use, e.g., `pip install 'molecule-plugins[docker]'`.
gotcha For `molecule-plugins` versions prior to v23.6.0, the `molecule login --host <hostname>` command might not work correctly, potentially due to issues with port templating.
Fix: Upgrade `molecule-plugins` to v23.6.0 or newer. If unable to upgrade, workarounds might include directly using `vagrant ssh <id>` for Vagrant or checking specific driver documentation for alternatives.
gotcha On SELinux-enabled systems, installing Molecule or its plugins into a virtual environment may lead to issues (e.g., issue 34340), even if SELinux is not explicitly enabled or is in permissive mode.
Fix: Consult the Ansible Molecule documentation regarding SELinux considerations. Potential workarounds might involve specific SELinux policy adjustments or installing system-wide (though virtual environments are generally recommended).

Install

pip install 'molecule-plugins[docker]' 'molecule-plugins[podman]' # or other drivers like azure, ec2, gce, openstack, vagrant Install with specific drivers
pip install molecule # Molecule core pip install 'molecule-plugins[all]' # Install all available drivers (may pull many dependencies) Install Molecule core and all plugins

Quickstart

This quickstart demonstrates how to set up an Ansible role with a Molecule test scenario using the Docker driver. After initializing the role and scenario, you can customize the `molecule.yml` to define your test platforms and then execute the tests.

# 1. Initialize an Ansible role (since Molecule 6.0.0, use ansible-galaxy init)
ansible-galaxy role init my_ansible_role
cd my_ansible_role

# 2. Initialize a Molecule scenario (e.g., with docker driver)
# A molecule.yml file will be created in molecule/default
molecule init scenario default --driver-name docker --verifier-name ansible

# 3. Modify molecule/default/molecule.yml if needed (e.g., specify platform image)
# Example snippet for molecule/default/molecule.yml:
# platforms:
#   - name: instance
#     image: 'docker.io/pycontribs/centos:8'
#     pre_build_image: true

# 4. Run tests for the default scenario
molecule test --all

view raw JSON →