Installer des rôles depuis Galaxy : requirements.yml et pinning

requirements.yml déclare les rôles et collections dont votre projet dépend, avec leur provenance et leur version. Il joue le rôle d'un requirements.txt Python ou d'un package.json, à une différence près qui coûte cher : son contenu ne garantit pas ce qui se trouve sur le disque. Cette page explique le format, les sources acceptées, et surtout les cas où l'installation ne fait pas ce que le fichier demande.

Ce que vous allez apprendre

Écrire un requirements.yml qui déclare rôles et collections.
Choisir la source adaptée : Galaxy, dépôt Git, archive.
Épingler une version, et comprendre ce que chaque forme autorise.
Reconnaître les deux situations où l'installation ignore votre fichier.
Vérifier l'intégrité des collections par signature.

Prérequis

Connaître les sous-commandes d'installation, décrites dans la CLI ansible-galaxy.
Un projet Ansible avec au moins un playbook.

La structure du fichier

Le fichier accepte deux clés de premier niveau, indépendantes l'une de l'autre. Chacune décrit une famille d'objets, et rien n'oblige à utiliser les deux.

---
roles:
  # Depuis Galaxy : le nom suffit, sous la forme namespace.role
  - name: geerlingguy.docker
    version: 7.4.4

  # Depuis un dépôt Git, avec un nom local choisi
  - src: https://github.com/geerlingguy/ansible-role-nginx
    name: geerlingguy.nginx
    version: 3.1.0

collections:
  # Version exacte
  - name: ansible.posix
    version: "2.0.0"

  # Intervalle borné
  - name: community.general
    version: ">=8.0.0,<10.0.0"

Pour un rôle, la clé name est celle que vous emploierez dans vos playbooks. Quand la source est un dépôt Git, elle est donc essentielle : sans elle, le rôle prend le nom du dépôt et votre - role: nginx ne trouve rien.

Les sources acceptées

Quatre provenances couvrent tous les cas, du rôle communautaire au rôle interne d'entreprise.

Galaxy public est la source par défaut. Le nom au format namespace.role suffit, ansible-galaxy se charge de trouver le dépôt correspondant.

roles:
  - name: geerlingguy.docker
    version: 7.4.4

Un dépôt Git public s'indique par son URL. La version accepte alors tout ce que Git comprend : un tag, un nom de branche ou une empreinte de commit.

roles:
  - src: https://github.com/geerlingguy/ansible-role-nginx
    name: geerlingguy.nginx
    version: 3.1.0        # tag, branche ou SHA de commit

Un dépôt privé en SSH demande une précision supplémentaire. L'URL ne commençant pas par un protocole reconnaissable, le paramètre scm lève l'ambiguïté.

roles:
  - src: git@gitlab.corp.example.com:ansible/role-internal.git
    scm: git
    name: corp.internal_role
    version: v2.5.0

Une archive téléchargeable convient aux rôles distribués par un serveur de fichiers interne, sans Git ni Galaxy.

roles:
  - src: https://files.corp.example.com/releases/role-v1.0.tar.gz
    name: corp.example_role

Épingler une version

Le choix de la contrainte décide de ce qui se passera dans six mois, quand quelqu'un relancera l'installation sur une autre machine.

Forme	Ce qui sera installé	Usage
`version: 7.4.4`	exactement cette version	production, environnement reproductible
`version: ">=8.0.0,<10.0.0"`	la plus récente de l'intervalle	acceptable si l'auteur respecte le versionnage sémantique
`version: ">=1.2.0"`	la plus récente, sans limite haute	risqué, une version majeure passera sans prévenir
`version: main`	l'état actuel de la branche	développement uniquement
absence de `version`	la plus récente disponible	à éviter, le résultat change dans le temps

Un rôle installé par tag Git mérite une précaution supplémentaire : un tag se déplace, donc un même numéro peut livrer deux codes différents. C'est expliqué dans Versionner et publier, et cela justifie l'épinglage par empreinte de commit sur les chaînes sensibles.

Installer, et vérifier que c'est bien fait

La commande lit le fichier et installe ce qu'il déclare.

# Les rôles seulement
ansible-galaxy role install -r requirements.yml -p ./roles/

# Les collections seulement
ansible-galaxy collection install -r requirements.yml -p ./collections/

L'option -p place le contenu dans le projet plutôt que dans votre répertoire personnel, ce qui rend l'installation reproductible et visible en revue de code.

ansible-galaxy install -r requirements.yml traite les deux familles en un appel, mais seulement sans -p. Avec un chemin personnalisé, les collections sont écartées, et l'avertissement passe facilement inaperçu au milieu de la sortie :

