Tester des rôles Ansible avec Molecule et Docker

Molecule permet d’automatiser les tests des rôles Ansible en créant des instances éphémères (conteneurs, VM ou cloud), en appliquant le rôle et en exécutant des tests (testinfra/pytest). Ce guide explique comment installer Ansible, Docker et Molecule, initialiser un rôle LEMP, configurer Molecule pour Docker, écrire des tests testinfra et exécuter des scénarios de test complets.

Important : ce tutoriel utilise Ubuntu 22.04 en exemple et des images Docker publiques contenant Python. Adaptez les images et noms de paquets selon vos versions et distribution cible.

Objectifs et variantes de recherche

H1 principal : Tester des rôles Ansible avec Molecule et Docker

Intent principal : Expliquer comment installer et utiliser Molecule avec Docker pour tester des rôles Ansible. Mots-clés associés : Molecule Docker, testinfra, test Ansible, CI Ansible, rôles Ansible, validation automatisée

Pourquoi utiliser Molecule

Molecule automatise la création d’un environnement de test, l’application du rôle et la vérification du résultat. Il facilite :

• la reproductibilité des tests,
• l’intégration dans une pipeline CI,
• la validation multi-plateforme (différentes images/VM/cloud),
• et la standardisation des processus de développement des rôles.

Définition rapide : Molecule — outil de test pour rôles Ansible. Testinfra — bibliothèques pytest pour vérifier l’état d’une machine distante.

Prérequis

• Une machine Linux (ex. Ubuntu 22.04) avec un utilisateur non-root ayant sudo. Exemple d’utilisateur : alice.
• Connaissance de base d’Ansible et de l’organisation des rôles.
• Accès réseau pour télécharger paquets et images Docker.

Remarque importante : adaptez les paquets système et noms de services à la distribution cible (ex. systemd vs SysV).

Partie A — Installation des dépendances système

Mettez à jour l’index de paquets avant de commencer :

sudo apt update

Ensuite installez Python3, pip, venv, Ansible et utilitaires :

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

Input y quand le système vous le demande.

Installer Docker (Community Edition) via le dépôt officiel :

1. Créez le répertoire pour la clé GPG de Docker et importez-la :

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

2. Ajoutez le dépôt Docker :

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

3. Mettez à jour les sources puis installez Docker CE :

sudo apt update

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

Ajoutez votre utilisateur au groupe docker pour exécuter docker sans sudo :

sudo usermod -aG docker $USER

Vérifiez la configuration en lançant l’image hello-world :

docker run hello-world

Si Docker fonctionne, vous verrez la sortie du conteneur hello-world.

A présent, les dépendances système (Python3, pip, Ansible et Docker) sont prêtes.

Partie B — Installer Molecule dans un environnement virtuel Python

Créez et activez un virtualenv nommé ansible-venv :

python3 -m venv ansible-venv

source ansible-venv/bin/activate

Déplacez-vous dans le répertoire et installez Molecule avec le plugin Docker :

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

Note : pip installe Molecule dans le virtualenv ; conservez l’environnement actif lorsque vous travaillez sur vos rôles.

Partie C — Initialiser un rôle Ansible avec Molecule

Vous allez générer un squelette de rôle pour installer une pile LEMP (Linux, Nginx, MariaDB, PHP-FPM). Exécutez :

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

Cette commande crée un dossier lemp contenant la structure d’un rôle et la configuration Molecule.

Entrez dans le dossier :

cd lemp

Éditez tasks/main.yml et ajoutez les tâches d’installation et d’activation des services :

---  
- 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 }}"

Sauvegardez et fermez l’éditeur.

Définissez les variables dans vars/main.yml :

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

Ajustez les noms de paquets (php8.1-fpm) selon la version disponible sur l’image ou la distribution.

Partie D — Préparer l’instance Docker pour les tests

Dans cet exemple nous utilisons l’image Docker mipguerrero26/ubuntu-python3 qui inclut Python3. Vous pouvez choisir une autre image tant que Python est présent.

Téléchargez l’image :

docker pull mipguerrero26/ubuntu-python3

Vérifiez les images disponibles :

docker images

