Direkt zum Inhalt
03.09.2024 - Fachbeitrag

Lieblings-Tool "ansible-doc" – ein schneller Überblick über die Ansible-Module

Grafik Ansible
text

Storage, Server und Netzwerke automatisieren, schwierige manuelle Arbeitsschritte vereinfachen und so Fehler­anfälligkeit reduzieren – das ist das Ziel des Konfigurations­managements mit Ansible. Dozent Sven Velt ist echter Ansible-Profi, gibt Kurse an unserer Akademie und verrät hier mehr über sein Ansible-Lieblings-Tool.

Das bietet „ansible-doc“ – ein kleines How-to

Nach der Installation von Ansible ist das Tool "ansible-doc" direkt verfügbar. Wie der Name schon sagt, kann man damit auf die Dokumentation aller Plugins und Module zugreifen. Die Dokumentation ist Teil des jeweiligen Source-Codes – so ist sichergestellt, dass tatsächlich alle Teile dokumentiert sind. In vielen Fällen enthält die Doku sogar konkrete Anwendungsbeispiele.

  • Mit dem Aufruf "ansible-doc -l" listet uns Ansible alle Module auf, die installiert bzw. bekannt sind. Um die genaue Zahl zu erfahren, leitet der erfahrene Linux-User die Ausgabe um und erfährt so die genaue Zahl der Module: "ansible-doc -l | wc -l". 
  • Weiß man, wie ein Modul heißt, kann man dessen Dokumentation direkt aufrufen: "ansible-doc ansible.posix.authorized_key". Im Bereich "OPTIONS" werden alle möglichen Argumente, die an das Modul übergeben werden können, aufgelistet. Praktisch: Die rote Farbe (oder in älteren Versionen ein Gleichheitszeichen/"=") zeigt an, dass dieses Argument gesetzt werden muss. 
  • Wer mit Theorie nicht so viel anfangen kann, nutzt den Abschnitt "EXAMPLES", in dem verschiedene Varianten gezeigt werden, wie man das Modul in einem Playbook aufrufen kann - ggf. auch in Kombination mit anderen Ansible-Konstrukten wie z.B. Jinja2-Lookups.
  • Soll auf das Ergebnis des Modul-Aufrufs reagiert werden, sieht man alle möglichen Rückgaben des Moduls im Abschnitt "RETURN VALUES". Aber Vorsicht: Nicht immer werden alle Werte zurückgegeben, man sollte sich also nie darauf verlassen, dass eine Variable gesetzt ist. Für alle, die es ganz genau wissen möchten: In der ersten Zeile der Dokumentation ist zusätzlich der komplette Pfad zum jeweiligen Modul im Dateisystem angegeben.

FQCN – finde den richtigen Namen

Für alle, die sich die sog. "fully-qualified collection name" (FQMN) nicht merken können gibt es zwei Wege:

  • Für Module, die schon in Ansible 2.9 unter gleichem Namen vorhanden waren, kann der Aufruf mit dem reinen Modul-Namen erfolgen: "ansible-doc authorized_key". 
  • Für Module, die nur noch unter ihrem FQCN ansprechbar sind, oder wenn man den genauen Namen nicht (mehr) weiß, hilft die gute alte Kommandozeile und "grep" aus: "ansible-doc -l | grep authorized_key".
  • So kann man natürlich auch nach Herstellern ("ansible-doc -l | grep proxmox") oder Stichwörtern ("ansible-doc -l | grep SSH") suchen.

So funktioniert es bei Plugins

Ansible besteht nicht nur aus Modulen. An vielen Stellen gibt es Plugins und auch diese enthalten direkt ihre Dokumentation.

  • Wer mit dynamischen Inventories arbeiten möchte, kann sich direkt ansehen, welche Plugins mitgeliefert werden: "ansible-doc -t inventory -l". Und auch hier kann man sich die Dokumentation (ähnlich zu den Modulen) ansehen: "ansible-doc -t inventory community.general.proxmox" 
  • Für Konfigurationen mit der Jinja2-Template-Sprache benötigt man häufiger Lookups und Filter. Auch auf deren Auflistung bzw. Dokumentation kann man auf die gleiche Art und Weise zugreifen: "ansible-doc -t lookup -l" bzw. "ansible-doc -t filter ansible.builtin.dirname". 

Grundsätzlich gibt es die Dokumentation auch im Web - allerdings immer nur für die beiden letzten Versionen (und zusätzlich die bereits 2019 veröffentlichte Version 2.9). Hat man sich - aus guten Gründen - entschieden, keine dieser Versionen zu installieren, kann man nicht sicher sein, dass die Online-Dokumentation auch zur installierten Version passt.

Mehr Tipps vom Profi – Jetzt Schulungsplatz sichern

Neugierig geworden? Einen kompletten Überblick über Ansible gibt Sven regelmäßig in seiner Schulung an der Heinlein Akademie – für Kurzentschlossene sind noch letzte Plätze im Kurs ab dem 16.09.24 frei.

16.09. – 20.09.24 Konfigurationsmanagement mit Ansible (Online-Schulung)
25.11. – 29.11.24  Konfigurationsmanagement mit Ansible (Vor Ort in Berlin)