requirements.yml Ansible : Galaxy, Git, URL, signatures GPG, pinning strict

Un projet Ansible mature versionne ses dépendances dans requirements.yml. Le fichier liste les collections et rôles utilisés, leur source (Galaxy, Git, URL tarball, chemin local), leur version pinnée (semver strict), et optionnellement leurs signatures GPG détachées pour la chaîne supply-chain. Sans ce fichier, un projet dérive au fil des releases upstream et casse en prod sans avertissement.

Cette page couvre les 4 sources acceptées par ansible-galaxy, la syntaxe complète, la vérification d’intégrité avec ansible-galaxy collection verify, et la configuration ansible.cfg [galaxy] pour cibler plusieurs serveurs (Galaxy + Automation Hub privé).

# requirements.yml — versionné dans Git
---
collections:
  # Source 1 : Galaxy public, version exacte (préféré en prod)
  - name: ansible.posix
    version: "2.0.0"

  # Source 2 : range de versions (major locké)
  - name: community.general
    version: ">=8.0.0,<10.0.0"

  # Source 3 : Git avec tag (ou SHA pour reproductibilité absolue)
  - name: stephrobert.webapp
    source: https://github.com/stephrobert/ansible-collection-webapp.git
    type: git
    version: v1.2.3              # tag Git, JAMAIS "main"

  # Source 4 : tarball direct (cas extrêmes)
  - name: my.collection
    source: https://internal.example.com/my-collection-1.0.0.tar.gz
    type: url
    version: 1.0.0

# Installation isolée au projet (pas dans ~/.ansible/)
ansible-galaxy collection install -r requirements.yml -p collections/

# Vérification d'intégrité après install (checksums + signatures GPG)
ansible-galaxy collection verify -r requirements.yml -p collections/

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

Pinning strict sur chaque collection — version exacte (2.0.0) ou range bornée (>=8.0.0,<10.0.0). JAMAIS de wildcard ou pas de version.
Tag Git, jamais branche pour les sources Git — version: v1.2.3 ou un SHA. main = drift garanti.
-p collections/ mandatory — installer dans le projet, pas dans ~/.ansible/ global.
ansible-galaxy collection verify dans la CI — bloque le pipeline si un checksum a changé depuis l’install (mirror compromis détecté).
Mirror privé en entreprise — éviter la dépendance directe à Galaxy public ; valider chaque collection avant publication interne sur Automation Hub privé.
signatures: dans requirements.yml pour les collections critiques — vérifie une signature GPG détachée à l’install. Bonus défense en profondeur supply chain.

Ce que vous allez apprendre

4 sources dans requirements.yml : Galaxy, Git, URL tarball, chemin local.
Pinning strict par tag, branche ou SHA Git.
ansible-galaxy collection install -r ... -p <chemin> pour isolation projet.
ansible-galaxy collection verify pour intégrité (checksums + signatures GPG).
Multi-serveur Galaxy + Automation Hub via ansible.cfg [galaxy].
Pattern airgap : signatures GPG + --keyring + --offline.

Prérequis

Avoir lu Découvrir une collection.
Ansible 2.13+ (signatures GPG depuis 2.13).

Le fichier `requirements.yml` — toutes les sources

---
collections:
  # SOURCE 1 — Galaxy public (default)
  - name: ansible.posix
    version: "2.0.0"

  - name: community.general
    version: "10.5.0"
    source: https://galaxy.ansible.com    # explicite (default)

  # SOURCE 2 — Git (tag, branche ou SHA40)
  - name: https://github.com/ansible-collections/community.docker.git
    type: git
    version: "4.0.0"                      # tag (recommandé)
    # OU version: main                    (branche, déconseillé en prod)
    # OU version: abc1234567890abcdef...  (SHA40, reproductibilité absolue)

  # SOURCE 3 — URL tarball
  - name: https://example.com/dist/acme-webapp-1.4.2.tar.gz
    type: url

  # SOURCE 4 — chemin local (dev)
  - name: /home/bob/dev/acme.webapp
    type: dir

  # OVERRIDE de namespace lors de l'install
  - name: namespace.collection
    type: galaxy
    source: https://my-hub.acme.local/api/galaxy/

roles:
  # Rôles standalone Galaxy v1 (legacy mais encore supportés)
  - name: geerlingguy.docker
    version: "7.4.0"

🔍 Observation : un seul fichier centralise toutes les dépendances. Le placer dans requirements.yml à la racine du projet, le versionner dans Git, l’utiliser dans la CI et l’EE.

Sources Git — tag vs branche vs SHA

Format `version:`	Exemple	Cas d’usage
Tag Git	`version: v1.2.3`	Production stable (recommandé)
Branche	`version: main`	Dev rapide, déconseillé en prod
SHA40	`version: abc1234567890abcdef...`	Reproductibilité absolue

🔍 Observation cruciale : pinner par branche = drift garanti dès qu’un commit upstream casse votre pipeline. Toujours tag ou SHA en prod.

Installation depuis `requirements.yml`

ansible-galaxy collection install \
  -r requirements.yml \
  -p ./local_collections \
  --force

