Ansible Molecule

Siehe auch

Verwandte Artikel

• Ansible

Offizielle Dokumentation

• Ansible Molecule

Linuxfabrik

• LFOps Ansible Collection

Molecule ist das Standard-Test-Framework für Ansible-Rollen und -Collections. Es automatisiert das Aufsetzen einer isolierten Testumgebung (typischerweise ein Container), spielt dort die zu testende Rolle ein, prüft das Ergebnis und räumt hinterher wieder auf. Damit lassen sich Ansible-Automatisierungen reproduzierbar und CI-tauglich testen, ohne eine echte Zielmaschine zu beanspruchen. Molecule gehört zu den ansible-dev-tools und wird von Red Hat als offizielles Testwerkzeug gepflegt.

Begriffe

• Scenario: ein Satz Testdateien unter extensions/molecule/<name>/. Jede Collection bringt mindestens ein Scenario (typischerweise default) mit. Weitere Scenarios für spezifische OS-Varianten (z.B. rhel, debian) sind üblich.

• Driver: das Backend, das die Testumgebung provisioniert. Gebräuchlich sind podman, docker, vagrant und delegated (für bereits vorhandene Umgebungen).

• converge: die eigentliche Test-Phase - hier läuft das zu testende Playbook gegen die Testumgebung.

• idempotence: zweiter Lauf von converge. Ansible muss dabei changed=0 melden, sonst ist die Rolle nicht idempotent.

• verify: optionale Akzeptanzprüfung mit einem externen Tool, z.B. Testinfra oder Ansible-Assertions.

Installation

Die Installation erfolgt in einer dedizierten venv. Als Driver-Backend wird podman verwendet - rootless und auf RHEL 8+ standardmässig verfügbar.

dnf --assumeyes install podman

python3 -m venv ~/venvs/molecule
source ~/venvs/molecule/bin/activate

python3 -m pip install --upgrade pip
python3 -m pip install ansible-dev-tools 'molecule-plugins[podman]'

ansible-galaxy collection install containers.podman community.general

Versionen prüfen:

molecule --version
ansible --version

Scenario in einer Collection anlegen

Innerhalb einer bestehenden Ansible-Collection (z.B. lfops) wird ein Default-Scenario initialisiert:

source ~/venvs/molecule/bin/activate

cd lfops
mkdir --parents extensions
cd extensions

molecule init scenario
# optional: additional scenarios for specific OS variants
molecule init scenario rhel

Struktur nach init:

lfops/
+-- extensions/
    +-- molecule/
        +-- default/
        |   +-- converge.yml
        |   +-- create.yml
        |   +-- destroy.yml
        |   +-- molecule.yml
        |   +-- verify.yml
        +-- rhel/
            +-- ...

Konfiguration

Zentrale Datei ist molecule.yml pro Scenario. Beispiel mit Podman-Driver und einem Rocky-9-Container:

extensions/molecule/default/molecule.yml

---
driver:
  name: podman

platforms:
  - name: rocky9
    image: rockylinux/rockylinux:9
    pre_build_image: true
    privileged: true
    command: /usr/sbin/init

provisioner:
  name: ansible

verifier:
  name: ansible

Der zu testende Code landet in converge.yml:

extensions/molecule/default/converge.yml

---
- name: Converge
  hosts: all
  tasks:
    - name: apply my role
      ansible.builtin.include_role:
        name: my_role

Testablauf

Molecule unterteilt einen Testlauf in einzelne Phasen:

• dependency: Installation aller benötigten Abhängigkeiten (Collections, Rollen, Playbooks).

• create: Provisionierung der Testumgebung (Container, VM, Cloud-Instanz).

• prepare: Vorbereitungen, die nicht zum eigentlichen Test gehören (z.B. SSH-Keys einrichten, python3 nachinstallieren).

• converge: der eigentliche Test - hier wird die zu testende Automatisierung ausgeführt.

• idempotence: zweiter converge-Lauf. Wenn Ansible dabei Änderungen meldet, ist die Rolle nicht idempotent.

• side_effect: separate Automatisierung, die auf unerwünschte Nebeneffekte testet.

• verify: Validierung expliziter Akzeptanzkriterien. Typischerweise mit Testinfra oder mit Ansible-Assertions.

• cleanup: Entfernen temporärer Daten, die während des Tests entstanden sind.

• destroy: Abbau der in create aufgesetzten Testumgebung.

Reihenfolge und Umfang der Phasen werden in molecule.yml definiert:

extensions/molecule/default/molecule.yml

scenario:
  test_sequence:
    - dependency
    - create
    - converge
    - verify
    - side_effect
    - verify
    - destroy

Mit molecule test wird die komplette Testsequenz ausgeführt. Einzelne Phasen lassen sich auch gezielt aufrufen, z.B. um Container oder VMs nach converge zu inspizieren, bevor sie gelöscht werden. Dabei werden stets alle Phasen der Testsequenz bis zur angegebenen Phase mitgeführt - ein molecule converge durchläuft bei der Standardsequenz also dependency, create, prepare und converge.

Molecule Cheat Sheet

source ~/venvs/molecule/bin/activate
cd lfops/extensions

# full test sequence
molecule test

# only the rhel scenario
molecule test --scenario-name rhel

# schrittweise, zum Debugging
molecule create                   # Container hochfahren
molecule converge                 # Rolle einspielen
molecule login                    # in den Container wechseln
molecule verify                   # nur die verify-Phase
molecule destroy                  # aufraeumen

# verbose output
molecule --debug test

Troubleshooting

Error while fetching server API version oder podman.service: Failed to start

Der Podman-Socket ist nicht erreichbar. Für den aktuellen Benutzer den User-Socket starten: systemctl --user enable --now podman.socket. Im CI-Umfeld zusätzlich DOCKER_HOST=unix:///run/user/$(id -u)/podman/podman.sock exportieren.

Failed to import the required Python library (requests) beim Podman-Driver

Das Python der venv findet den Podman-Client nicht, oder die Abhängigkeiten fehlen. python3 -m pip install 'molecule-plugins[podman]' in der venv erneut installieren.

Molecule bricht mit idempotence: changed tasks ab

Die Rolle ist nicht idempotent: ein zweiter Lauf würde auf der produktiven Maschine erneut Änderungen anwenden. Typische Ursachen sind command/shell ohne changed_when, copy ohne mode:, oder Template-Rendering, das Zeitstempel oder eine zufällige Reihenfolge enthält.