Module Ansible yum_repository : déclarer un dépôt RPM RHEL/AlmaLinux

Le module ansible.builtin.yum_repository déclare un dépôt RPM (yum/dnf) en générant le fichier .repo correspondant dans /etc/yum.repos.d/. C'est l'outil pour activer EPEL, ajouter le dépôt Docker CE, déclarer un dépôt interne d'entreprise, ou désactiver un dépôt par défaut. Public visé : intermédiaires Ansible sur RHEL/AlmaLinux/Rocky/Fedora. Cette page couvre la déclaration complète (URL, GPG, priority, exclude), l'import de la clé GPG via ansible.builtin.rpm_key, les patterns sécurité (gpgcheck=1 mandatory) et les différences avec dnf (qui installe des paquets, pas des dépôts).

Ce que vous allez apprendre

Déclarer un dépôt RPM avec son URL et son baseurl.
Importer la clé GPG du dépôt avant son activation (sécurité).
Gérer un dépôt désactivé (présent mais enabled: 0) pour usage ponctuel.
Comprendre la différence entre yum_repository (déclare un dépôt) et dnf (installe des paquets).
Suivre les bonnes pratiques sécurité : gpgcheck mandatory, signature de la metadata.

Prérequis

Ansible installé et nœud cible Linux RPM-based (RHEL 8/9/10, AlmaLinux, Rocky, CentOS Stream, Fedora).
Connaissances de base sur les fichiers .repo (cf. man yum.conf ou man dnf.conf).
Privilèges root sur le nœud (become: true).

Exemple type, activer EPEL sur RHEL 9

- name: Importer la clé GPG EPEL 9
  ansible.builtin.rpm_key:
    state: present
    key: https://dl.fedoraproject.org/pub/epel/RPM-GPG-KEY-EPEL-9

- name: Déclarer le dépôt EPEL 9
  ansible.builtin.yum_repository:
    name: epel
    description: "Extra Packages for Enterprise Linux 9"
    baseurl: "https://dl.fedoraproject.org/pub/epel/9/Everything/$basearch/"
    gpgcheck: true
    gpgkey: https://dl.fedoraproject.org/pub/epel/RPM-GPG-KEY-EPEL-9
    enabled: true
    state: present

Comportement :

Crée /etc/yum.repos.d/epel.repo (nom dérivé du name).
Si le fichier existe déjà avec les mêmes valeurs → task ok (idempotent).
Si une valeur diffère → fichier réécrit et task changed.

Deux étapes obligatoires :

Importer la clé GPG en premier avec rpm_key. Sans la clé, le 1er dnf install depuis ce dépôt échouera avec GPG check failed.
Déclarer le dépôt ensuite avec gpgcheck: true et gpgkey: pointant vers la même clé.

Les paramètres essentiels

- ansible.builtin.yum_repository:
    name: docker-ce                      # nom interne (= nom du fichier .repo)
    description: "Docker CE Stable - $basearch"
    baseurl: "https://download.docker.com/linux/centos/$releasever/$basearch/stable"
    gpgcheck: true                        # mandatory en prod
    gpgkey: https://download.docker.com/linux/centos/gpg
    enabled: true                         # 1=actif, 0=déclaré mais inactif
    state: present                        # present|absent
    file: docker-ce                       # nom du fichier sans .repo (défaut = name)
    priority: 50                          # plugin yum-plugin-priorities
    exclude: "docker-ce-1.13*"            # exclure des paquets de ce dépôt
    includepkgs: "docker-ce*"             # inclure UNIQUEMENT ces paquets
    sslverify: true                       # vérifier le cert HTTPS du repo
    metadata_expire: 86400                # cache metadata en secondes

Les variables $releasever, $basearch, $arch sont des macros yum/dnf résolues à l'exécution :

$releasever : version majeure de l'OS (9 sur RHEL 9, 10 sur RHEL 10).
$basearch : architecture du système (x86_64, aarch64).
$arch : architecture précise (rare en pratique).

Ne pas remplacer ces macros par des valeurs en dur, sinon le rôle ne marche que sur une seule architecture/version.

Désactiver un dépôt sans le supprimer

Cas typique : votre rôle doit désactiver un dépôt par défaut (sans le supprimer) pour forcer les installations vers un mirror interne.

- name: Désactiver le dépôt RHEL appstream sans le supprimer
  ansible.builtin.yum_repository:
    name: rhel-9-for-x86_64-appstream-rpms
    file: redhat                          # le fichier .repo où le dépôt est défini
    description: "RHEL 9 AppStream (désactivé par stratégie interne)"
    enabled: false
    state: present

state: present + enabled: false = le dépôt reste déclaré dans le fichier .repo mais n'est pas utilisé par dnf. C'est différent de state: absent qui supprime la section du fichier.

Différence avec `dnf` et `rpm_key`

C'est une confusion fréquente. Mémoriser :

Module	Rôle
`ansible.builtin.yum_repository`	Déclare/configure un dépôt (fichier `.repo`)
`ansible.builtin.rpm_key`	Importe une clé GPG dans le keyring rpm
`ansible.builtin.dnf`	Installe/désinstalle des paquets depuis les dépôts actifs
`ansible.builtin.package`	Wrapper portable (`dnf`, `apt`, `pacman`…)

Une chaîne typique pour ajouter un dépôt + installer un paquet :

- name: 1. Importer la clé GPG
  ansible.builtin.rpm_key:
    state: present
    key: https://download.docker.com/linux/centos/gpg

- name: 2. Déclarer le dépôt
  ansible.builtin.yum_repository:
    name: docker-ce
    description: "Docker CE Stable"
    baseurl: "https://download.docker.com/linux/centos/$releasever/$basearch/stable"
    gpgcheck: true
    gpgkey: https://download.docker.com/linux/centos/gpg

