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.

Pressé ? Inspecter une collection en 30 secondes

# Lister toutes les collections installées (avec versions)
ansible-galaxy collection list

# Détails d'une collection précise
ansible-galaxy collection info ansible.posix

# Lister les modules d'une collection
ansible-doc -l ansible.posix

# Doc d'un module avec FQCN exact (snippet YAML prêt à copier)
ansible-doc -s ansible.posix.firewalld

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

Sécurité non négociable :

• FQCN partout dans vos playbooks (ansible.builtin.copy, jamais copy:) — c’est l’usage attendu en 2026, et ansible-lint --profile=production plante sans.
• ansible-galaxy collection verify dans la CI — détecte un mirror compromis ou un checksum modifié depuis l’install.
• Auditer une collection avant adoption — qui maintient ? activité récente ? tests CI ? documentation des modules ?
• ansible-doc est votre seule source autorisée à l’examen RHCE — apprendre -s (snippet) et -l (liste) à mémoriser.

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.

Lab pratique

Le lab collections/decouvrir (labs/collections/decouvrir/) reproduit ce parcours avec 5 tests pytest et un challenge final qui dépose un inventaire des collections sur db1.lab via ansible-galaxy collection list.

À 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.

Prochaines étapes

requirements.yml multi-sources Galaxy + Git + signatures GPG, pinning semver, ansible-galaxy collection install -r.

Créer sa collection custom ansible-galaxy collection init, module Python, build, ansible-test sanity.

Lab 93 sur GitHub Inventorier les collections installées, structure et FQCN, 5 tests pytest.

×

📖 Voir la documentation →