volant galaxy
Les options d'ansible-galaxy, vérifiées par Volant lui-même, pendant que ses sous-commandes deviennent natives une par une.
volant galaxy accepte les sous-commandes et les options d’ansible-galaxy d’ansible-core 2.19.12 : les scripts et les jobs de CI écrits pour lui gardent leurs lignes de commande. Il est en cours de réécriture dans Volant, sans le runtime Python. Aujourd’hui il lit les options et fait les vérifications qu’ansible-galaxy fait en premier, puis refuse la sous-commande tant que sa version native n’est pas là.
volant galaxy collection <download|init|build|publish|install|list|verify> [OPTIONS]volant galaxy role <init|remove|delete|list|search|import|setup|info|install> [OPTIONS]Chaque sous-commande accepte -s/--server, --token/--api-key, -c/--ignore-certs, --timeout et -v, qui peut être répété. collection download et collection install acceptent aussi --clear-response-cache et --no-cache. Une option inconnue, ou une valeur du mauvais type, sort avec 2 et affiche l’usage. volant galaxy --version affiche le bloc de version d’ansible-galaxy.
Les premières vérifications
Section intitulée « Les premières vérifications »Elles passent avant tout travail, avec les messages et les codes de sortie d’ansible-galaxy :
| Cas | Message | Sortie |
|---|---|---|
collection install avec des noms et -r |
[ERROR]: The positional collection_name arg and --requirements-file are mutually exclusive. |
1 |
collection install ou download sans l’un ni l’autre |
[ERROR]: You must specify a collection name or a requirements file. |
1 |
-r désigne un fichier qui n’existe pas |
[ERROR]: The requirements file '<path>' does not exist. |
1 |
role install sans nom ni -r |
[ERROR]: - you must specify a user/role name or a roles file |
5 |
role install -r avec un fichier qui ne finit pas par .yml ou .yaml |
[ERROR]: Invalid role requirements file, it must end with a .yml or .yaml extension |
1 |
role list sans aucun chemin de rôles existant |
[WARNING]: - the configured path <path> does not exist. pour chaque chemin, puis [ERROR]: - None of the provided paths were usable. Please specify a valid path with --roles-path |
5 |
Quand aucun chemin de collections configuré ne se trouve sous le PATH de collection install -p PATH, la commande affiche d’abord l’avertissement d’ansible-galaxy : [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. Le répertoire collections/ du runtime, que Volant ajoute en dernier au chemin des collections, n’apparaît pas dans <paths>.
Installer depuis une archive
Section intitulée « Installer depuis une archive »collection install installe nativement une archive de collection : volant galaxy collection install acme-demo-1.0.0.tar.gz -p DIR. Le nom et la version viennent du MANIFEST.json de l’archive, pas du nom du fichier. La collection va sous DIR/ansible_collections/<namespace>/<name>, ou sous le premier chemin de collections sans -p. Seuls les fichiers que liste FILES.json sont écrits, chacun vérifié d’abord contre son SHA-256. Un fichier est en 0644, ou en 0755 quand l’archive le marque exécutable. Une entrée qui atterrirait hors de la collection est refusée, tout comme un lien qui pointe hors d’elle. Une installation qui échoue ne laisse aucune collection à moitié écrite. La sortie, les messages et les codes de sortie sont ceux d’ansible-galaxy. Une collection déjà installée à la même version donne Nothing to do. All requested collections are already installed. If you want to reinstall them, consider using –force., et --force la réinstalle par-dessus l’ancien arbre. Quand PATH/ansible_collections existe déjà, l’avertissement de -p dit que le chemin appears to be part of the pip Ansible package, comme le dit ansible-galaxy.
collection install accepte aussi un dépôt git : git+<url>, avec ,<ref> pour une branche, une étiquette ou un commit, HEAD par défaut, et #/<subdir> pour une collection qui n’est pas à la racine du dépôt, comme git+https://host/org/repo.git,v1.0.0 ou git+file:///work/mono/.git#/collections/demo. Dans un fichier de prérequis, c’est une entrée avec type: git, dont la version est la référence. Volant lance le git du système : un clone superficiel pour HEAD, un clone complet suivi d’une extraction sinon, puis installe l’extraction comme une arborescence source. Un dépôt sans collection à sa racine installe chaque collection de ses sous-répertoires directs. Si une collection dépend d’une URL git+, ce dépôt est aussi cloné, sauf avec --no-deps. Ce qui vient d’un dépôt n’a pas de version à comparer, et se réinstalle donc à chaque exécution. Une version qui ne suit pas SemVer arrête l’installation avec Invalid version found for the collection, code 1. Les messages de git arrivent au terminal, comme avec ansible-galaxy. Un mot de passe dans l’URL est remplacé par ******** dans tous les messages. Sans git dans le PATH, la commande échoue avec Could not find git executable to extract the collection from the Git repository, code 1.
Les URL d’archives, les répertoires d’espace de noms et les signatures sont refusés tant qu’ils ne sont pas natifs : [ERROR]: volant galaxy collection install from a URL or a namespace directory is not supported yet, ou with signatures, code 1.
Créer une collection
Section intitulée « Créer une collection »collection init <namespace>.<name> [--init-path DIR] [--collection-skeleton DIR] [-e VARS] [-f] écrit une nouvelle collection sous DIR/<namespace>/<name>, ./ par défaut, et affiche - Collection <namespace>.<name> was created successfully. Sans squelette, il écrit le squelette par défaut d’ansible-core 2.19.12 : galaxy.yml, README.md, meta/runtime.yml, plugins/README.md et les répertoires vides docs/ et roles/. --collection-skeleton, ou GALAXY_COLLECTION_SKELETON, désigne à la place un répertoire de squelette à copier. Ses fichiers .j2 sont rendus avec --extra-vars et perdent leur extension, sauf sous playbooks/*/templates et roles/*/templates. Ses liens restent des liens, et ce que GALAXY_COLLECTION_SKELETON_IGNORE désigne est laissé de côté. Un répertoire de collection qui existe déjà est une erreur, sauf avec -f, qui le vide d’abord. Les messages et les codes de sortie sont ceux d’ansible-galaxy.
Construire une collection
Section intitulée « Construire une collection »collection build [PATH] [--output-path DIR] [-f] transforme une arborescence source dotée d’un galaxy.yml, . par défaut, en <namespace>-<name>-<version>.tar.gz dans DIR, ./ par défaut, et affiche Created collection for <namespace>.<name> at <path>. galaxy.yml demande namespace, name, version, readme et authors ; une clé manquante, ou un galaxy.yml absent, échoue avec le message d’ansible-galaxy. L’archive contient MANIFEST.json, FILES.json et l’arborescence, sans ce qu’ansible-galaxy laisse de côté : galaxy.yml, .git et les autres répertoires de gestion de versions, __pycache__, *.pyc, *.retry, tests/output, les artefacts précédents de la collection, et ce que liste build_ignore. Un fichier est en 0644, ou en 0755 quand son propriétaire peut l’exécuter ; un lien interne à l’arborescence reste un lien, et un lien vers un répertoire extérieur est sauté avec un avertissement. Un artefact existant est une erreur sauf avec -f. Volant écrit toutes les dates à 0 et tous les propriétaires à root : construire deux fois la même arborescence donne les mêmes octets ; ansible-galaxy y met l’heure courante. Un galaxy.yml avec une clé manifest: est refusé pour l’instant.
collection install DIR installe une arborescence source de la même façon, sans archive, et affiche Created collection for <namespace>.<name>:<version> at <path> entre ses lignes Installing et installed successfully. collection download construit une arborescence source dans le dossier de téléchargement.
Installer depuis des serveurs Galaxy
Section intitulée « Installer depuis des serveurs Galaxy »collection install accepte aussi des noms, avec une plage au besoin : demo.base, demo.base:1.0.0, "demo.base:>=1.0.0,<2.0.0", et les entrées de -r. Chaque nom est résolu auprès des serveurs avec ses dépendances, chacune à la plus haute version qui satisfait toutes les plages demandées, en revenant en arrière quand deux plages se contredisent. Les pré-versions ne comptent qu’avec --pre ou quand elles sont nommées exactement. Chaque archive est téléchargée, vérifiée contre le SHA-256 que donne le serveur, puis décompressée comme ci-dessus. Une collection installée depuis un serveur reçoit aussi ansible_collections/<namespace>.<name>-<version>.info/GALAXY.yml, qui note sa provenance. Une collection déjà installée à une version qui convient est gardée : '<name>:<version>' is already installed, skipping.
-n saute les dépendances, -U amène les collections installées à la plus récente version de la plage, -f réinstalle les collections demandées et --force-with-deps aussi leurs dépendances, -i continue après une installation échouée avec un avertissement, et --offline n’interroge aucun serveur. Quand aucun jeu de versions ne satisfait toutes les plages, la commande échoue avec le message d’ansible-galaxy, qui liste les plages et se termine par un conseil sur --pre ; les objets Python qu’ansible-galaxy affiche après ce conseil sont omis.
Télécharger pour une installation hors ligne
Section intitulée « Télécharger pour une installation hors ligne »collection download résout les collections demandées avec leurs dépendances, comme install, et enregistre chaque archive dans le dossier que nomme -p, ./collections par défaut. Il y écrit ensuite un requirements.yml qui liste les archives par nom de fichier, avec leurs versions. Sur une machine sans réseau, volant galaxy collection install --offline -r requirements.yml lancé depuis ce dossier les installe sans interroger aucun serveur. Les noms de fichiers sont lus depuis le répertoire de travail, comme les lit ansible-galaxy. -n laisse les dépendances de côté, et -r et --pre fonctionnent comme pour install. Avec --offline, un nom qu’aucune archive ne fournit, ou une dépendance qui n’est pas installée, échoue avec le message du résolveur.
Lister et vérifier les collections
Section intitulée « Lister et vérifier les collections »collection list [NAME] [-p PATH]... [--format human|json|yaml] affiche, pour chaque répertoire de -p et du chemin des collections qui contient des collections, un bloc # <path>/ansible_collections avec le nom et la version de chaque collection, la version étant * quand la collection n’a pas de MANIFEST.json. Les colonnes sont aussi larges que le plus long nom et la plus longue version, comme ansible-galaxy les complète. --format json affiche {"<path>": {"<namespace>.<name>": {"version": "<version>"}}} sur une ligne, et --format yaml la même chose en YAML. Un -p qui n’existe pas donne un avertissement ; quand aucun chemin n’est lisible, la commande échoue avec le code 5. ansible-galaxy liste aussi la collection qu’ansible-core garde dans son propre paquet Python, ansible._protomatter ; Volant, qui n’a pas ce paquet, ne la liste pas.
collection verify NAME... [-p PATH] [--offline] vérifie chaque collection installée : MANIFEST.json, puis FILES.json contre l’empreinte que donne le manifeste, puis chaque fichier contre la sienne, puis l’arborescence à la recherche de fichiers et de répertoires que FILES.json ne liste pas, *.pyc exceptés. Chaque différence est listée sous Collection <name> contains modified content in the following files:, et la commande sort avec 1. Sans --offline, l’archive du serveur pour la même version est téléchargée et son MANIFEST.json fait référence ; avec, c’est celui qui est installé. Une collection non installée, ou sans MANIFEST.json, est une erreur ; -i change les erreurs en avertissements.
Installer et gérer les rôles
Section intitulée « Installer et gérer les rôles »role install NAME... [-p PATH] [-r FILE] installe chaque rôle dans le premier chemin de rôles : -p, ou le premier configuré. Un nom s’écrit owner.role[,version[,name]] et se cherche par l’API v1 du premier serveur ; sans version, c’est la plus haute que liste le serveur, puis la branche du dépôt, puis master. Un chemin vers une archive, une URL et une source git+ s’installent aussi ; une archive ou une source git prend son nom de rôle dans le troisième champ de la ligne, ou dans le chemin quand ce champ est vide. Le répertoire de tête de l’archive est retiré, et meta/.galaxy_install_info garde la version et la date d’installation. Un rôle déjà installé dans la même version est sauté ; dans une autre version, il donne un avertissement et reste en place, sauf si --force le remplace. Les dépendances de meta/main.yml et de meta/requirements.yml suivent, sauf avec -n ; --force-with-deps remplace celles déjà installées. Un rôle qui échoue donne un avertissement, et la commande sort avec 1 sauf si -i la laisse continuer. -g garde le répertoire .git d’un rôle git.
role list [NAME] [-p PATH] affiche chaque chemin de rôles sous la forme # <path>, puis - <role>, <version> pour chaque rôle qu’il contient, (unknown version) quand le rôle n’a pas d’informations d’installation. role remove NAME... [-p PATH] supprime chaque rôle du premier chemin de rôles, avec - <role> is not installed, skipping. pour un répertoire qui ne contient pas de rôle.
Les serveurs Galaxy
Section intitulée « Les serveurs Galaxy »Les serveurs viennent de -s, sinon de [galaxy] server_list et des sections [galaxy_server.<name>] d’ansible.cfg, sinon de GALAXY_SERVER, https://galaxy.ansible.com par défaut. Chaque variable ANSIBLE_GALAXY_* passe avant le fichier. Chaque serveur accepte url, token, validate_certs et timeout. --token l’emporte sur le jeton du fichier, -c coupe la vérification des certificats, et --timeout fixe l’attente, 60 secondes par défaut. Un serveur injoignable est sauté avec l’avertissement d’ansible-galaxy, et le suivant est interrogé.
Le jeton part dans Authorization: Token <token> et n’est jamais affiché. Sans jeton, le fichier de jeton est lu, GALAXY_TOKEN_PATH, par défaut <ANSIBLE_HOME>/galaxy_token, créé vide en mode 0600 s’il manque. Les proxys viennent de https_proxy, http_proxy, all_proxy et no_proxy ; contrairement à ansible-galaxy, qui choisit la variable selon le schéma de l’URL, la première d’entre elles qui est définie s’applique à toutes les URL. Les réponses sont gardées un jour dans <ANSIBLE_HOME>/galaxy_cache/api.json, le même fichier qu’utilise ansible-galaxy. --no-cache le laisse de côté et --clear-response-cache le vide. username, password et auth_url ne sont pas lus.
Les fichiers de prérequis
Section intitulée « Les fichiers de prérequis »-r lit le fichier de prérequis comme ansible-galaxy : collections: et roles: dans un même fichier, ou l’ancienne liste simple de rôles, que seul role install accepte. Une entrée include: apporte les rôles d’un autre fichier, dont le chemin part du répertoire de travail. Quand -r est donné deux fois, c’est le dernier qui compte. Quand le fichier n’a aucune entrée pour la commande, collection install et role install affichent Skipping install, no requirements found et sortent avec 0. -vvv affiche d’abord Reading requirement file at '<path>'. Un fichier mal formé échoue avec le message d’ansible-galaxy, code 1 : aucune entrée, des clés autres que collections et roles, une entrée de rôle sans name ni src, un nom de collection qui n’est pas namespace.name et ne désigne rien, ou un type inconnu. Le source d’une entrée de collection nomme le serveur d’où elle s’installe, par son nom dans la liste des serveurs ou par son URL ; une autre URL est interrogée comme un serveur à part. Un source qui n’est ni l’un ni l’autre échoue avec Collections requirement 'source' entry should contain a valid Galaxy API URL but it does not: <source> is not an HTTP URL.
La sortie détaillée
Section intitulée « La sortie détaillée »-v compte après la sous-commande, comme pour ansible-galaxy ; ansible-galaxy ignore un -v écrit avant la sous-commande, et Volant le compte.
| Niveau | Ce qui s’ajoute |
|---|---|
-v |
Using <path> as config file, ou No config file found; using defaults. |
-vv |
Avant cette ligne, le bloc qu’affiche --version : ansible-galaxy [core <version>], config file, configured module search path, ansible collection location, executable location. Les lignes Python, Jinja et PyYAML ne viennent que si l’interpréteur du contrôleur répond, comme pour 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> ou 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. Les autres lignes HTTP d’ansible-galaxy (Calling Galaxy at, Found API version, le cache des réponses) ne sont pas affichées. |
ansible-galaxy signale aussi ansible._protomatter, la collection qu’ansible-core garde dans son propre paquet Python ; Volant n’a pas ce paquet et ne la signale jamais. role remove interroge le serveur Galaxy par défaut sur son API avant de supprimer quoi que ce soit, ce qui affiche Opened <token file> à -vvv ; Volant retire le rôle sans contacter de serveur.
Les sous-commandes refusées
Section intitulée « Les sous-commandes refusées »Une sous-commande qui n’est pas encore native échoue avec [ERROR]: volant galaxy <subcommand> is not supported yet, code 1. collection publish et role delete, search, import, setup et info demandent un compte Galaxy ou la base de rôles du serveur, et restent refusées : [ERROR]: volant galaxy <subcommand> is not supported, code 1.
volant runtime install --collections installe toujours les collections avec l’ansible-galaxy du runtime.