Vous pouvez exécuter un conteneur temporaire pour vérifier Python et la release Ubuntu :

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

python3 --version  
cat /etc/lsb-release

Quittez avec exit.

Partie E — Configurer Molecule pour utiliser l’image

Ouvrez molecule/default/molecule.yml et modifiez la section platforms :

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

Enregistrez le fichier.

Listez les instances Molecule :

molecule list

Vous devriez voir instance-ubuntu22.04 avec le driver Docker.

Partie F — Exécuter converge pour appliquer le rôle

Lancez :

molecule converge

Molecule crée l’instance Docker, puis exécute le rôle Ansible contre celle-ci.

Vérifiez ensuite les conteneurs Docker :

docker ps

Vous verrez le conteneur instance-ubuntu22.04.

Connectez-vous au conteneur :

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

Vérifiez les ports et sockets pour confirmer que Nginx, MariaDB et PHP-FPM sont actifs :

ss -tulpn  
ss -pl | grep php

Pour nettoyer, détruisez l’instance Molecule :

molecule destroy

Vérifiez qu’il n’y a plus de conteneurs en cours :

docker ps  
docker ps -a

Partie G — Ajouter des tests avec testinfra (pytest)

Installez le plugin pytest-testinfra dans le virtualenv :

pip3 install pytest-testinfra

Créez le répertoire des tests et le fichier de test :

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

Contenu du fichier test_default.py :

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

Enregistrez et fermez.

Modifiez molecule/default/molecule.yml pour utiliser testinfra comme vérificateur :

verifier:  
  name: testinfra  
  directory: tests

Exécutez la suite complète (create → converge → verify → destroy) :

molecule test

Molecule détruira d’abord toute instance existante, puis créera l’instance, appliquera le rôle, lancera pytest/testinfra et détruira l’instance.

Après exécution, pytest doit afficher un résumé du type “collected N items - N passed” si tout est valide.

Bonnes pratiques en développement avec Molecule

