ansible-galaxy CLI : init, install, list, search, remove, info

ansible-galaxy est la commande qui crée, installe, inspecte et publie du contenu réutilisable. Elle sert deux familles d'objets qui ne se comportent pas de la même façon, les rôles et les collections, et c'est cette dualité qui déroute au début : les deux familles n'acceptent ni les mêmes sous-commandes, ni les mêmes options.

Cette page pose d'abord cette distinction, puis parcourt le cycle de vie complet, de la création d'un squelette à la publication.

Ce que vous allez apprendre

Distinguer ce qu'ansible-galaxy sait faire sur un rôle et sur une collection.
Chercher un rôle avant de l'installer, et lire ce que Galaxy en dit.
Installer depuis Galaxy, depuis Git ou depuis une archive locale, au bon endroit.
Inspecter ce qui est installé et d'où cela vient.

Prérequis

ansible-core installé, vérifiable avec ansible-galaxy --version.
Avoir lu Découvrir les rôles pour la notion de rôle.

Deux familles, deux jeux de commandes

La première chose à comprendre est que ansible-galaxy se décline en deux sous-commandes principales, et que leurs capacités diffèrent.

Sous-commande	Rôle	Collection
`init`	oui	oui
`install`	oui	oui
`list`	oui	oui
`remove`	oui	non
`search`, `info`	oui	non
`build`, `publish`	non	oui
`verify`, `download`	non	oui
`import`, `setup`, `delete`	oui	non

Cette page suit le cycle de vie du contenu que vous consommez : le chercher, l'installer, l'inspecter, le supprimer. Le versant production relève d'autres pages : la création d'un squelette avec init est traitée dans Structure standard d'un rôle et dans Créer une collection, la construction et la publication d'une archive dans Versionner et publier.

Chercher avant d'installer

Deux commandes existent, réservées aux rôles.

# Rechercher, avec filtres
ansible-galaxy role search nginx --author geerlingguy
ansible-galaxy role search nginx --platforms EL
ansible-galaxy role search nginx --galaxy-tags web

# Détail d'un rôle
ansible-galaxy role info geerlingguy.nginx

role info renvoie bien plus qu'une description : le dernier commit indexé, la date de création, le dépôt GitHub d'origine et le nombre de téléchargements. Ce dernier chiffre est un signal d'adoption utile avant de confier à un rôle tiers les droits de votre automatisation, sujet développé dans Auditer un rôle existant.

Installer du contenu

L'installation accepte trois provenances, et le choix de la destination compte autant que celui de la source.

Depuis Galaxy

ansible-galaxy role install geerlingguy.nginx
ansible-galaxy collection install community.general

Sans autre précision, les rôles atterrissent dans ~/.ansible/roles/ et les collections dans ~/.ansible/collections/, donc hors de votre projet et invisibles pour vos collègues.

Depuis un dépôt Git

La syntaxe empile jusqu'à trois informations séparées par des virgules : l'URL, la référence, puis le nom local.

# URL seule : la branche par défaut du dépôt
ansible-galaxy role install git+https://github.com/geerlingguy/ansible-role-nginx.git

# Avec un tag précis
ansible-galaxy role install git+https://github.com/geerlingguy/ansible-role-nginx.git,3.1.0

# Avec un nom local choisi
ansible-galaxy role install git+https://github.com/geerlingguy/ansible-role-nginx.git,3.1.0,nginx

Le troisième argument n'est pas un raffinement : sans lui, le rôle prend le nom du dépôt. Une installation depuis ansible-role-nginx produit un répertoire ansible-role-nginx, et votre playbook qui appelle - role: nginx ne trouvera rien.

- extracting ansible-role-nginx to .../roles/ansible-role-nginx
- ansible-role-nginx (3.1.0) was installed successfully

Depuis une archive locale

Une collection déjà construite s'installe directement depuis son fichier .tar.gz, sans passer par Galaxy. C'est la seule voie possible sur une machine sans accès Internet, et c'est aussi le meilleur moyen de tester une collection que vous venez de construire, avant de la publier à d'autres.

ansible-galaxy collection install ./dist/acme-tools-1.0.0.tar.gz -p ./installed

Choisir la destination avec `-p`

ansible-galaxy role install -r requirements.yml -p ./roles/
ansible-galaxy collection install -r requirements.yml -p ./collections/

L'option -p installe dans le projet plutôt que dans votre répertoire personnel. C'est ce qui rend une chaîne d'intégration reproductible : l'environnement de build repart d'un répertoire vide et n'hérite de rien.

Le format du fichier requirements.yml est détaillé dans Installer des rôles depuis Galaxy.

Inspecter ce qui est installé

# Les rôles, avec leur version quand elle est connue
ansible-galaxy role list

# Les collections, tous chemins confondus
ansible-galaxy collection list

# Filtrer sur une collection précise
ansible-galaxy collection list community.general

# Sortie exploitable par un script
ansible-galaxy collection list --format json

