Ansible Molecule: Rollen mit Docker testen

Ansible Molecule automatisiert das Testen und Validieren von Ansible‑Rollen und Playbooks in reproduzierbaren Szenarien. In dieser Anleitung richten Sie eine Entwicklungsumgebung mit Python‑Virtualenv, Ansible, Docker und Molecule ein, erzeugen einen Rollen‑Boilerplate, definieren Testinstanzen mit Docker und schreiben eigenständige Testfälle mit pytest‑testinfra. Am Ende führen Sie vollständige Molecule‑Durchläufe (create → converge → verify → destroy) zur kontinuierlichen Validierung durch.

Wichtig: Diese Anleitung verwendet Ubuntu 22.04 als Beispiel und testet mit einem Docker Image, das Python bereits enthält.

Was ist Ansible Molecule

Ansible Molecule ist ein Framework zum Entwickeln, Testen und Validieren von Ansible‑Rollen und Playbooks. Es automatisiert das Erstellen von Testinstanzen, das Anwenden von Rollen sowie das Verifizieren des gewünschten Zustands mittels Verifiern wie testinfra. Molecule unterstützt verschiedene Treiber (Docker, Podman, Vagrant, Cloud‑Provider) und lässt sich in CI‑Pipelines integrieren.

Kurzdefinition: Molecule = Entwicklungs‑Workflow + Testinstanzen + Verifier.

Primäre Suchintentionen und Varianten

• Primär: Ansible Molecule mit Docker testen
• Varianten: Rolle mit Molecule testen, Molecule testinfra Beispiel, Molecule Docker Tutorial, Ansible Rollen automatisiert testen, Molecule CI Integration

TL;DR — noch einmal kurz

Molecule erzeugt isolierte Testumgebungen (hier: Docker‑Container), spielt Ihre Rolle ein und führt automatisierte Tests mit testinfra aus. Nutzen Sie: virtuelle Umgebung, Molecule Docker Driver, pytest‑testinfra. Workflow: molecule init → tasks/vars anpassen → molecule converge → tests laufen → molecule destroy oder molecule test für End‑to‑End.

Voraussetzungen

• Linux‑System (Beispiel: Ubuntu 22.04 Server, Hostname: ansible-test)
• Nicht‑Root‑Benutzer mit sudo (Beispiel: alice)
• Grundkenntnisse in Ansible und Rollen‑Layout
• Zugang zum Internet, um Pakete und Docker‑Images zu ziehen

Wichtig: Molecule selbst läuft lokal in einer Python‑Virtualenv; Docker auf dem Host wird für Container inspiziert.

Sicherheits‑Hinweis

Wichtig: Beim Testen mit privilegierten Containern (privileged: true) sollten Sie in produktionsähnlichen Umgebungen verantwortungsbewusst vorgehen. Vermeiden Sie unbeaufsichtigte Ausführung in unsicheren Netzwerken.

Schritt 1 — Installieren von Abhängigkeiten

Ziel: Python3, Pip, Virtualenv, Ansible und Docker CE auf Ubuntu installieren.

1. Paketindex aktualisieren

sudo apt update

2. Python3, Pip3, Virtualenv, Ansible und Hilfspakete installieren

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

Antworten Sie mit y, wenn Sie dazu aufgefordert werden.

3. Docker Repository und GPG‑Key anlegen

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

4. Docker CE Repository hinzufügen

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

5. Paketindex erneut aktualisieren und Docker installieren

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

6. Benutzer zur Docker‑Gruppe hinzufügen

sudo usermod -aG docker $USER

Melden Sie sich danach ab und wieder an oder starten Sie die Shell neu, damit die Gruppenmitgliedschaft aktiv wird.

7. Testlauf: hello‑world‑Container

docker run hello-world

Erfolg zeigt die Ausgabe des hello‑world‑Containers.

Schritt 2 — Molecule in einer Virtualenv installieren

Empfehlung: Isolierte Python‑Umgebung pro Entwickler/Projekt.

1. Virtualenv anlegen

python3 -m venv ansible-venv

2. Virtualenv aktivieren

source ansible-venv/bin/activate

Ihre Shell‑Eingabeaufforderung zeigt nun (ansible-venv).

3. Molecule und Docker‑Plugin installieren

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

Hinweis: Verwenden Sie pip in der aktivierten Virtualenv, nicht systemweit.

Schritt 3 — Ansible‑Rolle mit Molecule initialisieren

Ziel: Boilerplate‑Rolle erstellen, die später LEMP installiert.

1. Rolle generieren

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

Das erzeugt ein Verzeichnis lemp mit Standardstruktur (tasks, handlers, defaults, vars, molecule/…).

2. In das Rollenverzeichnis wechseln

cd lemp

3. Aufgaben definieren (tasks/main.yml)

nano tasks/main.yml

Inhalt:

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

Speichern und schließen.

4. Variablen anlegen (vars/main.yml)

nano vars/main.yml

Beispielinhalt:

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

Schritt 4 — Testinstanz konfigurieren

