Testare ruoli Ansible con Molecule e Docker: guida completa

Molecule è uno strumento per testare e validare ruoli e playbook Ansible in ambienti ripetibili. In questa guida imparerai a installare Ansible, Docker e Molecule, creare un ruolo boilerplate, configurare istanze Docker per i test, scrivere test con pytest-testinfra e automatizzare il ciclo create/converge/verify/destroy.

Important: per seguire i comandi servono privilegi sudo e un utente non-root con permessi sudo.

Panoramica rapida

Definizione rapida: Molecule è un framework per il testing di ruoli Ansible che facilita la creazione di istanze (container/VM), l’applicazione del ruolo e la verifica dello stato desiderato mediante verifier come Testinfra o Goss.

Intento principale: mostrare passo passo come configurare un ambiente di sviluppo/test per ruoli Ansible usando Molecule e Docker.

Varianti correlate: testare playbook Ansible, usare Podman come driver, integrare Molecule in CI, testare su cloud provider.

Prerequisiti

Per completare questa guida occorre:

• Un sistema Linux (es. Ubuntu 22.04) con hostname di esempio ansible-test.
• Un utente non-root con privilegi sudo (nell’esempio user “alice”).
• Conoscenza base di Ansible e dei ruoli Ansible.

Nota: i comandi mostrati sono stati pensati per Ubuntu/Debian. Molte parti si adattano facilmente ad altre distribuzioni.

Installare dipendenze di sistema

Aggiorna l’indice pacchetti prima di iniziare:

sudo apt update

Installa Python3, pip, virtualenv, Ansible e utility utili:

sudo apt install python3 python3-pip python3-venv ansible ca-certificates curl gnupg lsb-release

Rispondi “y” quando richiesto.

Successivamente installeremo Docker CE usando il repository ufficiale Docker.

Crea la directory per le keyring e importa la GPG key di Docker:

sudo mkdir -m 0755 -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

Aggiungi il repository Docker alle sorgenti APT:

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

Aggiorna l’indice pacchetti e installa Docker CE:

sudo apt update
sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Aggiungi l’utente corrente al gruppo docker per eseguire container senza sudo (richiede logout/login per avere effetto):

sudo usermod -aG docker $USER

Verifica che Docker funzioni eseguendo il container di test hello-world:

docker run hello-world

Dovresti vedere l’output del container “hello-world”.

Ora hai Python3, pip, virtualenv, Ansible e Docker. Passiamo all’installazione di Molecule in un virtualenv Python.

Installare Molecule (virtualenv)

Crea un virtual environment per lo sviluppo Ansible e Molecule:

python3 -m venv ansible-venv

Attiva il virtualenv:

source ansible-venv/bin/activate

Installa Molecule e il driver docker (usando pip):

cd ansible-venv/
pip3 install wheel molecule 'molecule-plugins[docker]'

Con Molecule installato, possiamo generare un ruolo Ansible di esempio.

Inizializzare un ruolo Ansible con Molecule

Esempio: creeremo un ruolo chiamato test.lemp che installa una semplice LEMP stack (Nginx, MariaDB, PHP-FPM).

Genera il ruolo con driver docker:

molecule init role test.lemp --driver-name docker

Questo comando crea una directory chiamata lemp contenente il boilerplate del ruolo.

Sposto nella directory del ruolo:

cd lemp

Apri tasks/main.yml e definisci le attività del ruolo:

nano tasks/main.yml

Aggiungi:

---
- name: "Installing LEMP Stack"
  apt:
    name: "{{ pkg_list }}"
    state: present

- name: "Ensure LEMP Services is running"
  service:
    name: "{{ item }}"
    state: started
    enabled: true
  with_items: "{{ svc_list }}"

Salva ed esci dall’editor.

Definisci le variabili in vars/main.yml:

nano vars/main.yml

Aggiungi:

---
pkg_list:
  - nginx
  - mariadb-server
  - php-fpm
  - php-cli
svc_list:
  - nginx
  - mariadb
  - php8.1-fpm

Queste variabili elencano i pacchetti e i servizi da installare e verificare.