La sortie de role list mérite un mot, car elle révèle une propriété importante des rôles :

- nginx, 3.1.0
- stephrobert.users, (unknown version)

(unknown version) apparaît dès qu'un rôle a été installé sans référence explicite. La commande ne peut donc pas toujours répondre à la question « quelle version ai-je installée », et Versionner et publier explique pourquoi.

Le format JSON, lui, renvoie un dictionnaire par chemin d'installation, ce qui permet de détecter une collection présente en double :

{
  "/home/bob/.ansible/collections/ansible_collections": {
    "community.general": {"version": "11.4.7"}
  }
}

Vérifier l'intégrité d'une collection

ansible-galaxy collection verify community.general

La commande télécharge l'archive officielle, compare les empreintes fichier par fichier avec votre copie locale, et signale les écarts.

Verifying 'community.general:11.4.7'.
MANIFEST.json hash: 98db0158caa1504b21feaf146cc8c3a734ba5565b104a1fd4de41138843d1fd9
Collection community.general contains modified content in the following files:
    plugins/connection/__pycache__

Un détail surprend au premier usage : les répertoires __pycache__ remontent systématiquement comme contenu modifié. Ils sont créés par Python à la première exécution, donc absents du manifeste d'origine. Ce n'est pas une altération, mais cela oblige à lire la liste au lieu de se fier au seul verdict.

Supprimer

La suppression d'un rôle est immédiate, et l'option -p s'applique ici aussi : sans elle, la commande cherche dans votre répertoire personnel et ne trouvera pas un rôle installé dans le projet.

ansible-galaxy role remove nginx

# Dans un chemin de projet
ansible-galaxy role remove nginx -p ./roles/

Il n'existe aucune commande équivalente pour les collections. La suppression se fait à la main :

rm -rf ~/.ansible/collections/ansible_collections/community/general

Cibler un autre serveur que Galaxy

Toutes les commandes qui contactent un serveur acceptent --server, et lisent par défaut la liste déclarée dans ansible.cfg.

ansible-galaxy collection install community.general --server https://hub.corp.example.com/api/automation-hub/

La configuration d'un Automation Hub interne et ses conséquences sur l'authentification sont décrites dans Versionner et publier.

Mettre en pratique

La dualité rôle / collection ne s'ancre qu'en parcourant le cycle entier sur une machine. Le lab vous fait écrire un script qui crée un rôle puis une collection, construit l'archive de cette collection, l'installe depuis le disque sans passer par Galaxy, et relit enfin l'inventaire avec list. Tout se joue hors ligne, et les tests exécutent votre script pour inspecter le disque plutôt que la liste de commandes que vous auriez recopiée.

CLI ansible-galaxy : init, install, list, build, publish

$ dsoxlab run galaxy-ansible-galaxy-cli

Environnement : Shell·Durée : ~20 min

Validé : la sortie produite est comparée au résultat attendu.

Première fois ? Qu'est-ce que dsoxlab et comment l'installer

dsoxlab est la ligne de commande qui prépare un environnement jetable (un shell isolé ou une VM), déroule le scénario du lab, puis vérifie l'état réel du système et calcule un score. Rien n'est installé ni cassé sur votre poste de travail.

Installer la CLI dsoxlab, une seule fois :

uv tool install dsoxlab   # ou : pipx install dsoxlab
git clone https://github.com/stephrobert/ansible-training.git
cd ansible-training

Lancer ce lab, puis valider votre travail :

dsoxlab run galaxy-ansible-galaxy-cli
dsoxlab check galaxy-ansible-galaxy-cli

Voir tous les labs : dsoxlab list-labs. Suivre sa progression : dsoxlab progress.

Pièges courants

Symptôme	Cause	Solution
`the role 'nginx' was not found` après une installation Git	Le rôle porte le nom du dépôt	Ajouter le nom local en troisième argument
`(unknown version)` dans `role list`	Rôle installé sans référence Git	Épingler une `version:` dans `requirements.yml`
Aucune commande pour désinstaller une collection	Elle n'existe pas	Supprimer le répertoire à la main
`verify` signale `__pycache__`	Fichiers générés par Python après installation	Sans gravité, lire la liste des écarts réels

À retenir

Les rôles et les collections n'acceptent pas les mêmes commandes : pas de remove pour une collection, pas de build ni publish pour un rôle.
Une installation depuis Git nomme le rôle d'après le dépôt, sauf troisième argument explicite.
-p installe dans le projet plutôt que dans le répertoire personnel, ce qui rend une chaîne d'intégration reproductible.
(unknown version) dans role list signale un rôle installé sans référence Git.

Pour aller plus loin

Auditer un rôle existant : ce qu'il faut regarder avant de lancer install sur un contenu que vous ne connaissez pas.
Versionner et publier : l'autre bout de la chaîne : build, publish et role import vus depuis le producteur.
RHEL System Roles : une bibliothèque concrète à installer puis à inspecter avec les commandes vues ici.