• Travaillez dans un virtualenv Python pour isoler Molecule et ses dépendances.
• Gardez la configuration Molecule versionnée avec le rôle (molecule.yml dans le repo du rôle).
• Créez plusieurs scenarios Molecule (répertoire molecule//) pour tester différentes images ou distributions.
• Automatisez l’appel de molecule test dans votre pipeline CI pour chaque PR.

Quand Molecule peut échouer et contre-exemples

• Image de test dépourvue de Python : testinfra ou Ansible remote nécessite Python. Solution : choisir une image qui inclut Python ou installer python via la provision du conteneur.
• Paquets manquants dans les dépôts de l’image : adapter les sources APT ou utiliser une image correspondant à la distribution cible.
• Services qui ne démarrent pas en mode privilégié : certains modules Ansible ou services attendent des capacités spécifiques. Testez en mode privileged: true ou ajustez capabilities.
• Tests instables à cause d’ordres ou délais : ajoutez des handlers, uses systemd-detect-virt ou des retries dans Ansible ou des attentes explicites dans les tests.

Approches alternatives

• Vagrant comme driver local pour tester VMs basées sur VirtualBox/VMware si vous avez besoin d’un environnement plus proche d’une VM réelle.
• Cloud drivers (AWS, Azure, GCP) pour tests d’intégration en environnement cloud, mais plus coûteux et moins rapides pour CI.
• Utiliser des images de build dédiées (baked images) pour réduire le temps d’installation lors de converge.
• Exécuter linting Ansible (ansible-lint) avant moleculer pour attraper des erreurs statiques.

Checklist par rôle (liste de vérification rapide)

• Le rôle a un molecule.yml et un scenario de test par plate-forme supportée.
• tasks/main.yml est idempotent et couvre l’installation + configuration.
• vars/main.yml contient des valeurs par défaut modifiables.
• Handlers définis et déclenchés correctement.
• Testinfra couvre : paquets, services, ports, fichiers de configuration, utilisateurs.
• Les tests s’exécutent dans CI pour chaque PR.

Critères d’acceptation

• Le rôle s’applique sans erreur via molecule converge.
• Tous les tests pytest/testinfra passent (0 échec).
• Aucune ressource résiduelle après molecule destroy.
• Le rôle reste idempotent (apply twice → pas de changement la seconde fois).

Exemples de cas de test supplémentaires

• Vérifier qu’un fichier de configuration a le contenu attendu :

def test_config_file(host):
    f = host.file('/etc/nginx/nginx.conf')
    assert f.exists
    assert f.user == 'root'
    assert 'worker_processes' in f.content_string

• Vérifier qu’un port est à l’écoute :

def test_listening_port(host):
    socket = host.socket('tcp://0.0.0.0:80')
    assert socket.is_listening

• Vérifier la version d’un paquet via la commande :

def test_nginx_version(host):
    cmd = host.run('nginx -v 2>&1')
    assert 'nginx' in cmd.stderr

Mini-méthodologie pour intégrer Molecule en CI

1. Installez les dépendances (docker, python, pip) dans l’image CI runner.
2. Créez un virtualenv et installez molecule + drivers.
3. Exécutez ansible-lint et tests unitaires locaux (sans Docker) si possible.
4. Lancez molecule test en mode non-interactif.
5. Collectez les sorties pytest et enregistrez les artefacts (logs, sorties) pour débogage.

Sécurité et confidentialité

• Ne publiez jamais des clés, mots de passe ou secrets dans les fichiers molecule.yml ou les tests. Utilisez des variables d’environnement ou un vault chiffré.
• Limitez les privilèges des images Docker utilisées pour les tests : n’exécutez pas de services sensibles dans le conteneur.
• Nettoyez systématiquement les instances via molecule destroy pour éviter des ressources oubliées.

Compatibilité et conseils de migration

• Si vous migrez d’un driver (Vagrant) vers Docker, adaptez les commandes de provisionnement et les chemins des sockets.
• Vérifiez la compatibilité de versions entre Ansible, Molecule et drivers (consultez la doc officielle pour la matrice de compatibilité).
• Testez vos rôles sur plusieurs versions d’OS en multipliant les scenarios Molecule.

Modèle de décision (flowchart Mermaid)

flowchart TD
  A[Démarrer développement du rôle] --> B{Rôle idempotent?}
  B -- Oui --> C{Tests unitaires présents?}
  B -- Non --> D[Corriger tasks/main.yml]
  C -- Oui --> E{Molecule scenario configuré?}
  C -- Non --> F[Ajouter tests pytest-testinfra]
  E -- Oui --> G[Exécuter molecule test]
  E -- Non --> H[Init scenario avec molecule init role]
  G --> I{Tests passés?}
  I -- Oui --> J[Merge et déployer pipeline CI]
  I -- Non --> D

Glossaire (1 ligne chacun)

• Molecule : outil de test pour rôles Ansible.
• Testinfra : bibliothèques pytest pour vérifier l’état d’une machine distante.
• Converge : étape où Ansible applique le rôle sur l’instance.
• Verify : étape où Molecule lance les vérifications (testinfra).

Dépannage courant

• Erreur : MOLECULE_INVENTORY_FILE non défini → assurez-vous d’exécuter testinfra depuis Molecule (molecule verify ou molecule test) ou exportez la variable d’environnement.
• Échec d’installation apt dans le conteneur → vérifiez la connectivité réseau et les sources APT interne à l’image.
• Conteneur qui expire avant la vérification → augmentez les timeouts ou utilisez des readiness checks dans les tests.

Ressources et lecture complémentaire

• Documentation officielle Molecule — pour la configuration avancée et les drivers.
• testinfra + pytest — pour écrire des tests riches et paramétrés.
• ansible-lint — pour valider la qualité statique des rôles.

Conclusion

Vous savez désormais : installer Molecule et Docker, initialiser un rôle Ansible, configurer Molecule pour Docker, écrire des tests testinfra et exécuter un scénario de test complet (create, converge, verify, destroy). Intégrez molecule test dans votre CI pour assurer la qualité et la reproductibilité des rôles Ansible.

Résumé des prochaines étapes recommandées :

• Versionnez la configuration Molecule avec le rôle et créez plusieurs scenarios.
• Ajoutez ansible-lint et des tests unitaires pour détecter rapidement les régressions.
• Intégrez les tests dans une pipeline CI avec reporting des résultats.