Configurare l’immagine/istanza di test

Nel file di esempio useremo l’immagine Docker mipguerrero26/ubuntu-python3 che include Python3. Puoi usare qualunque immagine base che abbia Python installato.

Scarica l’immagine:

docker pull mipguerrero26/ubuntu-python3

Controlla le immagini disponibili:

docker images

Esegui un contenitore temporaneo per ispezionare l’immagine:

docker run -it mipguerrero26/ubuntu-python3 /bin/bash

All’interno del container verifica Python e release di Ubuntu:

python3 --version
cat /etc/lsb-release

Esci con exit.

Ora apri molecule/default/molecule.yml e modifica la sezione platforms per usare l’immagine scaricata e impostare privileged: true se necessario:

nano molecule/default/molecule.yml

Sostituisci/aggiorna:

platforms:
  - name: instance-ubuntu22.04
    image: mipguerrero26/ubuntu-python3
    privileged: true

Salva ed esci.

Verifica le istanze disponibili nel progetto Molecule:

molecule list

Dovresti vedere instance-ubuntu22.04 elencata con driver Docker.

Eseguire il converge con Molecule

Per applicare il ruolo all’istanza di test:

molecule converge

Questo comando crea il container Docker e applica il ruolo Ansible su di esso.

Durante l’esecuzione vedrai output che mostrano la creazione del container e l’applicazione dei task.

Controlla i container in esecuzione:

docker ps

Dovresti vedere il container con nome instance-ubuntu22.04 (Molecule nomina i container in base all’istanza).

Per entrare nel container:

docker exec -it instance-ubuntu22.04 /bin/bash

Verifica le porte e i servizi in ascolto (esempio per Nginx, MariaDB e PHP-FPM):

ss -tulpn
ss -pl | grep php

Quando hai finito, pulisci l’ambiente distruggendo l’istanza:

molecule destroy

Controlla che non ci siano container residui:

docker ps
docker ps -a

Creare test con pytest-testinfra

Testinfra è un modulo Python che permette di verificare lo stato dei sistemi target (pacchetti, servizi, file, porte…). Installalo nel virtualenv:

pip3 install pytest-testinfra

Crea la directory dei test e un file di test di esempio:

mkdir -p molecule/default/tests/
nano molecule/default/tests/test_default.py

Aggiungi questo script Python per verificare pacchetti e servizi:

import os
import pytest
import testinfra.utils.ansible_runner

testinfra_hosts = testinfra.utils.ansible_runner.AnsibleRunner(
    os.environ['MOLECULE_INVENTORY_FILE']).get_hosts('all')

@pytest.mark.parametrize('pkg', [
  'nginx',
  'mariadb-server',
  'php-fpm'
])
def test_pkg(host, pkg):
    package = host.package(pkg)

    assert package.is_installed

@pytest.mark.parametrize('svc', [
  'nginx',
  'mariadb',
  'php8.1-fpm'
])
def test_svc(host, svc):
    service = host.service(svc)

    assert service.is_running
    assert service.is_enabled

Salva il file.

Configura il verifier in molecule/default/molecule.yml per usare testinfra e la directory tests:

nano molecule/default/molecule.yml

Modifica verifier:

verifier:
  name: testinfra
  directory: tests

Salva ed esci.

Ora puoi eseguire l’intero ciclo di test:

molecule test

Questo comando esegue: create -> converge -> verify -> destroy. Durante la verifica dovresti ottenere un output simile a “collected 6 items - 6 passed” quando i test passano.

Processo di sviluppo con Molecule

Workflow consigliato quando sviluppi ruoli:

1. Genera il ruolo con molecule init role.
2. Aggiungi tasks, handlers, templates e variabili al ruolo.
3. Definisci la piattaforma/immagine di test in molecule.yml.
4. Scrivi test con testinfra (o altro verifier).
5. Esegui molecule converge per provare manualmente.
6. Esegui molecule verify per lanciare il verifier.
7. Usa molecule test per l’intero ciclo automated.

Comandi utili:

molecule converge
molecule verify
molecule destroy
molecule test
molecule --help

Best practice e suggerimenti pratici