Molecule nutzt in der Standardkonfiguration eine molecule/default/molecule.yml. Wir passen die Plattform‑Definition an, um ein Image mit Python zu verwenden.

1. Optional: eigenes Testimage ziehen (muss Python3 enthalten)

docker pull mipguerrero26/ubuntu-python3

2. Plattform in molecule.yml anpassen

nano molecule/default/molecule.yml

Ändern Sie den Abschnitt platforms so:

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

Das Attribut privileged: true erleichtert Tests, die Systemdienste benötigen.

3. Vorhandene Instanzen auflisten

molecule list

Sie sollten die konfigurierte Instanz sehen.

Schritt 5 — Konvergenz ausführen

Führen Sie die Rolle gegen die Testinstanz aus:

molecule converge

Molecule erstellt die Containerinstanz und wendet Ihre Rolle an. Beobachten Sie die Ausgabe, um Installations‑ und Service‑Schritte zu verifizieren.

Prüfen Sie laufende Docker‑Container:

docker ps

Beispiel: container mit Namen instance-ubuntu22.04 wird sichtbar.

Um sich in den Container einzuloggen:

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

Im Container prüfen Sie geöffnete Ports und laufende PHP‑Sockets:

ss -tulpn
ss -pl | grep php

Wenn Nginx auf Port 80, MariaDB auf Port 3306 und PHP‑FPM über /run/php/*.sock verfügbar sind, ist die Konvergenz erfolgreich.

Zum Aufräumen lokal:

molecule destroy

Schritt 6 — Testskripte mit pytest‑testinfra erstellen

testinfra ermöglicht, Serverzustände als Tests zu beschreiben (Pakete, Dienste, Dateien, Sockets).

1. testinfra installieren

pip3 install pytest-testinfra

2. Tests anlegen

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

Beispieltest (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

Speichern und schließen.

3. Molecule Verifier konfigurieren

nano molecule/default/molecule.yml

Im Abschnitt verifier auf testinfra setzen:

verifier:
  name: testinfra
  directory: tests

4. Vollständigen Testlauf starten

molecule test

Der Befehl führt einen kompletten Zyklus aus: create → converge → verify → destroy.

Screenshots zeigen Ablauf und Erfolgsmeldung (collected X items, X passed).

Best Practices und Workflow im Entwicklungszyklus

1. Rollenstruktur mit Molecule erzeugen: molecule init role …
2. Tasks/Handlers/Defaults/Vars anpassen.
3. Lokale Testinstanz definieren (molecule.yml).
4. Schnelle Validierung: molecule converge
5. Testskripte erweitern: pytest/testinfra
6. End‑to‑End: molecule test
7. Nutzung in CI: dieselben Schritte in Pipeline (evtl. mit Docker‑in‑Docker oder GitHub Actions runners)

Wichtig: Nutzen Sie idempotente Tasks, damit wiederholtes Anwenden keine Seiteneffekte erzeugt.

Troubleshooting: Häufige Fehler und Lösungen

• Fehler: Container startet, aber Paketinstallation schlägt fehl
  • Prüfen Sie /var/log/apt/term.log im Container
  • Stellen Sie sicher, dass das Testimage Netzwerkzugriff hat
• Fehler: testinfra findet keine Hosts
  • Überprüfen Sie, ob MOLECULE_INVENTORY_FILE in der Umgebung gesetzt ist
  • Führen Sie molecule converge vor molecule verify aus
• Fehler: Dienstname stimmt nicht mit Distribution überein
  • Unterschiedliche Distros verwenden unterschiedliche Paket‑ und Servicenamen (z. B. php8.1-fpm vs php-fpm)

Erweiterte Konfiguration: beispielhafte molecule.yml Snippets

Minimal konfiguriertes molecule/default/molecule.yml (Auszug):

driver:
  name: docker

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

provisioner:
  name: ansible

verifier:
  name: testinfra
  directory: tests

Passen Sie zusätzlichvolumes oder environment‑Variablen an, falls Ihre Rolle Zugriff auf spezielle Ressourcen benötigt.

Sicherheit und Härtungsempfehlungen für Testumgebungen

• Führen Sie Tests nicht mit erhöhten Rechten in gemeinsam genutzten CI‑Runnern aus. Verwenden Sie dedizierte Runner oder Sandboxen.
• Verwenden Sie signierte Images aus vertrauenswürdigen Quellen. Prüfen Sie Image‑Hashes in CI.
• Entfernen Sie sensible Daten (Schlüssel/Passwörter) aus Testvariablen; nutzen Sie Vault oder CI‑Secret‑Stores.

Integration in CI/CD Pipelines

• GitHub Actions: Job mit steps → checkout → setup Python → install dependencies → docker login (falls nötig) → molecule test
• GitLab CI: Führen Sie Runner mit Docker‑in‑Docker oder Privilegierten Runnern, damit Molecule Container starten kann.
• Tipp: Cachen Sie pip‑Abhängigkeiten und Docker‑Layer, um Laufzeiten zu reduzieren.

Mögliche Alternativen zu Molecule

• Testen nur lokal mit Vagrant (wenn VM‑verhalten erforderlich)
• Verwendung von Containerspezifischen Tools (Podman statt Docker) — Molecule unterstützt Podman über entsprechende Treiber
• Lightweight‑Integrationstests mit Docker Compose für Multi‑Container‑Setups

Entscheidungshilfe (Mermaid‑Flowchart)

flowchart TD
  A[Will ich Rollen testen?] --> B{Brauche ich Container oder VMs}
  B -->|Container| C[Docker/Podman + Molecule]
  B -->|VMs| D[Vagrant + Molecule]
  C --> E{Testart}
  E -->|Unit/Integration| F[Molecule converge + testinfra]
  E -->|System/End2End| G[CI + echte Cloud/VMs]
  D --> G

Rollen‑Checkliste für Entwickler

• molecule init role ausgeführt
• tasks/main.yml idempotent
• vars/defaults dokumentiert
• molecule/default/molecule.yml für Zielplattform angepasst
• testinfra‑Tests vorhanden und aussagekräftig
• molecule test lokal erfolgreich
• CI Pipeline für molecule test eingerichtet

Beispiel Testfälle und Akzeptanzkriterien

• Testfall: Paketinstallation
  • Erwartung: nginx, mariadb-server, php-fpm sind installiert
  • Kriterium: test_pkg bestätigt is_installed für alle Pakete
• Testfall: Dienste laufen
  • Erwartung: nginx, mariadb, php‑fpm laufen und sind enabled
  • Kriterium: test_svc bestätigt is_running und is_enabled
• Testfall: Netzwerk
  • Erwartung: Port 80 offen
  • Kriterium: testinfra prüft socket(‘tcp://0.0.0.0:80’)

Playbook / SOP für wiederholbare Tests

1. Lokal: activate virtualenv
2. pip install -r requirements.txt (molecule, plugins, pytest‑testinfra)
3. molecule test
4. Bei fehlgeschlagenen Tests: molecule converge → logs prüfen → Rolle anpassen → moleculer test erneut
5. Merge nach erfolgreichem CI‑Durchlauf

Rollout‑Matrix und Reifegrade

• Stufe 0 — Keine Tests: Rollen manuell deployt
• Stufe 1 — Lokale Molecule Tests mit einem Szenario
• Stufe 2 — Molecule Tests für mehrere Plattformen (Ubuntu, CentOS)
• Stufe 3 — Molecule in CI mit Gates vor Merge

Risikoanalye und Gegenmaßnahmen

• Risiko: Tests liefern false positives durch fehlerhafte Testimages
  • Gegenmaßnahme: Verwenden Sie vertrauenswürdige Basisimages und prüfen Sie Versionen
• Risiko: Unterschiedliche Verhalten in Container vs. VM
  • Gegenmaßnahme: Ergänzende Tests auf VMs oder Cloud‑Instanzen

Lokale Anpassungen und Hinweise für Deutschland/Europa

• Paketnamen und Versionsnummern können je nach Distribution variieren; prüfen Sie apt‑Repos (debian/ubuntu) oder RHEL‑EQUIV
• DSGVOHinweis: Testdaten dürfen keine echten personenbezogenen Daten enthalten; anonymisieren oder synthetisieren Sie Testdaten

Kurze Glossarzeilen

• Molecule: Framework zum Testen von Ansible‑Rollen
• testinfra: pytest‑basiertes Tool zur Serverprüfung
• converge: Molecule‑Schritt zum Anwenden der Rolle auf Testinstanz
• verify: Molecule‑Schritt zum Ausführen von Tests

Beispielhafte Debug‑Kommandos

• Logs eines fehlgeschlagenen Ansible‑Tasks anzeigen:

# In Molecule‑Output nach FAILED suchen oder direkt:
molecule login
# dann im Container /var/log/ansible.log oder /var/log/syslog prüfen

Fazit

Mit Ansible Molecule schaffen Sie einen wiederholbaren, automatisierten Workflow zum Entwickeln und Testen von Rollen. Die Kombination aus Molecule, Docker und testinfra ermöglicht schnelle lokale Iterationen und sichere CI‑Integrationen. Beginnen Sie klein (eine Rolle, ein Szenario) und erweitern Sie Ihre Tests mit zusätzlichen Plattformen und Verifiern.

Wichtiger nächster Schritt: Integrieren Sie molecule test in Ihre CI‑Pipeline, damit jede Änderung automatisch validiert wird.

Zusätzliche Ressourcen

• Offizielle Molecule Dokumentation

Wichtige Hinweise

• Verwenden Sie virtuelle Umgebungen, um Abhängigkeitskonflikte zu vermeiden.
• Entfernen Sie sensible Daten aus Testkonfigurationen oder nutzen Sie Secret‑Stores.

Zusammenfassung

• Molecule automatisiert Erstellen, Anwenden und Testen von Ansible‑Rollen.
• Docker ist ein schneller, ressourcenschonender Testtreiber für Molecule.
• pytest‑testinfra erlaubt aussagekräftige Prüfungen des Systemzustands.
• Workflow in CI erhöht Zuverlässigkeit und verhindert Regressionen.

Ende des Tutorials.