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

Deux tâches suffisent, et leur ordre est la seule chose à retenir de cet exemple : la clé GPG entre d'abord dans le trousseau, la déclaration du dépôt vient ensuite. Inverser les deux produit un dépôt en apparence correct, dont la première installation échoue sur une vérification de signature. Le reste du bloc décrit un dépôt public classique, une adresse de base portant la macro d'architecture et la vérification des paquets activée.

- 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 :

1. 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.
2. Déclarer le dépôt ensuite avec gpgcheck: true et gpgkey: pointant vers la même clé.

Les paramètres essentiels

- name: Déclarer le dépôt docker-ce
  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.

Modification d'un fichier .repo géré par un RPM

Les fichiers .repo distribués par un paquet RPM (ex. redhat.repo géré par subscription-manager) sont écrasés par le paquet à chaque mise à jour. Modifier ces fichiers via yum_repository peut être annulé au prochain dnf update. Solution : créer un fichier .repo séparé (file: my-overrides) qui désactive le dépôt par son name exact, Ansible gérera ce fichier sans toucher à celui du paquet.

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…)

Glissez pour voir

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
- name: Déclarer le dépôt insecure-repo
  ansible.builtin.yum_repository:
    name: insecure-repo
    baseurl: "https://repo.example.com/"
    gpgcheck: false    # ← faille

# ✓ Toujours
- name: Déclarer le dépôt secure-repo
  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) :

- name: Déclarer le dépôt secure-repo
  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 :

- name: Déclarer le dépôt epel
  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

Cinq de ces sept lignes décrivent un dépôt déclaré mais inutilisable : clé GPG absente, macro laissée à résoudre par le mauvais moteur, adresse de miroir injoignable, signature de métadonnées exigée sur un dépôt qui n'en a pas, fichier repris par l'abonnement de la distribution. Les deux autres relèvent de la confusion de nommage entre l'identifiant du dépôt et le nom du fichier, et d'une version d'Ansible trop ancienne pour le module.

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

Glissez pour voir

Contrôle de connaissances

Vérifiez que l'essentiel de ce guide est acquis. Les questions portent uniquement sur ce qui vient d'être expliqué ici.

Contrôle de connaissances

Validez vos connaissances avec ce quiz interactif

6 questions

6 min.

70% requis

Informations

• Le chronomètre démarre au clic sur Démarrer
• Questions à choix multiples, vrai/faux et réponses courtes
• Vous pouvez naviguer entre les questions
• Les résultats détaillés sont affichés à la fin

Démarrer le quiz

Lance le quiz et démarre le chronomètre

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

Mettre en pratique

L'ordre des opérations est ce qui coince le plus souvent : une clé importée après la déclaration du dépôt et l'installation échoue. Ce lab vous fait donc importer la clé avec rpm_key, déclarer le dépôt avec gpgcheck actif, installer un paquet qui n'existe que là, puis poser un second dépôt en enabled: false pour le garder sous la main sans l'activer. Le contrôle porte sur le contenu des fichiers .repo générés.

Lab pratique

Module yum_repository : déclarer un dépôt RPM

$ dsoxlab run modules-paquets-yum-repository

Environnement : VM·Durée : ~35 min

Validé : l'état du système est vérifié après reboot, pas la commande tapée.

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 et brancher le catalogue, une seule fois :

uv tool install dsoxlab   # ou : pipx install dsoxlab
dsoxlab catalog add https://github.com/stephrobert/ansible-training

Lancer ce lab, puis valider votre travail :

dsoxlab run modules-paquets-yum-repository
dsoxlab check modules-paquets-yum-repository

Voir tous les labs : dsoxlab list-labs. Suivre sa progression : dsoxlab progress. Le guide complet de dsoxlab détaille l'installation, le calcul du score et les pièges.

Pour aller plus loin

• Multi-distribution : déclarer un dépôt côté Debian ne passe pas par le même module, cette page donne les branchements.
• Module mount : un dépôt local sert souvent une image ISO montée, à gérer proprement dans fstab.

×

📖 Voir la documentation →