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

requirements.yml est le fichier de référence pour déclarer les rôles et collections externes utilisés par votre projet. Comme requirements.txt en Python ou package.json en Node, il pin les versions pour reproductibilité, supporte des sources mixtes (Galaxy public, Git, mirror privé), et permet la vérification cryptographique des collections.

Pressé ? Le requirements.yml de référence

# requirements.yml — versionné dans Git
---
collections:
  - name: ansible.posix
    version: ">=1.5.0,<2.0.0"        # range — major locké
  - name: community.general
    version: "8.6.1"                  # exact — preferé en prod
  - name: community.hashi_vault
    version: "6.2.0"

  # Git source avec tag (signé)
  - name: stephrobert.webapp
    source: https://github.com/stephrobert/ansible-collection-webapp.git
    type: git
    version: v1.2.3                   # tag, JAMAIS "main"

roles:
  - src: geerlingguy.docker
    version: "7.4.0"                  # tag exact
  - src: https://gitlab.example.com/team/role-database.git
    scm: git
    version: v2.0.0
    name: company.database            # alias local

# Installation avec dossier dédié au projet (pas global ~/.ansible/)
ansible-galaxy install -r requirements.yml \
  -p collections/ \
  --force                              # force la réinstall si version a changé

# Vérification d'intégrité (signature GPG)
ansible-galaxy collection verify ansible.posix

Sécurité non négociable — supply chain :

• Pinner CHAQUE version — version: "1.2.3" ou version: ">=1.0.0,<2.0.0". JAMAIS latest ou pas de version (équivaut à latest).
• Tag Git, jamais branche — version: v1.2.3 ou un SHA. version: main = la branche évolue sous vos pieds = drift garanti.
• ansible-galaxy collection verify dans la CI — vérifie les checksums et signatures GPG. Un attaquant qui prend le contrôle d’une collection compromise est détecté.
• Mirror privé en entreprise (Galaxy NG self-hosted, Automation Hub) — évite la dépendance directe à Galaxy public ; permet de valider chaque collection avant publication interne.
• Installer dans collections/ au projet plutôt que ~/.ansible/ — isolation, reproductibilité, pas de pollution croisée entre projets.
• Auditer les rôles tiers AVANT install (cf. Auditer un rôle existant) — un rôle malveillant qui tourne en root sur 50 serveurs, c’est game over.

Ce que vous allez apprendre

• Format complet de requirements.yml (rôles + collections).
• Pinning de version : exact, range, contraintes complexes.
• Sources : Galaxy, Git (avec branche/tag), URL, fichier local.
• Signatures cryptographiques pour intégrité.
• Workflow CI/CD : install local au projet (pas dans ~/.ansible/).

Le fichier requirements.yml complet

---
# requirements.yml — sources mixtes : Galaxy + Git + version pinning

roles:
  # 1. Rôle Galaxy public (version pinnée exacte)
  - name: geerlingguy.docker
    version: 7.4.4

  # 2. Rôle depuis Git (branche main)
  - src: https://github.com/stephrobert/ansible-role-motd
    name: stephrobert.motd
    version: main

  # 3. Rôle depuis Git avec tag
  - src: https://github.com/geerlingguy/ansible-role-postgresql
    name: geerlingguy.postgresql
    version: 4.1.0

collections:
  # 4. Collection avec range de version (acceptable)
  - name: ansible.posix
    version: ">=1.5.0,<2.0.0"

  # 5. Collection avec version mini ouverte
  - name: community.general
    version: ">=8.0.0"

  # 6. Collection pinnée par version exacte (production stricte)
  - name: community.crypto
    version: "2.20.0"

  # 7. Collection avec signature (Galaxy 2024+)
  - name: ansible.utils
    version: ">=4.0.0"
    signatures:
      # En 2026, signatures GPG sur les collections Galaxy
      # - https://galaxy.ansible.com/api/...

Installation depuis requirements.yml

# Installation par défaut (~/.ansible/...)
ansible-galaxy role install -r requirements.yml
ansible-galaxy collection install -r requirements.yml

# Installation locale au projet (recommandé CI/CD)
ansible-galaxy role install -r requirements.yml -p ./roles/
ansible-galaxy collection install -r requirements.yml -p ./collections/

Une seule commande pour tout :

# Si requirements.yml a 'roles:' ET 'collections:'
ansible-galaxy install -r requirements.yml

Sources possibles

Source 1 — Galaxy public (par défaut)

roles:
  - name: geerlingguy.docker      # ← namespace.role_name
    version: 7.4.4

ansible-galaxy télécharge depuis galaxy.ansible.com.

