Découvrir une collection Ansible : ansible-galaxy collection list, info, structure standard, FQCN

Avant de produire ses propres collections, il faut savoir lire celles qui existent. Cette page ouvre le capot : ansible-galaxy collection list/info pour l'inventaire, lecture d'un galaxy.yml, structure interne plugins/{modules,filter,...}/, signification de meta/runtime.yml, et compréhension du FQCN (Fully Qualified Collection Name) obligatoire en 2026 (ansible.builtin.copy, jamais copy:).

À la fin, vous saurez inspecter n'importe quelle collection avant de l'utiliser, distinguer un rôle standalone d'un rôle dans une collection, et trouver un module avec son FQCN exact via ansible-doc.

Ce que vous allez apprendre

• ansible-galaxy collection list/info pour l'inventaire des collections installées.
• Lecture d'un galaxy.yml : namespace, name, version, dependencies, tags.
• Structure interne : plugins/, roles/, playbooks/, meta/runtime.yml.
• FQCN obligatoire en 2026 : namespace.collection.plugin.
• Différence rôle standalone vs rôle dans collection.
• ansible-doc <FQCN> pour la doc embarquée (plus fiable que internet).

Prérequis

• Ansible 2.18+ installé.
• ansible-galaxy collection install community.general --force au moins une fois pour avoir une collection à inspecter.

Le FQCN, pierre angulaire 2026

Chaque ressource Ansible se nomme désormais avec un Fully Qualified Collection Name :

namespace.collection.plugin

Trois exemples concrets :

FQCN	Signification
ansible.builtin.copy	Module copy de la collection builtin du namespace ansible (livré avec ansible-core)
community.general.archive	Module archive de la collection general du namespace community
kubernetes.core.k8s	Module k8s de la collection core du namespace kubernetes

Glissez pour voir

Avantages :

• Pas de conflit : ansible.posix.firewalld et community.general.firewalld peuvent coexister.
• Provenance claire : on voit immédiatement d'où vient un module.
• Lint compatible : la règle fqcn-builtins d'ansible-lint --profile production impose le FQCN partout.

FQCN obligatoire à l'EX294 2026

L'examen RHCE EX294 ainsi que ansible-lint --profile production exigent le FQCN partout : ansible.builtin.copy, jamais copy:. Un playbook qui utilise des noms courts est techniquement valide mais rejeté en production et pénalisé à l'examen.

Inspecter les collections installées

ansible-galaxy collection list

Sortie typique :

/usr/share/ansible/collections/ansible_collections

Collection                    Version
----------------------------- -------
ansible.posix                 2.0.0
community.general             10.5.0
kubernetes.core               5.1.1

# /home/bob/.ansible/collections/ansible_collections
Collection                    Version
----------------------------- -------
community.docker              4.0.0

🔍 Observation : list agrège toutes les sources : système (/usr/share/ansible/), user (~/.ansible/), virtualenv. Plusieurs versions d'une même collection peuvent coexister, celle utilisée dépend de l'ordre dans ANSIBLE_COLLECTIONS_PATH.

Inspecter une collection précise

ansible-galaxy collection info community.general

Sortie :

Collection: community.general
Version: 10.5.0
Path: /usr/share/ansible/collections/ansible_collections/community/general
Documentation: https://docs.ansible.com/.../community/general/
Repository: https://github.com/ansible-collections/community.general
Issues: https://github.com/ansible-collections/community.general/issues
License: GPL-3.0-or-later
Authors:
  - Ansible Community

🔍 Observation : équivalent de dnf info ou apt show. Référence pour vérifier qu'une collection vient bien de Galaxy public et pas d'une source compromise.

Structure standard d'une collection

tree -L 2 /usr/share/ansible/collections/ansible_collections/community/general/

Structure attendue :

• Répertoirecommunity.general/

  • galaxy.yml
  • README.md
  • Répertoiremeta/

    • runtime.yml
  • Répertoireplugins/

    • Répertoiremodules/

      • …
    • Répertoirefilter/

      • …
    • Répertoirelookup/

      • …
    • Répertoireinventory/

      • …
    • Répertoirecallback/

      • …
    • Répertoireaction/

      • …
  • Répertoireroles/

    • …
  • Répertoireplaybooks/

    • …
  • Répertoirechangelogs/

    • …
  • Répertoiredocs/

    • …

Règles 2026 :