- name: 3. Installer le paquet
  ansible.builtin.dnf:
    name: docker-ce
    state: present

L'ordre est important, la clé doit exister AVANT l'installation, sinon dnf refuse.

Sécurité, `gpgcheck: true` non négociable

Pilier Security du WAF. Tout dépôt déclaré sans gpgcheck est une porte ouverte à un attaquant qui contrôlerait le mirror. Il pourrait servir un paquet bash modifié et obtenir l'exécution de code root au prochain dnf update.

# ❌ JAMAIS en prod
- ansible.builtin.yum_repository:
    name: insecure-repo
    baseurl: "https://repo.example.com/"
    gpgcheck: false    # ← faille

# ✓ Toujours
- ansible.builtin.yum_repository:
    name: secure-repo
    baseurl: "https://repo.example.com/"
    gpgcheck: true
    gpgkey: https://repo.example.com/RPM-GPG-KEY

Encore mieux : ajouter repo_gpgcheck: true qui force la vérification de la signature de la metadata du dépôt (en plus des paquets) :

- ansible.builtin.yum_repository:
    name: secure-repo
    baseurl: "https://repo.example.com/"
    gpgcheck: true
    repo_gpgcheck: true     # vérifie aussi la signature de repomd.xml
    gpgkey: https://repo.example.com/RPM-GPG-KEY

Tous les dépôts modernes (EPEL 9+, Docker CE) supportent repo_gpgcheck.

`mirrorlist` vs `baseurl`

Pour les dépôts qui supportent plusieurs miroirs :

- ansible.builtin.yum_repository:
    name: epel
    description: "EPEL via mirror"
    mirrorlist: "https://mirrors.fedoraproject.org/metalink?repo=epel-9&arch=$basearch"
    # PAS de baseurl ici — mirrorlist gère le choix
    gpgcheck: true
    gpgkey: https://dl.fedoraproject.org/pub/epel/RPM-GPG-KEY-EPEL-9

mirrorlist ou metalink retourne dynamiquement la liste des miroirs disponibles, dnf choisit le plus proche. Avantage : résilience si un miroir tombe. Inconvénient : moins déterministe en environnement air-gapped.

Pour un environnement isolé ou prod stable : préférer baseurl pointant vers votre mirror interne.

Pièges courants

Symptôme	Cause	Solution
`GPG check FAILED` au 1er `dnf install`	Clé GPG pas importée avant la déclaration	Toujours `rpm_key` AVANT `yum_repository`
`repository <name> is not configured`	Nom du dépôt vs nom du fichier confondus	`name:` = identifiant interne, `file:` = nom du fichier .repo
Dépôt RHEL géré par subscription-manager qui revient après `dnf update`	Modification d'un fichier RPM-managed	Créer un fichier `.repo` à part avec `file: overrides`
Macros `$basearch` non résolues dans le rôle	Quoted comme une string Ansible	Toujours quoter (`baseurl: "...$basearch..."`), yum résout, pas Ansible
`mirrorlist` retourne 404	URL incorrecte ou réseau bloqué	Tester `curl <mirrorlist-url>` manuellement
`gpgcheck: yes` ignoré si `repo_gpgcheck` activé sur un repo non signé	Métadonnée non signée du dépôt	Désactiver `repo_gpgcheck` ou demander la signature au mainteneur
Module Ansible introuvable	Vieille version Ansible	`yum_repository` est dans `ansible.builtin` depuis ansible-core 2.9

À retenir

yum_repository déclare un dépôt, pas un paquet (utiliser dnf ou package pour ça).
rpm_key AVANT yum_repository, la clé GPG doit exister avant la déclaration.
gpgcheck: true est non négociable. repo_gpgcheck: true mieux quand supporté.
Variables $releasever/$basearch doivent rester dans le .repo, ne pas les remplacer en dur.
enabled: false + state: present = dépôt déclaré mais inactif (cas désactivation contrôlée).
file: distinct de name:, un fichier peut contenir plusieurs sections [repo].
mirrorlist OU baseurl, jamais les deux.

Pratiquer dans le lab

Cette page a un lab d'accompagnement : labs/modules-paquets/yum-repository/ dans stephrobert/ansible-training.

Challenge, sur db1.lab (AlmaLinux 10) :

Importer la clé GPG EPEL via rpm_key: (URL https://dl.fedoraproject.org/pub/epel/RPM-GPG-KEY-EPEL-10).
Déclarer le dépôt EPEL avec gpgcheck: true et enabled: true.
Installer le paquet htop (présent dans EPEL, absent de la base) avec dnf:.
Déclarer un dépôt local local-test avec enabled: false (présent mais inactif).

Validation pytest+testinfra :

ansible-playbook labs/modules-paquets/yum-repository/challenge/solution.yml
ansible-playbook labs/modules-paquets/yum-repository/challenge/solution.yml  # 2e run = changed=0
pytest -v labs/modules-paquets/yum-repository/challenge/tests/

Les tests vérifient l'existence de /etc/yum.repos.d/epel.repo, le contenu (enabled=1, gpgcheck=1), l'installation de htop, et le enabled=0 pour local-test.

Prochaines étapes

Module package, installer un paquet (multi-distro) Le wrapper portable qui choisit dnf, apt, pacman, etc. selon l'OS.

Module dnf, options spécifiques RPM Pour les options dnf-specific (allowerasing, downgrade, autoremove).

Multi-distribution packages Pattern pour gérer paquets dnf et apt dans le même rôle.

Vue d'ensemble des modules Catalogue complet par catégorie.