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

ansible-galaxy est la CLI pour gérer rôles et collections : créer un rôle vide, en installer depuis Galaxy/Git, lister ce qui est installé, supprimer, rechercher, et publier. Cette page passe en revue les commandes essentielles avec exemples concrets.

Pressé ? Les 8 commandes du quotidien

# 1. Créer un rôle vide (squelette conforme)
ansible-galaxy role init <role>

# 2. Créer une collection vide
ansible-galaxy collection init <namespace>.<collection>

# 3. Installer depuis Galaxy
ansible-galaxy role install geerlingguy.docker
ansible-galaxy collection install ansible.posix

# 4. Installer tout depuis requirements.yml (recommandé)
ansible-galaxy install -r requirements.yml -p collections/

# 5. Lister ce qui est installé
ansible-galaxy collection list
ansible-galaxy role list

# 6. Vérifier l'intégrité (signatures GPG)
ansible-galaxy collection verify ansible.posix

# 7. Build une collection (tarball)
ansible-galaxy collection build

# 8. Publier sur Galaxy (token API requis)
ansible-galaxy collection publish my-namespace-my-collection-1.0.0.tar.gz \
  --api-key=$GALAXY_API_KEY

Sécurité non négociable :

• -p collections/ mandatory, installer dans le projet, pas dans ~/.ansible/. Évite les contaminations entre projets et garantit la reproductibilité.
• ansible-galaxy collection verify dans la CI, détecte un mirror compromis ou un checksum modifié.
• --api-key via variable d'env CI/CD secrétée, JAMAIS en clair dans une commande shell (apparaît dans history).
• Avant de publier : ansible-test sanity sur la collection, molecule test sur le rôle. Pas de release de code non testé.

Ce que vous allez apprendre

• ansible-galaxy role init pour créer un rôle vide.
• ansible-galaxy role/collection install depuis Galaxy ou Git.
• ansible-galaxy list pour voir ce qui est installé.
• ansible-galaxy search et info pour explorer.
• ansible-galaxy collection build/publish pour publier.
• ansible-galaxy collection verify pour vérifier l'intégrité.

Initialisation

# Créer un rôle vide avec la structure standard
ansible-galaxy role init nginx

# Créer dans un dossier spécifique
ansible-galaxy role init --init-path roles/ nginx

# Créer une collection
ansible-galaxy collection init stephrobert.networking

role init génère 8 dossiers (defaults, files, handlers, meta, tasks, templates, tests, vars) + README.md.

collection init génère la structure d'une collection : roles/, plugins/, playbooks/, meta/, galaxy.yml.

Recherche

# Rechercher un rôle sur Galaxy
ansible-galaxy search nginx --author geerlingguy

# Filtrer par tag platform
ansible-galaxy search nginx --platforms EL

# Info détaillée d'un rôle
ansible-galaxy role info geerlingguy.nginx

role info affiche : versions, dépendances, plateformes, dernière mise à jour, lien GitHub.

Installation

Depuis Galaxy (rôle communautaire)

ansible-galaxy role install geerlingguy.nginx

Installe dans ~/.ansible/roles/ (par défaut), visible par tous les playbooks.

Depuis Git (avec branche/tag)

# Branche main
ansible-galaxy role install git+https://github.com/geerlingguy/ansible-role-nginx.git,master

# Tag spécifique
ansible-galaxy role install git+https://github.com/geerlingguy/ansible-role-nginx.git,3.1.0

# Avec un nom local différent
ansible-galaxy role install git+https://github.com/...,3.1.0,nginx-prod

Depuis requirements.yml

ansible-galaxy role install -r requirements.yml
ansible-galaxy collection install -r requirements.yml

Voir la page installer-roles-galaxy pour le format complet.

Vers un dossier projet (recommandé pour CI/CD)

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

-p ./roles/ = installation locale au projet, pas dans ~/.ansible/. Pattern recommandé pour reproductibilité CI/CD.

Listing

# Lister tous les rôles installés
ansible-galaxy role list

# Lister les collections installées
ansible-galaxy collection list

# Filtrer par namespace
ansible-galaxy collection list community.general

# Format JSON pour scripts
ansible-galaxy collection list --format json

Suppression

ansible-galaxy role remove geerlingguy.nginx

Pas d'équivalent pour les collections, il faut supprimer manuellement le dossier dans ~/.ansible/collections/ansible_collections/<namespace>/<collection>/.

Build & publish (collections)

# Build une collection (génère .tar.gz)
cd path/to/collection/
ansible-galaxy collection build

# Publier sur Galaxy avec un token API
ansible-galaxy collection publish stephrobert-networking-1.0.0.tar.gz \
  --api-key=$GALAXY_TOKEN

Token API disponible sur galaxy.ansible.com → Profil → API Token.

Vérification

# Vérifier l'intégrité d'une collection installée vs Galaxy
ansible-galaxy collection verify community.general

# Avec signature GPG (Galaxy 2024+)
ansible-galaxy collection verify community.general \
  --signature https://galaxy.ansible.com/api/...

Détecte : altération locale du code, fichiers modifiés post-install.

Variables d'environnement utiles

Variable	Effet
ANSIBLE_GALAXY_TOKEN	Token Galaxy par défaut (évite --api-key)
ANSIBLE_ROLES_PATH	Chemins de recherche des rôles
ANSIBLE_COLLECTIONS_PATH	Chemins de recherche des collections
ANSIBLE_GALAXY_SERVER	URL d'un Automation Hub privé

Glissez pour voir

Configuration ansible.cfg pour Galaxy

[galaxy]
server_list = corporate_hub, galaxy

[galaxy_server.corporate_hub]
url = https://hub.corp.example.com/api/automation-hub/
token = <token>

[galaxy_server.galaxy]
url = https://galaxy.ansible.com/

Pattern entreprise : un mirror privé (Automation Hub) en premier, Galaxy public en fallback.

Pratiquer dans le lab

Cette page a un lab d'accompagnement : labs/galaxy/ansible-galaxy-cli/ dans stephrobert/ansible-training.

Le lab fournit un cheatsheet exhaustif des commandes ansible-galaxy. 7 tests structure validés (init, install, list, publish, verify).

cd ~/Projets/ansible-training/labs/galaxy/ansible-galaxy-cli/

cat cheatsheet.md
pytest -v challenge/tests/             # 7 tests

Pièges courants

Symptôme	Cause	Fix
Role not found après install	roles_path mal configuré	`ansible-config dump
Collection community.X plante	Dépendance non installée	ansible-galaxy collection list pour voir
Token Galaxy invalide	Token expiré	Régénérer sur galaxy.ansible.com
role import (Galaxy auto-import) ne déclenche pas	Webhook GitHub non configuré	Vérifier sur Galaxy → Imports
Collection installée 2 fois	~/.ansible/ + projet local	Préférer -p ./collections/ (local)

Glissez pour voir

À retenir

• role init + collection init = scaffolding officiel.
• install -r requirements.yml -p ./<dir>/ = installation locale projet (CI/CD).
• list + info = inspection.
• build + publish = workflow de publication collection.
• verify = intégrité cryptographique.
• ansible.cfg [galaxy] = mirror privé Automation Hub.

Prochaines étapes

Installer des rôles Galaxy Format complet de requirements.yml + pinning des versions

Auditer un rôle existant Avant d'installer un rôle Galaxy, savoir l'évaluer

Versionner et publier Workflow Git tag → publish Galaxy automatique

Trouver le bon module Sécurité supply chain, éviter les rôles Galaxy malveillants

×

📖 Voir la documentation →