Source 2 — Git (branche, tag, commit)

roles:
  - src: https://github.com/geerlingguy/ansible-role-nginx
    name: geerlingguy.nginx       # ← nom local utilisé dans le code
    version: 3.1.0                # ← tag Git, branche, ou SHA40

Versions acceptées :

• Tag : version: 3.1.0
• Branche : version: main
• SHA40 commit : version: a1b2c3d...

Source 3 — Git non-Galaxy (rôle privé)

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

scm: git force le SCM (par défaut auto-détecté depuis l’URL).

Source 4 — URL d’archive

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

Téléchargement direct d’une archive — utile pour les rôles internes hostés sur un serveur de fichiers.

Pinning de version — patterns

Forme	Effet	Quand l’utiliser
version: 1.2.3	Version exacte	Production — reproductibilité totale
version: ">=1.2.0,<2.0.0"	Range mineur	Acceptable — laisse passer patches
version: "*"	Toute version (= dernière)	⚠️ AVOID — surprises garanties
version: ">=1.2.0"	Plus récent que 1.2.0	⚠️ Risqué pour breaking changes
version: main	Dernière de la branche main	Dev seulement, jamais en prod

Glissez pour voir

Règle d’or : pinning exact en production, range mineur en dev/staging.

Signatures cryptographiques (Galaxy 2024+)

Depuis 2024, les collections Galaxy peuvent être signées GPG. Vérification auto :

collections:
  - name: ansible.posix
    version: 1.6.2
    signatures:
      - https://galaxy.ansible.com/api/v3/.../signatures/abc123

ansible-galaxy collection install -r requirements.yml vérifie la signature avant install. Si la signature ne matche pas → install échoue.

Mandatory dans les contextes sécurité (banque, défense, santé).

Pattern projet — installation locale

projet/
├── ansible.cfg
├── requirements.yml
├── roles/                       ← installé via -p ./roles/
│   ├── geerlingguy.docker/
│   └── stephrobert.motd/
├── collections/                 ← installé via -p ./collections/
│   └── ansible_collections/
│       ├── ansible/
│       └── community/
└── playbooks/

# ansible.cfg
[defaults]
roles_path = ./roles
collections_path = ./collections

Avantage : un git clone du projet + ansible-galaxy install -r requirements.yml -p ./roles/ reproduit exactement l’environnement. Aucune dépendance globale ~/.ansible/.

Workflow CI/CD typique

# .gitlab-ci.yml ou .github/workflows/test.yml
- pip install ansible-core>=2.16
- ansible-galaxy collection install -r requirements.yml -p ./collections/
- ansible-galaxy role install -r requirements.yml -p ./roles/
- ansible-playbook playbooks/site.yml

Pratiquer dans le lab

Cette page a un lab d’accompagnement : labs/galaxy/installer-roles/ dans stephrobert/ansible-training.

Le lab fournit un requirements.yml mixte (Galaxy public + Git + collections). 6 tests structure validés (rôles pinnés, sources Git, collection pinnée stricte).

cd ~/Projets/ansible-training/labs/galaxy/installer-roles/

cat requirements.yml
pytest -v challenge/tests/             # 6 tests

Pièges courants

Symptôme	Cause	Fix
Role not found in [requirements.yml]	Faute de frappe sur le namespace.name	Vérifier sur galaxy.ansible.com
Build cassé après mise à jour	Pas de pinning	Pinner avec version: X.Y.Z exacte
git clone rate sur source privée	Auth SSH manquante côté runner CI	Configurer ~/.ssh/known_hosts + clé déployée
Collection installée 2 fois	~/.ansible/ ET ./collections/	Choisir une seule source via collections_path
Signatures rejetées	Galaxy 2024+ et signature absente	Ajouter signatures: ou désactiver vérif (debug)

Glissez pour voir

À retenir

• requirements.yml = source unique pour les dépendances rôles + collections.
• Pinning exact (version: 1.2.3) en production.
• -p ./roles/ + -p ./collections/ = installation locale projet (reproductibilité).
• Sources : Galaxy, Git (tag/branche/SHA), URL d’archive.
• Signatures GPG mandatory en contexte sécurité.

Prochaines étapes

Auditer un rôle existant Avant d'ajouter un rôle dans requirements.yml, l'auditer

Versionner et publier Si vous publiez vos rôles, savoir comment les autres vont les pinner

ansible-galaxy CLI Toutes les commandes ansible-galaxy en référence

Trouver le bon module Rappel sécurité supply chain pour les collections Galaxy

×

📖 Voir la documentation →