Modules réutilisables : interface, version, publication

Un module réutilisable est un morceau d'infrastructure qu'on écrit une fois et qu'on appelle depuis plusieurs endroits, avec une interface claire et un numéro de version. Sans version, une correction du module change en même temps tous ses utilisateurs, sans que personne ne l'ait décidé. Cette leçon explique comment concevoir l'interface d'un module comme un contrat, comment le numéroter avec semver, pourquoi on l'épingle toujours sur une version précise et jamais sur une branche, et comment le publier puis le mettre à jour sans surprise. Elle suit le scénario de l'équipe de quatre personnes : deux VM applicatives, une base, un réseau, un DNS, un dev et une prod, infrastructure en cours de passage au code.

Ce que vous allez apprendre

• décrire l'interface d'un module comme un contrat d'entrées et de sorties ;
• classer un changement selon semver : correctif, évolution ou changement cassant ;
• épingler une version de module et justifier pourquoi une branche ne convient jamais ;
• choisir où publier un module : dépôt Git ou registre ;
• organiser une mise à jour contrôlée.

Les extraits de code sont des illustrations à lire, pas des étapes à exécuter. L'outillage détaillé reste dans les formations Terraform et Ansible, liées dans le texte.

Qu'est-ce qu'un module et pourquoi lui donner une interface ?

Un module est un bloc d'IaC paramétrable : on lui passe des valeurs en entrée, il crée des ressources et renvoie des valeurs en sortie. Selon l'outil, il porte un autre nom : module en Terraform et OpenTofu, rôle ou collection en Ansible. Dans le scénario, l'équipe écrit un module vm-applicative qui crée une machine avec son disque, son rattachement réseau et ses étiquettes ; dev et prod l'appellent chacun deux fois, une par VM applicative.

L'interface du module est l'ensemble de ce qu'un appelant voit : les variables d'entrée, les valeurs de sortie et le comportement documenté. Tout le reste (le nom interne des ressources, l'organisation des fichiers) est un détail d'implémentation que l'appelant n'a pas à connaître. C'est ce qui permet de corriger l'intérieur sans toucher aux appelants tant que l'interface ne bouge pas.

Une bonne interface reste petite. Chaque entrée expose un choix que l'appelant doit vraiment faire (taille, sous-réseau, étiquettes) et donne une valeur par défaut sûre pour le reste. Chaque sortie publie ce dont un autre composant a besoin (l'identifiant, l'adresse privée). Une validation d'entrée qui refuse une valeur absurde dès le plan évite un échec tardif chez le fournisseur. La mécanique Terraform des variables et des sorties est détaillée dans Variables et outputs d'un module Terraform.

Comment numéroter un module avec semver ?

Semver (versionnement sémantique) numérote une version MAJEUR.MINEUR.CORRECTIF, par exemple 1.4.2, et le numéro annonce la nature du changement. Le principe est simple : l'appelant doit pouvoir deviner, rien qu'en lisant le numéro, s'il peut adopter la nouvelle version sans rien modifier de son côté.

Numéro qui change	Nature du changement	Exemple pour vm-applicative	Risque pour l'appelant
Correctif (1.4.2 vers 1.4.3)	Correction sans changement d'interface	Une étiquette mal calculée est corrigée	Très faible
Mineur (1.4.3 vers 1.5.0)	Ajout compatible	Nouvelle entrée facultative taille_disque	Faible
Majeur (1.5.0 vers 2.0.0)	Changement cassant	Une entrée est renommée ou une sortie supprimée	Élevé, lecture du plan obligatoire

Glissez pour voir

En IaC, un piège spécifique : un changement interne peut être cassant sans toucher l'interface. Renommer une ressource dans le module fait croire à l'outil qu'il faut détruire l'ancienne et en créer une nouvelle. Pour une VM, c'est une recréation ; pour une base de données, c'est la perte des données. Ce type de changement se numérote en majeur, ou se protège par une instruction de migration que fournit l'outil (le geste est détaillé dans les formations d'outil).

Autre cas : changer une valeur par défaut. L'interface ne bouge pas, mais le comportement oui. Mieux vaut le traiter comme au moins une évolution mineure documentée, voire majeure si le plan des appelants change.

Pourquoi épingler une version, et jamais une branche ?

Épingler un module signifie le référencer par une version précise qui ne change pas sans décision. Référencer une branche comme main revient à dire « prends toujours la dernière chose écrite » : la prochaine exécution du plan de prod embarquera donc un changement que personne n'a relu dans ce contexte. La reproductibilité, qui est l'une des raisons d'être de l'IaC, disparaît.

# ❌ Contre-exemple : la branche bouge à chaque merge
module "vm_applicative" {
  source = "git::ssh://git@forge.interne/infra/module-vm-applicative.git?ref=main"
}

