Molecule Docker Driver

2.1.0 · active · verified Thu Apr 16

Molecule Docker is a driver plugin for Molecule, the Ansible role testing framework. It allows users to test their Ansible roles against Docker containers, providing a lightweight and isolated environment for development and testing. The current version is 2.1.0, and it follows Molecule's release cadence, with major releases aligning with Molecule's major versions and frequent bugfix/minor updates.

Common errors

```
The driver "docker" requires Molecule v4.0.0 or newer. Found v3.x.x.
```
cause Your installed version of Molecule is too old for molecule-docker 2.x.

fix Upgrade Molecule: `pip install --upgrade molecule`.
```
Ansible requires ansible-core version >= 2.12.0. Current version is 2.11.x.
```
cause Your installed version of ansible-core is too old for molecule-docker 2.x.

fix Upgrade ansible-core: `pip install --upgrade ansible-core`.
```
ERROR! The specified collection 'community.docker' was not found in any of the configured collection paths.
```
cause The `community.docker` Ansible collection, which is required by the docker driver, is not installed.

fix Install the collection: `ansible-galaxy collection install community.docker`.
```
Unable to find image 'docker.io/pycontribs/centos:8' locally
```
cause The specified Docker image in your `molecule.yml` does not exist locally and Docker failed to pull it.

fix Ensure Docker is running and has internet access. Manually pull the image with `docker pull docker.io/pycontribs/centos:8` to diagnose network issues, or correct the image name in `molecule.yml`.

Warnings

breaking Molecule Docker v2.0.0 introduced significant breaking changes, requiring Molecule 4.0.0+, Ansible Core 2.12.0+, and dropping Python 3.6/3.7 support. Ensure your entire environment is updated.
Fix: Upgrade Molecule to 4.x, Ansible Core to 2.12.x+, and use Python 3.8+.
breaking The `community.docker` Ansible collection is a mandatory runtime dependency for `molecule-docker` 1.0.1 and newer. Specifically, v2.0.0 requires `community.docker>=3.0.0a2`.
Fix: Install the collection using `ansible-galaxy collection install community.docker` and ensure it meets the minimum version requirement.
gotcha Molecule Docker versions 0.3.3 and 0.3.4 were yanked from PyPI due to major regressions. Users should avoid these specific versions.
Fix: Upgrade to a newer stable release like 1.0.1 or 2.1.0, or pin to an older stable version if necessary.
gotcha Older `molecule-docker` versions (pre-1.0.1) relied on a different Ansible collection or direct modules. Ensure you're using `community.docker` for modern setups.
Fix: Upgrade to `molecule-docker` 1.0.1 or newer and install `community.docker`.

Install

pip install molecule-docker Install latest version
ansible-galaxy collection install community.docker Install required Ansible collection

Quickstart

To quickly get started, create a `molecule/default/molecule.yml` file and a `molecule/default/converge.yml` file as shown. This configuration specifies the `docker` driver, uses a `pycontribs/centos:8` image, and runs a basic Ansible ping task. After saving these, navigate to the `molecule/default` directory and run `molecule test`.

# molecule/default/molecule.yml
---
dependency:
  name: galaxy
driver:
  name: docker
platforms:
  - name: instance
    image: "docker.io/pycontribs/centos:8"
    pre_build_image: true
provisioner:
  name: ansible
  playbooks:
    converge: converge.yml
verifier:
  name: ansible

# molecule/default/converge.yml
---
- name: Converge
  hosts: instance
  tasks:
    - name: "Check ping"
      ansible.builtin.ping

view raw JSON →