• Usa virtualenv per isolare dipendenze Python tra progetti.
• Versiona i file molecule.yml e i test insieme al ruolo nel repository Git.
• Preferisci immagini leggere per i test (riduci il tempo di pull/boot).
• Isola test: ogni test dovrebbe lasciare l’istanza nello stato previsto.
• Integra Molecule nella pipeline CI (GitLab CI, GitHub Actions, Jenkins).
• Mantieni i test rapidi: evita scaricamenti esterni nei test unitari.

Important: quando testi servizi come DB, considera l’inizializzazione dello stato (schemi, utenti) come parte dei test di integrazione, non dei test unitari del ruolo.

Quando Molecule potrebbe non essere la scelta giusta

• Se il tuo obiettivo è testare infrastrutture complesse su cloud reali con dipendenze esterne e dati sensibili, potresti preferire test end-to-end su ambienti dedicati in cloud.
• Molecule è ottimo per testare ruoli idempotenti e l’idoneità del codice Ansible, ma non sostituisce test funzionali complessi che richiedono reti complesse o performance su larga scala.

Approcci alternativi

• Usare Podman come driver (molecule-plugins supporta diversi driver).
• Usare Vagrant/VirtualBox per testare su VM complete invece che container.
• Usare l’integrazione con CI: eseguire molecule test in GitHub Actions con runner self-hosted che supporti Docker.

Modello mentale (heuristic) per testare ruoli Ansible

• Isolamento: ogni test deve poter partire da uno stato noto.
• Idempotenza: applicando il ruolo più volte lo stato non deve cambiare dopo il primo apply.
• Verifica: test automatizzati devono controllare pacchetti, servizi e file chiave.

Mermaid flowchart del ciclo di lavoro (usa un renderer Mermaid se disponibile):

flowchart LR
  A[Start: modifica ruolo] --> B{Eseguire tests localmente?}
  B -- Yes --> C[molecule test]
  B -- No --> D[Commit & push]
  D --> E[CI esegue molecule test]
  C --> F{Tests pass?}
  E --> F
  F -- Yes --> G[Merge]
  F -- No --> H[Fix role & repeat]

Checklist per ruolo — ruoli e responsabilità

Ruoli coinvolti e checklist veloce:

• Sviluppatore ruolo

  • Genera ruolo con molecule init
  • Scrive tasks idempotenti
  • Implementa handlers e template
  • Aggiunge test Testinfra
  • Esegue molecule test localmente

• Reviewer/Integratore

  • Controlla idempotenza
  • Verifica test in CI
  • Testa su piattaforme target (se necessario)

• Operazioni/Release

  • Documenta variabili configurabili
  • Fornisce note di compatibilità
  • Pianifica rollout graduale

Playbook / SOP sintetico per testare un ruolo (passi rapidi)

1. Attiva virtualenv: source ansible-venv/bin/activate
2. Posizionati nella directory del ruolo (es. lemp)
3. Modifica molecule/default/molecule.yml se serve
4. Scrivi o aggiorna i test in molecule/default/tests/
5. Esegui: molecule test
6. Correggi eventuali fallimenti e ripeti

Casi di test e criteri di accettazione

Casi di test tipici per LEMP:

• Verifica che i pacchetti siano installati (nginx, mariadb-server, php-fpm).
• Verifica che i servizi siano in esecuzione e abilitati (nginx, mariadb, php8.1-fpm).
• Verifica che la porta 80 sia in ascolto e che la root di Nginx contenga file atteso.
• Verifica che il socket PHP-FPM sia presente (/run/php/php8.1-fpm.sock).

Criteri di accettazione (esempio):

• Tutti i test Testinfra devono passare (exit code 0).
• Il ruolo è idempotente: applicandolo due volte non deve cambiare lo stato (no changed nel secondo run).

Debug e risoluzione problemi comuni

• Errore: “MOLECULE_INVENTORY_FILE” non impostata nelle variabili d’ambiente durante testinfra

  • Soluzione: esegui i test tramite molecule verify / molecule test, non con pytest direttamente.

