Ihr habt eure ersten Ansible-Playbooks und Rollen geschrieben und seid bereits ziemlich gut darin. Jetzt möchtet ihr den nächsten Schritt gehen und eine Ansible-Collection veröffentlichen. Doch was ist eine Collection eigentlich? Was haben Rollen damit zu tun? Und wie genau wird eine Collection erstellt?
Was ist eine Collection?
Jeder, der Ansible genutzt hat, ist bereits mit Rollen vertraut. Sie sorgen dafür, dass automatisch Variablen, Tasks, Handler und anderer Ansible-Code geladen werden, basierend auf einer standardisierten Verzeichnisstruktur. Dabei sieht eine solche Struktur wie folgt aus:
|
1 2 3 4 5 6 7 8 9 10 |
roles/ hardening/ tasks/ handlers/ library/ files/ templates/ vars/ defaults/ meta/ |
Bei der dargestellten Struktur handelt es sich um eine Rolle. Der Vorteil von Rollen? – Sie können im Anschluss einfach weiter genutzt und mit anderen Nutzern geteilt werden.
Viele Menschen, die Ansible in der aktuellen Version nutzen und die Entwicklung etwas verfolgen, kennen Collections. Sie sind ein neues Verteilungsformat für Ansible-Code. Dieser kann aus Playbooks, Rollen, Modulen, Dokumentation und Plugins bestehen. Collections werden dabei ebenfalls wie Rollen über Ansible Galaxy oder per Git installiert. Sobald Ansible als Softwarepaket installiert wird, findet automatisch eine Mitinstallierung von durch die Community gepflegte Collections statt. Diese Collections bestehen zum größten Teil aus Code, der früher in Ansible selbst Platz gefunden hat, jetzt aber ausgelagert wurde.
Ein Grund für diese Auslagerung ist unter anderem die Überstrapazierung der Arbeit der Kern-Entwickler*innen aufgrund der hohen Anzahl an Modulen und Plugins, welche durch die Community beigesteuert wurden. Zudem konnten die Plugins und Module nur mit einem neuen Release von Ansible bereitgestellt werden. Durch Collections können diese Plugins und Module nun schneller und unabhängiger von Ansible selbst entwickelt werden.
Wie sieht eine Collection aus?
Eine Collection folgt einer bestimmten Ordnerstruktur, welche verschiedenen Voraussetzungen und Bedingungen entsprechen muss. Dabei kann die Ordnerstruktur einer Collection wie folgt dargestellt werden:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 |
collection/ ├── docs/ ├── galaxy.yml ├── meta/ │ └── runtime.yml ├── plugins/ │ ├── modules/ │ │ └── module1.py │ ├── inventory/ │ └── .../ ├── README.md ├── roles/ │ ├── role1/ │ ├── role2/ │ └── .../ ├── playbooks/ │ ├── files/ │ ├── vars/ │ ├── templates/ │ └── tasks/ └── tests/ |
Mindestens vorhanden sein muss in dieser Ordnerstruktur zum Einen der Meta-Ordner mit der runtime.yml, in der die minimal benötigte Ansible-Version definiert ist, mit der die Rolle lauffähig ist. Zum Anderen muss die Struktur eine README zur Dokumentation sowie die galaxy.yml enthalten, in der Informationen über die Collection enthalten sind.
Warum umwandeln?
Jetzt wo klar ist, was eine Collection genau ist, wieso sie existiert und wie sie aussieht, stellt sich die Frage, wieso eine Rolle in eine Collection umgewandelt werden sollte. Zuerst: Rollen werden weiterhin offiziell und dauerhaft unterstützt. Rollen sind schließlich ein Teil von Collections! Allerdings legt RedHat bei der Entwicklung von Ansible nun verstärkt den Fokus auf Collections, da diese für die Entwicklung von Ansible selbst einfacher zu verwalten sind.
Umwandlung einer Rolle in eine Collection
An dieser Stelle zeige ich euch, wie genau ihr eine Rolle in eine Collection umwandelt. Dies werde ich an folgendem Beispiel vornehmen:
Es existiert eine Rolle mit Standard-Verzeichnissen und Dateien defaults, handlers, meta, tasks, templates, vars und einer README.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 |
ansible-collection-hardening ├── ansible.cfg ├── CHANGELOG.md ├── CONTRIBUTING.md ├── defaults ├── Gemfile ├── handlers ├── kitchen_vagrant_block.rb ├── meta ├── Rakefile ├── README.md ├── rhel6_provision.rb ├── suse_provision.rb ├── tasks ├── templates ├── tests ├── TODO.md └── vars |
In der README befindet sich die Dokumentation sowie diverse Playbook-Beispiele:
|
1 2 3 4 5 6 7 |
- hosts: localhost roles: - devsec.os-hardening vars: sysctl_overwrite: # Enable IPv4 traffic forwarding. net.ipv4.ip_forward: 1 |
Die Frage ist nun, welche Schritte genau getan werden müssen, um die Wandlung einer Rolle in eine Collection zu ermöglichen.
Die Lösung sieht wie folgt aus:
Zuerst muss eine neue Collection erstellt werden. Dazu wird der ansible-galaxy Befehl genutzt. Ebenso, wie eine Rolle erstellt wird, kann eine Collection erstellt werden:
|
1 2 3 4 5 6 7 8 9 10 |
> ansible-galaxy collection init devsec.hardening - Collection devsec.hardening was created successfully > tree devsec/hardening/ devsec/hardening/ ├── docs ├── galaxy.yml ├── plugins │ └── README.md ├── README.md └── roles |
Nachdem die Collection erstellt und mit einem Minimal-Set an Inhalten befüllt ist, wird die bestehende Rolle hinzugefügt. Dazu sollte jedoch zuerst ein neues Verzeichnis im Rollen-Ordner der Collection erstellt werden.
Hinweis: Der Name der Rolle darf nur aus Kleinbuchstaben, Zahlen, Buchstaben sowie Unterstrichen bestehen und mit einem Buchstaben beginnen.
|
1 |
> mkdir devsec/hardening/roles/hardening_role/ |
Im Anschluss kann der Inhalt der Rolle in den Rollen-Ordner der neuen Collection kopiert werden:
|
1 |
> cp -r ansible-collection-hardening/* devsec/hardening/roles/hardening_role/ |
Der nächste Schritt ist, die Dokumentation der Collection anzupassen. Hier gibt es zwei relevante Dateien. Die galaxy.yml sowie die README. In der galaxy.yml sollten alle Felder ausgefüllt werden. Besonders hervorzuheben sind hier das Autoren-Feld, die description, tags sowie die Links zum Repository, der Dokumentation, Homepage sowie dem Issuetracker. So könnte es dann aussehen:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
namespace: devsec name: hardening version: 7.4.0 readme: README.md authors: - dev-sec <hello@dev-sec.io> description: 'This collection provides battle tested hardening for Linux, SSH, nginx, MySQL' license: - GPL-2.0-or-later tags: - devsec - hardening repository: 'https://github.com/dev-sec/ansible-os-hardening' homepage: 'https://dev-sec.io/' issues: 'https://github.com/dev-sec/ansible-os-hardening/issues' |
Der nächste Schritt ist die Anpassung der README. In diese gehört:
- eine Beschreibung der Collection,
- deren Inhalte (Rollen, Playbooks, Plugins, etc.),
- mit welcher Ansible-Version die Collection kompatibel ist,
- Abhängigkeiten zu anderen Collections, falls vorhanden,
- wie man die Collection nutzt,
- wie man zur Collection beiträgt (oder einem Verweis auf die CONTRIBUTING.md),
- Releasenotes oder ein Changelog und
- eine Lizenz.
Mehr Inhalte benötigt eine Collection nicht!
Als Beispiel für eine umfangreichere Collection mit mehreren Rollen kann dabei die dev-sec-Organisation genannt werden. Außerdem hat auch die Ansible-Community eine Dokumentation geschrieben, wie Rollen in eine Collection migriert werden können.
> Eine Vorlage mit mehr Inhalt als die Collection, welche mit ansible-galaxy erstellt wurde, ist hier zu finden
Bei dem gesamten Vorgang kann sich natürlich immer an bestehenden Collections orientiert werden. Hier seien besonders die Collections der Telekom MMS auf GitHub zu erwähnen:
Erfahren Sie, wie Open Source Software die Telekom MMS bereichert.
Nutzen von Collections
Die Collection ist nun erstellt. Aber wie wird diese genutzt? Die Antwort lautet: fast genauso wie Rollen!
Ansible sucht nach Collections, die es in folgenden Ordnern nutzen kann:
- dem Standardpfad ~/.ansible/collections
- dem Pfad definiert in der ansible.cfg:
- [defaults]
- collections_paths = ./collections
- der Umgebungsvariable COLLECTIONS_PATHS=~/.ansible/collections
Es ist ebenfalls möglich, die Collection neben dem Playbook, welches ausgeführt wird, zu platzieren. Dabei muss die Collection unter collections/ansible_collections/ zu finden sein. Dies ist der von mir präferierte Weg, um Collections in einem Git-Repository zu verwenden.
Die Rolle in meiner neu erstellten Collection kann schlussendlich wie folgt in einem Playbook verwendet werden:
|
1 2 3 |
- hosts: localhost roles: - dev-sec.os-hardening |
oder:
|
1 2 3 4 5 |
- hosts: localhost collections: - devsec roles: - os-hardening |
Mehr Informationen zur Nutzung von Collections finden Sie in der offiziellen Ansible-Dokumentation.
Veröffentlichen von Collections
Als nächster Schritt kann die eigene Collection auf Ansible Galaxy veröffentlicht werden. Dies ist für Collections etwas umständlicher als für Rollen. Musste man für Rollen nur Github-Repositories im Galaxy-Frontend importieren, muss man für Collections zuerst einen Artefakt bauen und dieses im Anschluss hochladen. Das sind jedoch nur zwei Kommandozeilenbefehle.
Der Befehl ansible-galaxy collection build erstellt aus der Collection eine tar.gz-Datei:
|
1 2 |
> ansible-galaxy collection build Created collection for devsec.hardening at /home/segu/dev/blog-post-collection/devsec/hardening/devsec-hardening-1.0.0.tar.gz |
Bevor die Collection nun veröffentlicht werden kann, muss noch ein Token auf Ansible Galaxy erstellt werden. Dazu wird einfach Galaxy Profile-Preference geöffnet auf API Key gedrückt. Der so erhaltene Key wird daraufhin dem ansible-galaxy Befehl zugegeben.
Der Befehl ansible-galaxy collection publish veröffentlicht die Collection:
|
1 2 3 4 5 |
> ansible-galaxy collection publish devsec-hardening-1.0.0.tar.gz --token=<der token> Publishing collection artifact '/home/segu/dev/blog-post-collection/devsec/hardening/devsec-hardening-1.0.0.tar.gz' to default https://galaxy.ansible.com/api/ Collection has been published to the Galaxy server default https://galaxy.ansible.com/api/ Waiting until Galaxy import task https://galaxy.ansible.com/api/v2/collection-imports/10120/ has completed Collection has been successfully published and imported to the Galaxy server default https://galaxy.ansible.com/api/ |
Im Anschluss ist die eigene hochgeladene Collection veröffentlicht und in der Galaxy zu finden!
SECO eine Mitarbeiterinitiative der Telekom MMS und Community für die Zukunft. Lesen Sie mehr!
Erfahrungen und Best-Practices mit Ansible. Lesen Sie mehr!
Linux und Open Source Enthusiast. Aus dem traditionellen Betrieb kommend, schlage ich jetzt Brücken zwischen Betrieb und Entwicklung und tauche nebenbei in die Cloud-Native Landschaft ein.