Options clés :

Option	Effet
`-r requirements.yml`	Lit le fichier de dépendances
`-p <chemin>`	Installe localement au projet (pas dans `~/.ansible/`)
`--force`	Réinstalle même si version déjà présente
`--upgrade`	Upgrade vers la dernière version compatible avec les contraintes
`--keyring <path>`	Chemin du keyring GPG pour signatures
`--offline`	N’appelle pas le serveur (utile airgap)

🔍 Observation : -p <chemin> isole les collections par projet. Versionner le local_collections/ dans .gitignore, mais versionner le requirements.yml. Permet d’avoir 3 projets avec 3 versions différentes de community.general sans conflit.

`ANSIBLE_COLLECTIONS_PATH`

Une fois installées en local :

export ANSIBLE_COLLECTIONS_PATH=./local_collections
ansible-galaxy collection list -p ./local_collections

Ou dans ansible.cfg :

[defaults]
collections_path = ./local_collections

🔍 Observation : la variable d’env utilise : comme séparateur (comme $PATH). Permet d’enchaîner plusieurs paths avec priorité au premier.

Vérification d’intégrité

ansible-galaxy collection verify \
  -r requirements.yml \
  -p ./local_collections

Sortie :

Verifying 'ansible.posix:2.0.0'.
Found ansible.posix at /home/.../local_collections/ansible_collections/ansible/posix
Successfully verified that checksums for 'ansible.posix:2.0.0' match the remote collection

🔍 Observation : verify compare les checksums SHA-256 des fichiers locaux avec ceux du serveur. Détecte une corruption (disque, modification manuelle) ou une substitution (attaque supply-chain). À automatiser en CI : ansible-galaxy collection verify -r requirements.yml || exit 1.

Signatures GPG détachées

Pour les collections certifiées Red Hat ou les forks privés signés :

collections:
  - name: community.general
    version: "10.5.0"
    signatures:
      - https://galaxy.ansible.com/api/v3/.../detached_signature.asc
      - file:///etc/ansible/sigs/community-general-10.5.0.asc

ansible-galaxy collection install \
  -r requirements.yml \
  --keyring /etc/ansible/trustedkeys.gpg

Variables associées :

Variable	Effet
`GALAXY_REQUIRED_VALID_SIGNATURE_COUNT`	Nombre minimum de signatures valides (`+1`, `+all`)
`GALAXY_DISABLE_GPG_VERIFY`	`1` désactive (debug uniquement)
`--keyring <path>`	Chemin vers le keyring GPG de confiance

🔍 Observation : exige ansible-core ≥ 2.13. Sans --keyring, l’install échoue si signatures déclarées. Pattern essentiel pour airgap signé (verify offline avec --offline).

Multi-serveur — Galaxy + Automation Hub

Pour cibler plusieurs registres (Galaxy public + Hub privé), configurer ansible.cfg :

[galaxy]
server_list = automation_hub, validated, galaxy

[galaxy_server.automation_hub]
url=https://console.redhat.com/api/automation-hub/content/published/
auth_url=https://sso.redhat.com/auth/realms/redhat-external/protocol/openid-connect/token
token=<offline-token>

[galaxy_server.validated]
url=https://console.redhat.com/api/automation-hub/content/validated/
auth_url=https://sso.redhat.com/auth/realms/redhat-external/protocol/openid-connect/token
token=<offline-token>

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

🔍 Observation : ordre = priorité. Si une collection existe sur les 3, c’est celle d’automation_hub qui l’emporte (Red Hat certified). Pattern entreprise standard.

Pour `ansible-builder` (EE)

Variables d’env équivalentes pour les Execution Environments :

ANSIBLE_GALAXY_SERVER_LIST=automation_hub,galaxy
ANSIBLE_GALAXY_SERVER_AUTOMATION_HUB_URL=https://...
ANSIBLE_GALAXY_SERVER_AUTOMATION_HUB_TOKEN=<offline-token>
ANSIBLE_GALAXY_SERVER_AUTOMATION_HUB_AUTH_URL=https://...

Permet à ansible-builder build de résoudre les dépendances depuis le hub privé pendant le build de l’EE custom.

Lab pratique

Le lab collections/requirements (labs/collections/requirements/) reproduit ce parcours avec un challenge qui combine 3 sources (Galaxy + Git + URL/dir) et 4 tests pytest structurels.

À retenir

requirements.yml centralise toutes les dépendances Ansible.
4 sources : Galaxy (default), type: git, type: url, type: dir.
Pinning strict par tag ou SHA — jamais par branche en prod.
-p <chemin> isole les collections au niveau projet.
ansible-galaxy collection verify détecte corruptions et substitutions.
Signatures GPG via signatures: + --keyring pour la chaîne supply-chain.
Multi-serveur via ansible.cfg [galaxy] ou variables ANSIBLE_GALAXY_SERVER_*.

Prochaines étapes

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

Pipeline CI matrice GitHub Actions + GitLab CI durcis 2026.

Lab 94 sur GitHub requirements.yml multi-sources avec 4 tests pytest.