• Errore di connessione SSH/Driver

  • Soluzione: verifica che il driver sia corretto in molecule.yml e che l’immagine includa Python quando usi Testinfra.

• Il pacchetto non si installa nel container

  • Soluzione: entra nel container con docker exec e prova apt update && apt install manuale per diagnosticare.

• Timeout nella creazione dell’istanza

  • Soluzione: verifica risorse host (CPU/memoria), problemi di rete o limiti Docker.

Sicurezza e considerazioni GDPR

• Dati sensibili: non inserire credenziali in chiaro nei file del ruolo o nei test. Usa vault Ansible o variabili d’ambiente sicure.
• Log: evita di esporre dati sensibili nei log dei test. Filtra o anonimizza dove necessario.
• Immagini di test: preferisci immagini ufficiali o verificate; evita immagini pubbliche non controllate per dati sensibili.

Nota GDPR: il testing locale con immagini container non coinvolge di norma dati personali. Se testi con dati reali, applica le regole di minimizzazione e pseudonimizzazione.

Hardening e sicurezza del processo di test

• Esegui Molecule dentro runner CI isolati o macchine dedicate.
• Mantieni aggiornati Docker e il sistema host per patch di sicurezza.
• Usa immagini immutabili e pin delle versioni per riproducibilità.
• Controlla i permessi dei file sensibili e usa file .gitignore per credenziali.

Compatibilità e migrazione

• Molecule è compatibile con diversi driver: docker, podman, vagrant, ecc.
• Versioni Python: preferisci Python 3.8+ per compatibilità con le ultime librerie.
• Quando migri da Docker a Podman, verifica il supporto del runner CI e la compatibilità delle immagini.

Cheat sheet comandi rapidi

• Inizializza ruolo: molecule init role –driver-name docker
• Avvia converge: molecule converge
• Esegui test completo: molecule test
• Esegui verifier: molecule verify
• Elenca istanze: molecule list
• Distruggi ambiente: molecule destroy

Esempi di output attesi

• “collected 6 items - 6 passed” dai test pytest/testinfra indica che i controlli sono tutti positivi.
• “changed=0” nel secondo run Ansible indica idempotenza.

FAQ rapida

Q: Posso usare Molecule senza Docker? A: Sì, Molecule supporta altri driver come Podman, Vagrant e integrazione con cloud provider, ma richiede il plugin/driver appropriato.

Q: Dove inserisco test complessi (DB, migrazioni)? A: I test di integrazione più complessi vanno fatti in stage o ambienti dedicati; Molecule è ideale per test di ruolo e integrazione rapida.

Riepilogo e prossimi passi

• Molecule automatizza la creazione di istanze, l’applicazione dei ruoli e la verifica automatica.
• Integrare Molecule in CI migliora la qualità del codice Ansible e riduce regressioni.
• Prossimi passi consigliati: integrare Molecule nella pipeline CI, testare su più immagini (Ubuntu, Debian, CentOS) e aggiungere verifiche più dettagliate (file, permessi, endpoint HTTP).

Short announcement (100–200 parole):

In questa guida completa hai imparato a configurare un ambiente di test per ruoli Ansible usando Molecule e Docker. Hai visto come installare le dipendenze, creare un ruolo boilerplate, definire l’istanza di test, scrivere script di test con pytest-testinfra e automatizzare l’intero ciclo di test con molecule test. Seguendo le best practice proposte potrai integrare Molecule nella CI per assicurare la qualità dei ruoli e la loro idempotenza. Consiglio pratico: isola le dipendenze in un virtualenv, versiona file di test e molecule.yml, e automatizza i test per ogni merge request.

Social preview suggestions:

• OG title: Testare ruoli Ansible con Molecule e Docker
• OG description: Guida passo passo per installare Molecule, creare ruoli LEMP e automatizzare test con Testinfra e Docker.

Glossario (1 linea per voce)

• Ansible: strumento di automazione per configurazione e deployment.
• Molecule: framework di test per ruoli Ansible.
• Testinfra: libreria Python per testare lo stato dei sistemi target.
• Docker: piattaforma per containerizzazione.

Fine della guida.