volant galaxy
Die Optionen von ansible-galaxy, von Volant selbst geprüft, während seine Unterbefehle einer nach dem anderen nativ werden.
volant galaxy nimmt die Unterbefehle und Optionen von ansible-galaxy aus ansible-core 2.19.12 an, damit Skripte und CI-Jobs, die dafür geschrieben sind, ihre Befehlszeilen behalten. Es wird gerade in Volant neu geschrieben, ohne die Python-Runtime. Heute liest es die Optionen und macht die Prüfungen, die ansible-galaxy zuerst macht, und lehnt dann den Unterbefehl ab, bis dessen native Version da ist.
volant galaxy collection <download|init|build|publish|install|list|verify> [OPTIONS]volant galaxy role <init|remove|delete|list|search|import|setup|info|install> [OPTIONS]Jeder Unterbefehl nimmt -s/--server, --token/--api-key, -c/--ignore-certs, --timeout und -v an, das wiederholt werden kann. collection download und collection install nehmen auch --clear-response-cache und --no-cache an. Eine unbekannte Option oder ein Wert der falschen Art endet mit 2 und gibt die Verwendung aus. volant galaxy --version gibt den Versionsblock von ansible-galaxy aus.
Die ersten Prüfungen
Abschnitt betitelt „Die ersten Prüfungen“Sie kommen vor jeder Arbeit, mit den Meldungen und Exit-Codes von ansible-galaxy:
| Fall | Meldung | Exit |
|---|---|---|
collection install mit Namen und -r |
[ERROR]: The positional collection_name arg and --requirements-file are mutually exclusive. |
1 |
collection install oder download ohne beides |
[ERROR]: You must specify a collection name or a requirements file. |
1 |
-r nennt eine Datei, die es nicht gibt |
[ERROR]: The requirements file '<path>' does not exist. |
1 |
role install ohne Namen und ohne -r |
[ERROR]: - you must specify a user/role name or a roles file |
5 |
role install -r mit einer Datei, die nicht auf .yml oder .yaml endet |
[ERROR]: Invalid role requirements file, it must end with a .yml or .yaml extension |
1 |
role list, wenn keiner der Rollenpfade existiert |
[WARNING]: - the configured path <path> does not exist. für jeden Pfad, danach [ERROR]: - None of the provided paths were usable. Please specify a valid path with --roles-path |
5 |
Liegt kein konfigurierter Collections-Pfad unter dem PATH von collection install -p PATH, gibt der Befehl zuerst die Warnung von ansible-galaxy aus: [WARNING]: The specified collections path '<PATH>' is not part of the configured Ansible collections paths '<paths>'. The installed collection will not be picked up in an Ansible run, unless within a playbook-adjacent collections directory. Das eigene collections/-Verzeichnis der Runtime, das Volant als letzten Eintrag an den Collections-Pfad anhängt, fehlt in <paths>.
Aus einem Tarball installieren
Abschnitt betitelt „Aus einem Tarball installieren“collection install installiert einen Collection-Tarball nativ: volant galaxy collection install acme-demo-1.0.0.tar.gz -p DIR. Name und Version kommen aus dem MANIFEST.json des Tarballs, nicht aus dem Dateinamen. Die Collection kommt nach DIR/ansible_collections/<namespace>/<name>, ohne -p unter den ersten Collections-Pfad. Geschrieben werden nur die Dateien, die FILES.json auflistet, jede zuerst gegen ihren SHA-256 geprüft. Eine Datei bekommt 0644, oder 0755, wenn das Archiv sie als ausführbar markiert. Ein Eintrag, der außerhalb der Collection landen würde, wird abgelehnt, ebenso ein Link, der aus ihr hinauszeigt. Eine fehlgeschlagene Installation hinterlässt keine halb geschriebene Collection. Ausgabe, Meldungen und Exit-Codes sind die von ansible-galaxy. Eine bereits in derselben Version installierte Collection ergibt Nothing to do. All requested collections are already installed. If you want to reinstall them, consider using –force., und --force installiert sie erneut über den alten Baum. Existiert PATH/ansible_collections schon, sagt die Warnung zu -p, der Pfad appears to be part of the pip Ansible package, wie ansible-galaxy es sagt.
collection install nimmt auch ein git-Repository an: git+<url>, mit ,<ref> für einen Branch, ein Tag oder einen Commit, standardmäßig HEAD, und #/<subdir> für eine Collection, die nicht an der Wurzel des Repositorys liegt, etwa git+https://host/org/repo.git,v1.0.0 oder git+file:///work/mono/.git#/collections/demo. In einer Anforderungsdatei ist es ein Eintrag mit type: git, dessen version die Referenz ist. Volant ruft das git des Systems auf: einen flachen Klon für HEAD, sonst einen vollständigen mit Checkout, und installiert den Checkout dann als Quellbaum. Ein Repository ohne Collection an der Wurzel installiert jede Collection in seinen direkten Unterverzeichnissen. Hängt eine Collection von einer git+-URL ab, wird auch dieses Repository geklont, außer mit --no-deps. Was aus einem Repository kommt, hat keine vergleichbare Version und wird bei jedem Lauf neu installiert. Eine Version, die nicht SemVer entspricht, bricht die Installation mit Invalid version found for the collection ab, Exit 1. Die Meldungen von git erreichen das Terminal, wie unter ansible-galaxy. Ein Passwort in der URL wird in jeder Meldung durch ******** ersetzt. Ohne git im PATH scheitert der Befehl mit Could not find git executable to extract the collection from the Git repository, Exit 1.
URLs zu Tarballs, Namespace-Verzeichnisse und Signaturen werden abgelehnt, bis sie nativ sind: [ERROR]: volant galaxy collection install from a URL or a namespace directory is not supported yet oder with signatures, Exit 1.
Eine Collection anlegen
Abschnitt betitelt „Eine Collection anlegen“collection init <namespace>.<name> [--init-path DIR] [--collection-skeleton DIR] [-e VARS] [-f] schreibt eine neue Collection nach DIR/<namespace>/<name>, standardmäßig ./, und gibt - Collection <namespace>.<name> was created successfully aus. Ohne Skeleton schreibt es das Standard-Skeleton von ansible-core 2.19.12: galaxy.yml, README.md, meta/runtime.yml, plugins/README.md und die leeren Verzeichnisse docs/ und roles/. --collection-skeleton oder GALAXY_COLLECTION_SKELETON nennt stattdessen ein Skeleton-Verzeichnis, das kopiert wird. Seine .j2-Dateien werden mit --extra-vars gerendert und verlieren die Endung, außer unter playbooks/*/templates und roles/*/templates. Seine Links bleiben Links, und was GALAXY_COLLECTION_SKELETON_IGNORE trifft, wird ausgelassen. Ein vorhandenes Collection-Verzeichnis ist ein Fehler, außer mit -f, das es zuerst leert. Meldungen und Exit-Codes sind die von ansible-galaxy.
Eine Collection bauen
Abschnitt betitelt „Eine Collection bauen“collection build [PATH] [--output-path DIR] [-f] macht aus einem Quellbaum mit galaxy.yml, standardmäßig ., die Datei <namespace>-<name>-<version>.tar.gz in DIR, standardmäßig ./, und gibt Created collection for <namespace>.<name> at <path> aus. galaxy.yml braucht namespace, name, version, readme und authors; ein fehlender Schlüssel oder eine fehlende galaxy.yml scheitert mit der Meldung von ansible-galaxy. Der Tarball enthält MANIFEST.json, FILES.json und den Baum, ohne das, was ansible-galaxy weglässt: galaxy.yml, .git und die anderen Verzeichnisse der Versionsverwaltung, __pycache__, *.pyc, *.retry, tests/output, frühere Artefakte der Collection und was build_ignore auflistet. Eine Datei bekommt 0644, oder 0755, wenn ihr Besitzer sie ausführen darf; ein Link innerhalb des Baums bleibt ein Link, einer auf ein Verzeichnis außerhalb wird mit einer Warnung übersprungen. Ein vorhandenes Artefakt ist ein Fehler, außer mit -f. Volant schreibt jede Zeit als 0 und jeden Besitzer als root, sodass zweimal derselbe Baum dieselben Bytes ergibt; ansible-galaxy setzt die aktuelle Zeit. Eine galaxy.yml mit einem Schlüssel manifest: wird vorerst abgelehnt.
collection install DIR installiert einen Quellbaum ebenso, ohne Tarball, und gibt Created collection for <namespace>.<name>:<version> at <path> zwischen seinen Zeilen Installing und installed successfully aus. collection download baut einen Quellbaum in den Download-Ordner.
Von Galaxy-Servern installieren
Abschnitt betitelt „Von Galaxy-Servern installieren“collection install nimmt auch Namen an, bei Bedarf mit einem Bereich: demo.base, demo.base:1.0.0, "demo.base:>=1.0.0,<2.0.0", und die Einträge von -r. Jeder Name wird mit seinen Abhängigkeiten gegen die Server aufgelöst, jede in der höchsten Version, die alle verlangten Bereiche erfüllt; widersprechen sich zwei Bereiche, geht die Auflösung zurück. Vorabversionen zählen nur mit --pre oder wenn sie genau genannt sind. Jeder Tarball wird heruntergeladen, gegen den SHA-256 des Servers geprüft und wie oben entpackt. Eine von einem Server installierte Collection bekommt außerdem ansible_collections/<namespace>.<name>-<version>.info/GALAXY.yml, das ihre Herkunft festhält. Eine schon in passender Version installierte Collection bleibt: '<name>:<version>' is already installed, skipping.
-n überspringt die Abhängigkeiten, -U bringt installierte Collections auf die neueste Version im Bereich, -f installiert die verlangten Collections neu und --force-with-deps auch ihre Abhängigkeiten, -i macht nach einer fehlgeschlagenen Installation mit einer Warnung weiter, und --offline fragt keinen Server. Erfüllt keine Auswahl von Versionen alle Bereiche, scheitert der Befehl mit der Meldung von ansible-galaxy, die die Bereiche auflistet und mit einem Hinweis zu --pre endet; die Python-Objekte, die ansible-galaxy danach ausgibt, fehlen.
Für eine Offline-Installation herunterladen
Abschnitt betitelt „Für eine Offline-Installation herunterladen“collection download löst die verlangten Collections mit ihren Abhängigkeiten auf, wie install, und speichert jeden Tarball in dem Ordner, den -p nennt, standardmäßig ./collections. Danach schreibt es dort eine requirements.yml, die die Tarballs nach Dateinamen mit ihren Versionen auflistet. Auf einem Rechner ohne Netz installiert volant galaxy collection install --offline -r requirements.yml, aus diesem Ordner gestartet, sie, ohne einen Server zu fragen. Die Dateinamen gelten vom Arbeitsverzeichnis aus, wie bei ansible-galaxy. -n lässt die Abhängigkeiten weg, und -r und --pre wirken wie bei install. Unter --offline scheitert ein Name, den kein Tarball liefert, oder eine nicht installierte Abhängigkeit mit der Meldung des Resolvers.
Collections auflisten und prüfen
Abschnitt betitelt „Collections auflisten und prüfen“collection list [NAME] [-p PATH]... [--format human|json|yaml] gibt für jedes Verzeichnis aus -p und aus dem Collections-Pfad, das Collections enthält, einen Block # <path>/ansible_collections mit Name und Version jeder Collection aus; die Version ist *, wenn die Collection kein MANIFEST.json hat. Die Spalten sind so breit wie der längste Name und die längste Version, wie ansible-galaxy sie auffüllt. --format json gibt {"<path>": {"<namespace>.<name>": {"version": "<version>"}}} in einer Zeile aus, --format yaml dasselbe als YAML. Ein nicht vorhandenes -p ergibt eine Warnung; ist kein Pfad lesbar, endet der Befehl mit Exit 5. ansible-galaxy listet auch die Collection, die ansible-core in seinem eigenen Python-Paket hält, ansible._protomatter; Volant hat kein solches Paket und listet sie nicht.
collection verify NAME... [-p PATH] [--offline] prüft jede installierte Collection: MANIFEST.json, dann FILES.json gegen den Hash im Manifest, dann jede Datei gegen ihren eigenen, dann den Baum auf Dateien und Verzeichnisse, die FILES.json nicht auflistet, *.pyc ausgenommen. Jeder Unterschied steht unter Collection <name> contains modified content in the following files:, und der Befehl endet mit 1. Ohne --offline wird der Tarball des Servers in derselben Version geladen, und sein MANIFEST.json ist die Referenz; mit --offline ist es das installierte. Eine nicht installierte Collection oder eine ohne MANIFEST.json ist ein Fehler; -i macht aus Fehlern Warnungen.
Rollen installieren und verwalten
Abschnitt betitelt „Rollen installieren und verwalten“role install NAME... [-p PATH] [-r FILE] installiert jede Rolle in den ersten Rollenpfad: -p oder den ersten konfigurierten. Ein Name hat die Form owner.role[,version[,name]] und wird über die API v1 des ersten Servers gesucht; ohne Version gilt die höchste, die der Server listet, dann der Branch des Repositorys, dann master. Ein Pfad zu einem Tarball, eine URL und eine git+-Quelle lassen sich ebenfalls installieren; ein Tarball oder eine Git-Quelle nimmt den Rollennamen aus dem dritten Feld der Zeile oder, wenn dieses leer ist, aus dem Pfad. Das oberste Verzeichnis des Archivs fällt weg, und meta/.galaxy_install_info hält Version und Installationsdatum fest. Eine Rolle, die in derselben Version schon installiert ist, wird übersprungen; in einer anderen Version gibt es eine Warnung und sie bleibt, außer --force ersetzt sie. Die Abhängigkeiten aus meta/main.yml und meta/requirements.yml folgen, außer mit -n; --force-with-deps ersetzt die schon installierten. Eine Rolle, die scheitert, ergibt eine Warnung, und der Befehl endet mit 1, außer -i lässt ihn weiterlaufen. -g behält das Verzeichnis .git einer Git-Rolle.
role list [NAME] [-p PATH] gibt jeden Rollenpfad als # <path> aus, danach - <role>, <version> für jede Rolle darin, (unknown version), wenn die Rolle keine Installationsangaben hat. role remove NAME... [-p PATH] löscht jede Rolle aus dem ersten Rollenpfad, mit - <role> is not installed, skipping. für ein Verzeichnis ohne Rolle.
Galaxy-Server
Abschnitt betitelt „Galaxy-Server“Die Server kommen aus -s, sonst aus [galaxy] server_list und den Abschnitten [galaxy_server.<name>] der ansible.cfg, sonst aus GALAXY_SERVER, standardmäßig https://galaxy.ansible.com. Jede Variable ANSIBLE_GALAXY_* geht der Datei vor. Jeder Server nimmt url, token, validate_certs und timeout an. --token schlägt das Token der Datei, -c schaltet die Zertifikatsprüfung ab, und --timeout legt die Wartezeit fest, standardmäßig 60 Sekunden. Ein nicht erreichbarer Server wird mit der Warnung von ansible-galaxy übersprungen, und der nächste wird gefragt.
Das Token geht als Authorization: Token <token> mit und wird nie ausgegeben. Ohne Token wird die Token-Datei gelesen, GALAXY_TOKEN_PATH, standardmäßig <ANSIBLE_HOME>/galaxy_token, die leer mit Modus 0600 angelegt wird, wenn sie fehlt. Proxys kommen aus https_proxy, http_proxy, all_proxy und no_proxy; anders als ansible-galaxy, das die Variable nach dem Schema der URL wählt, gilt die erste gesetzte für jede URL. Antworten bleiben einen Tag in <ANSIBLE_HOME>/galaxy_cache/api.json, derselben Datei, die ansible-galaxy nutzt. --no-cache lässt sie beiseite, --clear-response-cache leert sie. username, password und auth_url werden nicht gelesen.
Anforderungsdateien
Abschnitt betitelt „Anforderungsdateien“-r liest die Anforderungsdatei wie ansible-galaxy: collections: und roles: in einer Datei, oder die alte einfache Liste von Rollen, die nur role install annimmt. Ein Eintrag include: holt die Rollen einer anderen Datei, deren Pfad vom Arbeitsverzeichnis aus gilt. Wird -r zweimal angegeben, zählt das letzte. Hat die Datei keinen Eintrag für den Befehl, geben collection install und role install Skipping install, no requirements found aus und enden mit 0. -vvv gibt zuerst Reading requirement file at '<path>' aus. Eine fehlerhafte Datei scheitert mit der Meldung von ansible-galaxy, Exit 1: keine Einträge, andere Schlüssel als collections und roles, ein Rolleneintrag ohne name und ohne src, ein Collection-Name, der nicht namespace.name ist und auf nichts zeigt, oder ein unbekannter type. Das source eines Collection-Eintrags nennt den Server, von dem sie installiert wird, über seinen Namen in der Serverliste oder seine URL; eine andere URL wird als eigener Server abgefragt. Ein source, das keines von beiden ist, scheitert mit Collections requirement 'source' entry should contain a valid Galaxy API URL but it does not: <source> is not an HTTP URL.
Ausführliche Ausgabe
Abschnitt betitelt „Ausführliche Ausgabe“-v zählt nach dem Unterbefehl, wie bei ansible-galaxy; ansible-galaxy ignoriert ein -v vor dem Unterbefehl, Volant zählt es.
| Stufe | Was hinzukommt |
|---|---|
-v |
Using <path> as config file oder No config file found; using defaults. |
-vv |
Vor dieser Zeile der Block, den --version ausgibt: ansible-galaxy [core <version>], config file, configured module search path, ansible collection location, executable location. Die Zeilen zu Python, Jinja und PyYAML erscheinen nur, wenn der Interpreter des Controllers antwortet, wie bei volant adhoc. |
-vvv |
Reading requirement file at '<file>', found role <dict> in yaml file, Processing role <name> , Found installed collection <name>:<version> at '<path>', Created <token file> oder Opened <token file>, Collection '<name>:<version>' obtained from server <server> <url>, Remote collection cached as '<path>', Skipping '<path>' for collection build. |
-vvvv |
Validating downloaded file hash. Die übrigen HTTP-Zeilen von ansible-galaxy (Calling Galaxy at, Found API version, der Antwort-Cache) werden nicht ausgegeben. |
ansible-galaxy meldet auch ansible._protomatter, die Collection, die ansible-core in seinem eigenen Python-Paket hält; Volant hat kein solches Paket und meldet sie nie. role remove fragt vor dem Löschen den Standard-Galaxy-Server nach seiner API, was bei -vvv Opened <token file> ausgibt; Volant entfernt die Rolle, ohne einen Server zu kontaktieren.
Abgelehnte Unterbefehle
Abschnitt betitelt „Abgelehnte Unterbefehle“Ein Unterbefehl, der noch nicht nativ ist, endet mit [ERROR]: volant galaxy <subcommand> is not supported yet, Exit 1. collection publish und role delete, search, import, setup und info brauchen ein Galaxy-Konto oder die Rollendatenbank des Servers und bleiben abgelehnt: [ERROR]: volant galaxy <subcommand> is not supported, Exit 1.
volant runtime install --collections installiert Collections weiterhin mit dem ansible-galaxy der Runtime.