[WARNING]: The requirements file contains collections which will be ignored.
To install these collections run 'ansible-galaxy collection install -r' or to
install both at the same time run 'ansible-galaxy install -r' without a custom
install path.

L'installation se termine sans erreur, avec un code de retour nul. En intégration continue, cela donne un build vert dont les collections manquent, et l'échec survient bien plus tard, à l'exécution du playbook. Utilisez deux commandes distinctes dès que vous employez -p.

Quand l'installation ignore votre fichier

Voici le comportement qui surprend le plus, et il diffère selon la famille.

Un rôle déjà présent n'est pas remplacé, même si vous avez changé sa version dans le fichier. Ansible le signale, puis poursuit sans rien faire :

[WARNING]: - geerlingguy.docker (7.4.4) is already installed - use --force to
change version to 7.4.3

Le fichier demande 7.4.3, le disque contient toujours 7.4.4, et la commande se termine normalement. Votre déclaration et votre réalité ont divergé sans qu'aucune erreur ne le signale.

# Le seul moyen d'aligner le disque sur le fichier
ansible-galaxy role install -r requirements.yml -p ./roles/ --force

Une collection, elle, est bien remplacée par la version demandée, sans option supplémentaire. Cette asymétrie entre les deux familles n'a pas de justification pratique : elle s'explique par leur histoire, les collections étant arrivées bien après.

Retenez-en une règle simple : en intégration continue, repartez d'un répertoire vide, ou passez systématiquement --force. C'est le seul moyen d'obtenir sur le disque ce que le fichier déclare.

Vérifier l'intégrité des collections

Les collections publiées sur Galaxy peuvent être signées, et ansible-galaxy vérifie ces signatures à l'installation quand elles existent. Plusieurs options encadrent ce comportement.

# Exiger au moins deux signatures valides
ansible-galaxy collection install -r requirements.yml --required-valid-signature-count 2

# Utiliser un trousseau précis
ansible-galaxy collection install -r requirements.yml --keyring ~/.ansible/galaxy.kbx

# Comparer une collection déjà installée à ce que le serveur publie
ansible-galaxy collection verify community.general

Une signature peut aussi être déclarée directement dans le fichier, à côté de la collection concernée.

collections:
  - name: ansible.posix
    version: "2.0.0"
    signatures:
      - https://galaxy.ansible.com/api/v3/.../signature.asc

L'option --disable-gpg-verify existe pour les environnements sans GPG, mais elle annule précisément la garantie que vous cherchiez. Un miroir interne compromis redevient alors indétectable.

Mettre en pratique

Le fichier déclare, le disque décide : c'est précisément cet écart que le lab fait constater. Vous écrivez un requirements.yml qui mêle rôles Galaxy, sources Git et collections, vous épinglez chaque version, puis vous installez dans un répertoire du projet plutôt que dans votre répertoire personnel. Les tests inspectent le disque au lieu de la sortie de la commande, exactement la précaution que cette page recommande.

Installer rôles et collections depuis Galaxy ou Git

$ dsoxlab run galaxy-installer-roles

Environnement : Shell·Durée : ~30 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-installer-roles
dsoxlab check galaxy-installer-roles

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

Pièges courants

Symptôme	Cause	Solution
Collections absentes après un `install -r` réussi	La commande unique les ignore quand `-p` est présent	Lancer `collection install -r` séparément
La version installée n'est pas celle du fichier	Un rôle déjà présent n'est jamais remplacé	Ajouter `--force`, ou partir d'un répertoire vide
`the role 'nginx' was not found`	Source Git sans clé `name`	Déclarer le nom local attendu par vos playbooks
Le contenu change alors que la version est figée	Le tag Git a été déplacé en amont	Épingler par empreinte de commit
Résultat différent d'une machine à l'autre	Aucune `version` déclarée	Épingler chaque entrée

À retenir

requirements.yml déclare, il ne garantit pas. Deux situations font diverger le fichier et le disque, sans erreur.
La commande unique install -r ignore les collections dès qu'un -p est présent, avec un simple avertissement et un code de retour nul.
Un rôle déjà installé n'est jamais remplacé sans --force, alors qu'une collection l'est. Cette asymétrie est purement historique.
La clé name est obligatoire sur une source Git, sinon le rôle porte le nom du dépôt.
Épinglez une version exacte en production, et par empreinte de commit quand un tag déplaçable ne suffit pas.

Pour aller plus loin

Auditer un rôle existant : une version épinglée ne dit rien de la qualité du contenu épinglé.
Versionner et publier : comprendre ce qu'un mainteneur garantit, et ne garantit pas, derrière un numéro de version.
Execution Environments : vue d'ensemble : figer collections et dépendances dans une image, plutôt que les réinstaller à chaque exécution.