Lieblings-Tool "ansible-doc" – ein schneller Überblick über die Ansible-Module
Storage, Server und Netzwerke automatisieren, schwierige manuelle Arbeitsschritte vereinfachen und so Fehleranfälligkeit reduzieren – das ist das Ziel des Konfigurationsmanagements 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)
Kommentare