• plugins/modules/ est le seul emplacement valide pour les modules custom (le library/ legacy n'est plus reconnu).
• plugins/<type>/ par type de plugin : filter, lookup, inventory, callback, action, connection, module_utils.
• roles/<name>/ suit la même structure qu'un rôle standalone (tasks/, handlers/, defaults/...).
• playbooks/ : playbooks fournis par la collection, accessibles via ansible-playbook collection_namespace.playbook.

Le galaxy.yml

namespace: community
name: general
version: 10.5.0
readme: README.md
authors:
  - "Ansible Community"
description: "Collection of community modules"
license:
  - GPL-3.0-or-later
tags:                                 # ← OBLIGATOIRE pour publier
  - linux
  - windows
  - cloud
dependencies:
  ansible.posix: ">=1.5.4"
repository: https://github.com/ansible-collections/community.general
documentation: https://docs.ansible.com/.../community/general/
issues: https://github.com/ansible-collections/community.general/issues
build_ignore:
  - .github
  - .venv
  - tests/output

Champs critiques :

Champ	Rôle
namespace	Préfixe du FQCN (community, kubernetes, acme)
name	Nom court (general, core, webapp)
version	Semver strict (10.5.0)
tags:	Obligatoire pour publier sur Galaxy
dependencies:	Autres collections requises avec contraintes semver
build_ignore:	Exclusions du tarball (.git/, .venv/, secrets)

Glissez pour voir

Le meta/runtime.yml

cat /usr/share/ansible/collections/ansible_collections/community/general/meta/runtime.yml | head -10

Exemple typique :

---
requires_ansible: ">=2.15.0"

plugin_routing:
  modules:
    sudoers:
      redirect: community.general.sudoers

Deux sections clés :

• requires_ansible: : seuil minimum d'ansible-core. Sans, ansible-test sanity échoue.
• plugin_routing.modules.<old>.redirect : sert à la migration, redirige un ancien nom court vers le nouveau FQCN. Pattern essentiel pour la rétrocompatibilité (voir Migration rôle → collection).

Trouver un module via FQCN

# Lister tous les modules d'une collection
ansible-doc -l community.general | head -10

# Trouver un module par mot-clé
ansible-doc -l | grep -i archive

# Lire la doc d'un module
ansible-doc community.general.archive

🔍 Observation cruciale : ansible-doc <FQCN> affiche la doc de la version installée, plus fiable que la doc internet (qui peut être plus récente). Si votre EE a community.general 9.0.0, la doc affichée correspond à 9.0.0, pas à 10.5.0.

Différence rôle standalone vs rôle dans collection

Type	Distribution	Installation	Usage
Rôle standalone	ansible-galaxy role install geerlingguy.docker	~/.ansible/roles/geerlingguy.docker/	roles: [geerlingguy.docker]
Rôle dans collection	ansible-galaxy collection install community.general	~/.ansible/collections/.../community/general/roles/	roles: [community.general.bind]

Glissez pour voir

🔍 Observation : le format standalone est legacy depuis ansible-core 2.10. Galaxy NG (2026) ne supporte plus les rôles standalone, toute nouvelle distribution publie en collection. Si vous avez un rôle standalone à maintenir, voir Migration rôle → collection.

Mettre en pratique

Savoir qu'un FQCN se lit namespace.collection.plugin ne remplace pas l'avoir cherché soi-même sur une collection installée. Ce lab vous fait lister l'existant, ouvrir un galaxy.yml, parcourir l'arborescence plugins/, roles/ et playbooks/, puis retrouver un module précis par son nom complet. Le résultat attendu est un inventaire des collections déposé sur db1.lab, que la correction relit sur la machine plutôt que dans votre terminal.

Lab pratique

Explorer les collections Ansible : FQCN et structure

$ dsoxlab run collections-decouvrir

Environnement : VM·Durée : ~50 min

Validé : l'état du système est vérifié après reboot, pas la commande tapée.

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 collections-decouvrir
dsoxlab check collections-decouvrir

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

À retenir

• FQCN = namespace.collection.plugin, obligatoire en 2026.
• ansible-galaxy collection list/info pour explorer l'installé.
• galaxy.yml : métadonnées + dependencies + tags obligatoires.
• meta/runtime.yml : seuil ansible-core + redirects de modules.
• Structure fixe : plugins/{modules,filter,...}/, roles/, playbooks/.
• ansible-doc <FQCN> : doc de la version installée, plus fiable que internet.
• Rôles standalone = legacy. Tout passe par les collections en 2026.

Pour aller plus loin

• Créer une collection custom : la même structure, vue de l'intérieur, en la construisant soi-même.
• Pipeline CI en matrice : tester une collection sur plusieurs versions d'ansible-core et de Python.
• Migration d'un rôle vers une collection : le chemin à suivre quand vos rôles standalone doivent rejoindre le format actuel.

×

📖 Voir la documentation →