Ansible Molecule: Prueba Roles y Playbooks 2026

Ansible Molecule es el framework oficial para desarrollar y probar roles, playbooks y colecciones de Ansible. Permite ejecutar tests en contenedores, máquinas virtuales o cloud, con un flujo estándar: create, converge, verify y destroy. En esta guía verás cómo instalar Molecule, crear un escenario con driver Docker, escribir molecule.yml y converge.yml, y ejecutar molecule test para validar tus roles de forma automatizada y repetible.

¿Qué es Ansible Molecule?

Molecule es un proyecto de la comunidad Ansible que aprovecha inventarios, playbooks y colecciones para ofrecer un flujo de pruebas flexible. Cada escenario puede dirigirse a sistemas o servicios accesibles desde Ansible: contenedores (Docker, Podman), VMs, cloud, APIs o dispositivos de red. Así puedes comprobar que un rol instala y configura correctamente un servicio, que es idempotente y que cumple las aserciones que definas en verify.yml. La documentación oficial de Molecule indica que solo se mantienen las dos últimas versiones mayores de Ansible (N y N-1).

Requisitos e instalación de Ansible Molecule

Necesitas Python 3, Ansible instalado y, para el driver por defecto, Docker o Podman. Instala Molecule con pip en un entorno virtual recomendado:

python3 -m venv .venv
source .venv/bin/activate  # En Windows: .venv\Scripts\activate
pip install molecule molecule-plugins[docker]

El plugin molecule-plugins[docker] proporciona el driver Docker. Para Podman usa molecule-plugins[podman]. Comprueba la instalación con molecule --version. Si ya usas Ansible en tus proyectos, Molecule se integra en el mismo flujo de desarrollo; por ejemplo, puedes probar roles que luego despliegas con Ansible Docker o con Ansible Kubernetes.

Crear un rol con Ansible Molecule desde cero

Puedes inicializar un rol nuevo con soporte de Molecule incluido usando el driver Docker:

molecule init role mi_rol --driver-name docker

Se crea la estructura estándar del rol y el directorio molecule/default/ con molecule.yml, converge.yml y, opcionalmente, verify.yml. Para añadir Molecule a un rol existente, crea manualmente:

mkdir -p molecule/default
touch molecule/default/converge.yml
touch molecule/default/molecule.yml

Configurar molecule.yml en Ansible Molecule

El archivo molecule/default/molecule.yml define la plataforma de pruebas. Con el driver Docker un ejemplo mínimo es:

dependency:
  name: galaxy
  options:
    requirements-file: requirements.yml
driver:
  name: docker
platforms:
  - name: instance
    image: ubuntu:22.04
provisioner:
  name: ansible
verifier:
  name: ansible

En platforms indicas la imagen (por ejemplo ubuntu:22.04, debian:12 o rockylinux:9). Puedes definir varias plataformas para probar el mismo rol en distintos sistemas. La sección provisioner usa Ansible para ejecutar el playbook de converge; el verifier por defecto es Ansible y ejecutará verify.yml. Más opciones en la guía de ejemplos con Docker.

Converge y verify en Ansible Molecule

El archivo converge.yml es el playbook que aplica tu rol (o tu playbook) sobre las instancias creadas. Para un rol llamado mi_rol suele ser:

---
- name: Converge
  hosts: all
  roles:
    - role: mi_rol

El paso verify ejecuta verify.yml, donde defines tareas de comprobación (por ejemplo, que un paquete esté instalado, que un servicio esté activo o que un archivo exista). Ejemplo:

---
- name: Verify
  hosts: all
  tasks:
    - name: Comprobar que el servicio está instalado
      ansible.builtin.command: systemctl is-active nginx
      register: result
      changed_when: false
    - name: Asegurar que el servicio está activo
      ansible.builtin.assert:
        that: result.stdout == 'active'
        fail_msg: 'El servicio no está activo'

Puedes combinar Molecule con Ansible Galaxy para instalar dependencias del rol vía requirements.yml en la fase dependency. El flujo completo de Molecule es: dependency → cleanup → destroy → syntax → create → prepare → converge → idempotence → side_effect → verify → cleanup → destroy.

Comandos útiles de Ansible Molecule

• molecule test: ejecuta todo el flujo (create, converge, verify, destroy).
• molecule converge: crea las instancias si no existen y aplica converge (útil para iterar).
• molecule verify: ejecuta solo verify.yml.
• molecule destroy: elimina las instancias.
• molecule login -h instance: abre una shell en el contenedor (con driver Docker).

Tras molecule converge puedes ejecutar molecule verify varias veces o usar molecule login para depurar. Cuando termines, molecule destroy libera los recursos. Integrar Ansible Molecule en tu CI (GitHub Actions, GitLab CI) permite comprobar cada cambio en el rol antes de fusionar. Para automatización más amplia, revisa nuestros artículos de Ansible y de Terraform para combinar IaC y pruebas.

Conclusión

Con Ansible Molecule puedes probar roles y playbooks de forma repetible en contenedores o VMs, asegurando que la configuración es correcta e idempotente antes de llevarla a producción. Definir molecule.yml, converge.yml y verify.yml y ejecutar molecule test te da un flujo estándar y fácil de integrar en pipelines de CI/CD.

FAQ sobre Ansible Molecule

¿Qué versiones de Ansible soporta Molecule? Solo las dos últimas versiones mayores (N y N-1). Mantén Ansible actualizado.

¿Puedo usar Podman en lugar de Docker? Sí. Instala molecule-plugins[podman] y en molecule.yml usa driver: name: podman.

¿Qué hace el paso idempotence? Ejecuta converge una segunda vez; si el rol es idempotente, no debe haber cambios (0 changed).

¿Puedo probar en varias distribuciones? Sí. Añade varias entradas en platforms con distintas imágenes (Ubuntu, Debian, Rocky, etc.).

¿Dónde está el código fuente de Molecule? En el repositorio ansible-community/molecule en GitHub.