# Correct : une version précise, qui change par un commit de l'appelant
module "vm_applicative" {
  source = "git::ssh://git@forge.interne/infra/module-vm-applicative.git?ref=v1.4.2"
}

Deux nuances. D'abord, un tag Git peut être déplacé par quelqu'un qui en a le droit : pour une exigence forte, on protège les tags contre la réécriture ou on épingle l'identifiant exact du commit. Ensuite, un registre de modules accepte des contraintes de version comme « compatible avec 1.4 » : c'est pratique, mais la contrainte laisse entrer des correctifs automatiquement. Pour la production, mieux vaut une version exacte et une mise à jour décidée que l'on suit dans une pull request.

La leçon Versionner ses modules Terraform avec Git détaille la mécanique Terraform (tag, ref, SHA), et Versionner et publier un rôle Ansible celle des rôles Ansible. Côté Ansible, le même principe s'applique aux collections qu'on installe depuis un fichier de dépendances avec une version fixée : voir requirements.yml Ansible.

Où publier un module : dépôt Git ou registre ?

Un module doit être retrouvable, versionné et documenté au même endroit. Deux options couvrent la plupart des cas. Le dépôt Git de l'équipe suffit pour démarrer : un dépôt par module (ou un sous-répertoire dans un dépôt de modules), des tags de version, un fichier README qui décrit l'interface. Les tags de version sont ceux de Tags Git : versionner et publier vos releases. Un registre apporte en plus une recherche, une documentation générée des entrées et des sorties, et une résolution de version par contrainte.

Option	Convient quand	Limite
Dépôt Git avec tags	Petite équipe, quelques modules internes	Pas de recherche, documentation à tenir à la main
Registre public	Module générique maintenu par une communauté	Dépendance à un tiers : lire le code avant d'adopter, épingler
Registre privé	Plusieurs équipes, plusieurs dizaines de modules	Un service de plus à exploiter

Glissez pour voir

Pour un module tiers, la règle ne change pas : on lit son code avant de l'adopter, on épingle sa version et on suit ses évolutions. La leçon Utiliser un module du Terraform Registry montre le geste côté Terraform.

Comment mettre à jour un module sans casser la production ?

Une mise à jour contrôlée passe toujours par une modification de l'appelant, relue comme n'importe quel changement. Le numéro de version n'est modifié que dans une pull request, qui montre le plan produit par la nouvelle version pour chaque environnement.

Le scénario le montre bien : le module vm-applicative passe de 1.4.2 à 1.5.0. L'équipe change d'abord la version dans la configuration de dev. Le plan de dev doit montrer exactement le changement annoncé dans les notes de version ; s'il montre une recréation de VM non prévue, la version est refusée. Une fois dev stable, le même numéro est reporté dans prod, avec le plan de prod joint à la pull request. La leçon Environnements et promotion d'un changement approfondit cette progression.

Pour ne pas rater les nouvelles versions, un robot de mise à jour des dépendances (par exemple Renovate ou Dependabot) peut ouvrir une pull request automatique à chaque publication. Il propose, il ne décide pas : la revue et la lecture du plan restent humaines.

Un module a besoin de notes de version qui disent, pour chaque numéro, ce qui change et ce que l'appelant doit modifier. Sans elles, le numéro de version ne sert qu'à moitié.

Quelles erreurs fréquentes avec les modules ?

• Pointer sur main « pour avoir toujours la dernière version ». Le plan de production change sans que quiconque l'ait décidé.
• Publier des changements cassants en mineur. L'appelant fait confiance au numéro et découvre la recréation de ressources dans son plan, au meilleur moment pour l'ignorer.
• Exposer trop d'entrées. Un module qui accepte quarante variables n'abstrait plus rien : il reprend le fournisseur, avec une couche en plus.
• Un module qui impose ses choix de fournisseur ou de secrets. Mieux vaut qu'il reçoive ce dont il a besoin en entrée.
• Copier le module dans chaque environnement au lieu de le versionner : chaque copie dérive, et la correction doit être refaite autant de fois.

À retenir

• Un module a une interface : des entrées, des sorties et un comportement documenté ; le reste est interne.
• Semver annonce la nature du changement ; un renommage interne qui recrée des ressources est un changement majeur.
• On épingle une version précise, jamais une branche comme main ; un tag peut être déplacé, l'identifiant de commit non.
• Un dépôt Git avec tags suffit pour démarrer ; un registre apporte recherche, documentation et résolution des versions.
• La mise à jour passe par une pull request de l'appelant, avec le plan de chaque environnement, d'abord en dev puis en prod.

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

×

📖 Voir la documentation →