Zuletzt aktualisiert: 03.09.2026 · Lesezeit: 9-11 Minuten
Seit 2019 nutzt Ansible sogenannte Collections. Sie sind das zentrale Mittel der Wahl, um Ansible-Inhalte mit anderen zu teilen. Doch bevor es Ansible Collections gab, dienten diesem Zweck bereits Rollen (oder Roles). Im heutigen Ökosystem sind nach wie vor beide vorhanden. Was es mit Rollen und Collections auf sich hat und wofür du dich heute entscheiden solltest, erfährst du jetzt.
Das Wichtigste in 30 Sekunden
- Rollen sind Funktionen, Collections sind das Verteilungsformat dafür. Beide ergänzen sich, Collections lösen Rollen nicht ab.
- Alleinstehende Rollen bekommen kaum noch Entwicklungsfokus und lassen sich nur über GitHub via Ansible Galaxy verteilen.
- Eigene Plugins (Module, Filter, …) in alleinstehenden Rollen sind nicht ohne Weiteres per FQCN nutzbar und bergen das Risiko von Namenskollisionen.
- Die Lösung: Alleinstehende Rollen in eine bestehende oder neue Collection überführen. Auch eine „miscellaneous“-Collection ist ein valider Weg.
Was ist eine Ansible Rolle, was eine Collection?
Wollte man früher Ansible Code anderen zugänglich machen, war die Wahl einfach: Rollen!
Ansible Rollen sind eine Ansammlung von Variablen, Tasks, Plugins, und anderen Extras, die in Kombination vor allem Zeit sparen.
Rollen kann man sich wie eine Funktion aus der Programmierung vorstellen. Sie erledigen Aufgaben, haben einen bestimmten Anwendungsfall und können bei Bedarf mit angepassten Parametern aufgerufen werden.
Bei Rollen sind diese Parameter die Variablen. Eine Rolle hat in der Regel vorgegebene Standardvariablen, die vom Nutzer geändert werden können, um das Verhalten der Rolle – also das Verhalten der Funktion – anzupassen. Eine Rolle, die einen Webserver aufsetzt, könnte den Server dann z.B. auf Port 8888 statt auf Port 80 lauschen lassen, wenn man die entsprechende Variable anpasst.
Collections sind die moderne Ergänzung zu Rollen. Sie lösen Rollen nicht ab, sondern dienen explizit der Verteilung von Ansible-Inhalten. Zu diesen Inhalten gehören Module und verschiedene Plugin-Arten, wie Inventory oder Filter Plugins, aber eben auch Rollen. Somit kann man Collections als Sammelbecken für Inhalte betrachten, während Rollen selbst einen konkreten Inhalt darstellen.
Sollte ich Rollen oder Collections verwenden?
Die kurze Antwort: Ja!
Rollen sind auch heute noch ein essentieller Bestandteil von Ansible. Die Collections haben den Rollen lediglich die Aufgabe der Verteilung abgenommen. Jegliche Ansible-Inhalte sollten heute in Collections angesiedelt werden. Das gilt auch für Rollen, insbesondere dann, wenn gleichzeitig Module bzw. Plugins zugänglich gemacht werden sollen.
Alleinstehende Rollen, also Rollen, die nicht dem modernen Ansatz folgen und damit nicht Teil einer Collection sind, sollten vermieden werden.
Gründe
Wenig Entwicklungsfokus bei der Ansible Rolle
Ein recht offensichtlicher Grund ist der Fokus auf Collections. In den letzten Jahren sind Collections immer wichtiger und ausgereifter geworden.
Es gibt zwar keine offiziellen Pläne seitens des Ansible-Projekts, aber da Rollen heute Teil einer Collection sein können, ist fraglich, wie lange alleinstehende Rollen noch unterstützt werden.
Anpassungen und Neuerungen beschränken sich schon heute hauptsächlich auf Collections, weshalb man mit alleinstehenden Rollen nur geringfügig davon profitieren kann.
Verteilung und Ansible Galaxy
Zur Verteilung von Ansible Rollen und Collections wird oft Ansible Galaxy genutzt. Collections können darüber bereitgestellt werden, indem man sie via Web UI oder CLI als Tar Ball hochlädt.
Rollen dagegen können nur von GitHub importiert werden. Ansible Galaxy kümmert sich dabei darum, die Inhalte – ein Tar Ball pro Git tag – herunterzuladen und bereitzustellen. Dabei landet der gesamte Inhalt des Repositorys im letztlichen Tar Ball. Tests, Dateien für CI/CD, etc. werden also unnötigerweise mit verteilt.
Bei Collections lassen sich dagegen Dateien exkludieren und es besteht keine Abhängigkeit von GitHub. Die Collection Tar Balls können selbst erstellt und manuell via Web UI oder CLI hochgeladen werden. Wo und auf welcher Plattform sich das Repository befindet, spielt keine Rolle.
Nutzung von Inhalten einer Ansible Rolle
Rollen sollten nicht für das Verteilen bzw. Zugänglichmachen von Plugins (Module, Filter, etc.) genutzt werden. Denn Plugins aus Rollen können nicht (ohne Weiteres) außerhalb der Rolle selbst genutzt werden.
Die Problematik möchte ich an einem Beispiel deutlich machen. Eine Rolle mit eigenen Plugins – hier ein Modul und ein Filter – könnte beispielsweise so aussehen:
netways.myrole/
├── defaults
│ └── main.yml
├── filter_plugins
│ └── myfilter.py
├── handlers
│ └── main.yml
├── library
│ └── mymodule.py
├── meta
│ └── main.yml
├── tasks
│ └── main.yml
└── vars
└── main.ymlDie folgenden Code-Blöcke zeigen den Inhalt der relevanten Dateien.
ibrary/mymodule.py:
from ansible.module_utils.basic import AnsibleModule
DOCUMENTATION = '''
name: mymodule
short_description: Test module
description:
- Just a test module that echoes its input
version_added: 1.0.0
author:
- Matthias Döhler
options:
name:
description:
- A name to echo
required: true
type: str
'''
EXAMPLES = '''
mymodule:
name: "John"
'''
def main():
module = AnsibleModule(
argument_spec=dict(
name=dict(required=True, type='str'),
)
)
args = module.params
module.exit_json(
changed=False,
name=args['name'],
echoed_name=args['name'],
)
if __name__ == '__main__':
main()
filter_plugins/myfilter.py:
def my_filter(_input):
result = f'"{_input}" went through "myfilter"'
return result
class FilterModule(object):
def filters(self):
return {
"myfilter": my_filter,
}Es wird über eine Funktion ein Filter definiert, der einen übergebenen Parameter transformiert und das Ergebnis zurückgibt.
Die KlasseFilterModuleübernimmt die interne Übersetzung des Filternamens zur passenden Funktion.
Wenn das Filter Plugin jetzt in einem Play genutzt werden soll, kommt es zu folgendem Fehler.
play.yml:
- name: Test
hosts: localhost
tasks:
- name: Short name
ansible.builtin.debug:
msg: "{{ 'my custom message' | myfilter }}"
- name: FQCN
ansible.builtin.debug:
msg: "{{ 'my custom message' | netways.myrole.myfilter }}"
TASK [Short name] ****************************************************************************************************************************************************
[ERROR]: Task failed: Finalization of task args for 'ansible.builtin.debug' failed: Error while resolving value for 'msg': Syntax error in template: No filter named 'myfilter'. Der Filter myfilter wurde von Ansible nicht gefunden. Auch der Versuch, den FQCN zu verwenden, scheitert.
Hier gibt es nun zwei Lösungen:
Ausführen der Rolle
Wird die Rolle im Play direkt genutzt, können innerhalb desselben Plays Plugins aus dieser Rolle aufgerufen und genutzt werden.
play.yml:
- name: Test
hosts: localhost
roles:
- netways.myrole
tasks:
- name: Short name
ansible.builtin.debug:
msg: "{{ 'my custom message' | myfilter }}"
- name: FQCN
ansible.builtin.debug:
msg: "{{ 'my custom message' | netways.myrole.myfilter }}"Dabei entstehen jedoch drei Probleme.
Der FQCN ist hier in diesem Kontext nicht nutzbar. Ansible versteht die Notation <Rollenname>.<Pluginname> nicht. Entsprechend wird netways.myrole.myfilter von Ansible nicht gefunden und der zweite Task scheitert nach wie vor.
Technisch gesehen sind die Plugins als
ansible.legacy.<Name des Plugins>aufrufbar.
Das zweite Problem hängt eng mit dem ersten Problem zusammen: Die Möglichkeit von Namenskollisionen.
Die Funktion my_filter könnte zusätzlich beispielsweise auch unter dem Namen first exportiert werden. Über die Kurzschreibweisen myfilter und first könnte dann derselbe Filter im Hintergrund genutzt werden.
Damit wäre der Filter ansible.builtin.first in seiner Kurzschreibweise überschrieben, was im weiteren Verlauf einer Playbook-Ausführung zu erheblichen Problemen führen kann.
Eine Rolle X, die nach netways.myrole genutzt wird, verwendet evtl. keinen FQCN für Filter und verlässt sich auf die Kurzschreibweise first. Dadurch nutzt sie dann aber effektiv den Filter first aus netways.myrole.
Über diesen Mechanismus können sich also sogar Rollen gegenseitig beeinflussen, was die Problemlösung erschwert.
Erschwerend kommt hinzu, dass in Rollen innerhalb moderner Collections bei der Filternutzung oft auf den FQCN verzichtet wird. Ansible vermeidet hier nämlich Namenskollisionen weitestgehend, indem Filter aus zusätzlichen Collections gar nicht als Kurzschreibweise verfügbar gemacht werden. Für eigene Filter ist hier der FQCN also ohnehin zwingend erforderlich.
Das dritte Problem ist offensichtlich: Die Rolle muss ausgeführt werden. Das bedeutet, dass auch die Tasks aus der Rolle jedes Mal ausgeführt werden müssen, damit man im weiteren Verlauf auf die Plugins zugreifen kann. Das wird selten das gewünschte Verhalten sein.
Wenn es keine Tasks in der Rolle gibt, stellt das Ganze kein Problem dar. Eine Rolle ohne Tasks ist aber unheimlich selten und spiegelt weder den neuen Collection-Ansatz, noch den alten Rollen-Ansatz wider.
Bonus-Problem: Manche Arten von Plugins, wie etwa Inventory Plugins, müssen vor der Playbook-Ausführung geladen werden. Der Trick, die Rolle zuerst auszuführen, funktioniert hier nicht. Wir haben ein Henne-Ei-Problem.
Konfigurationsanpassungen
Ansible nutzt für Plugins verschiedene Suchpfade. Plugins aus Collections sind automatisch verfügbar, sofern die Collections von Ansible gefunden werden. Die Collections müssen also nur in den korrekten Pfad kopiert bzw. installiert werden.
Für Plugins außerhalb von Collections – ob einzelne Dateien oder in alten Rollen – muss der Suchpfad von Ansible erweitert werden.
Folgende Beispielkonfiguration erweitert die Suchpfade um einen Ordner mit selbstgeschriebenen Inventory Plugins.
[defaults]
inventory_plugins=/usr/share/ansible/plugins/inventory:/home/matthias/ansible_plugins/inventoryDas Problem dieses Ansatzes wird schnell deutlich, wenn auch Plugins von alleinstehenden Rollen genutzt werden sollen:
[defaults]
inventory_plugins=/usr/share/ansible/plugins/inventory:/home/matthias/ansible_plugins/inventory:/home/matthias/ansible_roles/role1/inventory_plugins:/home/matthias/ansible_roles/role2/inventory_pluginsFür jede alleinstehende Rolle muss der Suchpfad entsprechend angepasst werden. Zusätzlich hat jede Plugin-Art eine eigene Konfigurationsoption, was den Pflegeaufwand zusätzlich erhöht. Der zeitliche (und nervliche) Aufwand ist hier schlicht nicht zu rechtfertigen.
Bei beiden Szenarien muss man außerdem bedenken, dass dieser zusätzliche Aufwand, die Tricks, die Suchpfade, etc. nichts sind, was der Rollenersteller den Nutzern abnehmen kann. Jeder Nutzer einer solchen Rolle steht exakt vor demselben Problem und muss eine Lösung umsetzen.
Ansible-Setup mit vielen alten Rollen?
Unsere Consultants unterstützen dich bei der Migration auf Collections und beim laufenden Betrieb deiner Ansible-Umgebung.
Kostenlose Beratung anfragen →
Was jetzt?
Um mit dem modernen Ansatz von Ansible kompatibel zu sein, empfiehlt es sich, alleinstehende Rollen – speziell mit Plugins – in Collections zu überführen. Rollen können thematisch zu Collections zusammengeführt oder in eine „miscellaneous“ Collection eingebunden werden, wenn es keinen thematischen Zusammenhang gibt. Auch die Erstellung einer neuen Collection mit nur einer Rolle ist ein valider Weg.
Die Beispiel-Rolle von oben könnte als Collection folgende Struktur haben:
netways/misc/
├── galaxy.yml
├── plugins
│ ├── filter
│ │ └── myfilter.py
│ └── modules
│ └── mymodule.py
└── roles
└── myrole
├── defaults
│ └── main.yml
├── handlers
│ └── main.yml
├── meta
│ └── main.yml
├── tasks
│ └── main.yml
└── vars
└── main.ymlIm Prinzip wird die Rolle in den roles/-Ordner der Collection kopiert und der Inhalt aus library/ nach plugins/modules/ innerhalb der Collection verschoben. Für andere Arten von Plugins wird der Inhalt des jeweiligen Ordners aus der Rolle nach plugins/<Art des Plugins>/ verschoben.
| Art des Plugins | Pfad in der Rolle | Pfad in der Collection |
|---|---|---|
| Modul | library/ | plugins/modules/ |
| Filter | filter_plugins/ | plugins/filter/ |
| Test | test_plugins/ | plugins/test/ |
| … | … | … |
Nach dem Umbau und der Integration einer alleinstehenden Rolle in eine Collection sind die Plugins nun auch via FQCN ansteuerbar. Die Plugins sollten zur Sicherheit noch getestet werden, sollten in aller Regel jedoch weiter wie gewohnt funktionieren. Bestehende Referenzen auf die Kurzschreibweise von Plugins sollten durch den passenden FQCN ausgetauscht werden. Jetzt gilt es nur noch, Referenzen auf die alte Rolle in Playbooks durch den Verweis auf die neue Rolle innerhalb der Collection auszutauschen.
Fazit: Ansible Rolle oder Collection
„Never change a running system“ ist oftmals ein gutes Mantra für Stabilität. Aber speziell beim Thema Automatisierung sollte man stets am Ball bleiben, um von Verbesserungen, quality of life features, und neuen Möglichkeiten zu profitieren. Collections haben sich jetzt schon einige Zeit etabliert. In Summe kostet es evtl. sogar mehr Zeit, alte, alleinstehende Rollen zu nutzen und um Probleme herum zu arbeiten, weil hier einfach die komfortablen Möglichkeiten von Collections fehlen.
Wenn dir in nächster Zeit Probleme beim Umgang mit alleinstehenden Rollen auffallen oder Du dir deiner eigenen Workarounds bewusst wirst, ist das vermutlich ein guter Zeitpunkt, voll in die Ära der Collections einzutauchen.
