41 Rückgabestruktur von Modulen: Konvention statt Zwang

41.1 Grundprinzip der Rückgabestruktur

Die Struktur der Rückgabewerte eines Ansible-Moduls ist nicht durch Ansible selbst vorgeschrieben, sondern ergibt sich aus der Verwendung der Hilfsklasse AnsibleModule innerhalb des Moduls. Diese Klasse stellt Methoden wie exit_json() und fail_json() bereit, die eine einheitliche, wohlgeformte JSON-Ausgabe erzeugen. Dadurch entsteht eine faktische Standardstruktur, obwohl diese technisch nicht erzwungen wird.

41.2 Standardfelder bei Verwendung von AnsibleModule

Ein typisches Modul, das AnsibleModule verwendet, liefert folgende strukturierte Felder zurück:

• changed: automatisch auf false gesetzt, wenn nicht explizit angegeben
• failed: nur bei fail_json() gesetzt, standardmäßig false
• msg: optionaler Text zur Beschreibung des Ergebnisses oder Fehlers
• stdout, stderr: bei Modulen, die Shell-Kommandos ausführen
• stdout_lines, stderr_lines: automatisch generierte Listen aus den jeweiligen Textausgaben
• rc: Rückgabecode bei Shell-Kommandos

Diese Felder erscheinen im JSON, das über stdout an den Ansible-Control-Node zurückgegeben wird, und sind somit direkt in einer register-Variable verfügbar.

41.3 Manuelle JSON-Erzeugung und ihre Risiken

Verzichtet ein Modul auf die Verwendung von AnsibleModule, sondern erzeugt seine JSON-Ausgabe manuell, ist es völlig frei in der Struktur. Es könnte beispielsweise nur folgendes liefern:

{ "error": "etwas ist schiefgelaufen" }

41.3.1 Probleme bei manueller JSON-Erzeugung

Dieses JSON ist formal gültig, wird aber von Ansible nicht als Fehler erkannt, da das Pflichtfeld failed: true fehlt. Ebenso wird der Task als nicht geändert betrachtet, wenn changed: true nicht vorhanden ist. Die automatische Interpretation durch Ansible funktioniert in solchen Fällen nicht zuverlässig, und das Verhalten kann irreführend sein.

41.4 Bedeutung der Konvention

Die Rückgabestruktur ist also keine verbindliche Schnittstelle, sondern eine Konvention, die durch die breite Nutzung von AnsibleModule etabliert ist. Sie sorgt für:

• Konsistente Task-Ergebnisse: Einheitliche Interpretation von Erfolg und Fehlern
• Nachvollziehbare Logs: Strukturierte Ausgaben für bessere Debugging-Möglichkeiten
• Korrekte Playbook-Logik: Zuverlässige Funktionsweise von Bedingungen und Handlers

41.5 Empfehlung für die Modulentwicklung

Bei der Entwicklung eigener Module ist die Verwendung der Standardmechanismen von AnsibleModule ausdrücklich empfohlen, um volle Kompatibilität mit der Ansible-Ausführungsumgebung sicherzustellen. Dies gewährleistet:

• Automatische Behandlung der Standard-Rückgabefelder
• Konsistentes Verhalten im Ansible-Ökosystem
• Bessere Integration mit bestehenden Playbooks und Rollen
• Vermeidung von unerwarteten Seiteneffekten bei der Task-Ausführung