Versionner ses modules Terraform avec Git

Versionner un module Terraform consiste à associer un tag Git sémantique à chaque version stable du code. Cela permet aux projets consommateurs de choisir précisément quelle version utiliser, d’éviter les régressions et de planifier les mises à jour. Sans versionnement, modifier un module impacte immédiatement tous les projets qui le consomment.

Prérequis : avoir lu Utiliser un module local et Utiliser un module du Registry.

Ce que vous allez apprendre

• Comprendre pourquoi le versionnement est indispensable
• Appliquer le versionnement sémantique (SemVer) aux modules
• Créer des tags Git pour versionner un module
• Référencer une version spécifique depuis un projet consommateur
• Mettre à jour un module de façon contrôlée

Pourquoi versionner

Le problème sans versionnement

Avec un module local (source = "../modules-partages/reseau"), toute modification du module est immédiatement visible par tous les projets qui le consomment. Cela signifie qu’un changement dans le module peut casser un projet en production sans prévenir.

modules-partages/reseau/  ← une modification ici...
├── projet-dev/           ← ...impacte ici
├── projet-staging/       ← ...et ici
└── projet-prod/          ← ...et ici aussi !

La solution : les versions

Le versionnement découple le rythme de développement du module du rythme d’adoption par les projets. Chaque projet choisit quand monter en version :

module "reseau" {
  source  = "git::https://gitlab.example.com/infra/modules.git//reseau?ref=v1.2.0"
  # ↑ ce projet utilise la v1.2.0 — il ne sera pas impacté par des changements ultérieurs
}

Le versionnement sémantique (SemVer)

Le standard utilisé par Terraform et le Registry est le Semantic Versioning (SemVer) : MAJOR.MINOR.PATCH.

Composant	Quand l’incrémenter	Exemple
MAJOR	Changement incompatible (breaking change)	1.0.0 → 2.0.0
MINOR	Nouvelle fonctionnalité rétrocompatible	1.0.0 → 1.1.0
PATCH	Correction de bug rétrocompatible	1.0.0 → 1.0.1

Glissez pour voir

Exemples concrets pour un module réseau

Modification	Type	Version
Corriger le message d’erreur d’une validation	PATCH	1.0.0 → 1.0.1
Ajouter une variable optionnelle tags avec default = {}	MINOR	1.0.1 → 1.1.0
Renommer cidr en network_config (breaking)	MAJOR	1.1.0 → 2.0.0
Supprimer une variable existante	MAJOR	1.1.0 → 2.0.0
Ajouter un nouvel output	MINOR	1.1.0 → 1.2.0

Glissez pour voir

Ce qui est un breaking change

Tout changement qui oblige les projets consommateurs à modifier leur bloc module est un breaking change : renommer une variable, supprimer une variable, changer le type d’une variable, renommer un output.

Versionner avec des tags Git

1. Initialiser un dépôt Git pour les modules :

   cd modules-partages/
   git init
   git add .
   git commit -m "feat: module réseau initial"

2. Créer un tag pour la première version :

   git tag -a v1.0.0 -m "Version initiale du module réseau"
   git push origin v1.0.0

3. Après une modification mineure (ajout d’une variable optionnelle) :

   # Modifier le code...
   git add .
   git commit -m "feat(reseau): ajouter variable tags optionnelle"
   git tag -a v1.1.0 -m "Ajout de la variable tags"
   git push origin v1.1.0

4. Après un breaking change (renommage de variable) :

   # Modifier le code...
   git add .
   git commit -m "BREAKING CHANGE(reseau): renommer cidr en network_config"
   git tag -a v2.0.0 -m "Renommage cidr → network_config"
   git push origin v2.0.0

Tags annotés

Utilisez toujours git tag -a (tag annoté) plutôt que git tag (tag léger). Les tags annotés stockent l’auteur, la date et un message — utiles pour l’historique.

Référencer une version dans un projet

Depuis un dépôt Git

module "reseau" {
  source = "git::https://gitlab.example.com/infra/modules.git//reseau?ref=v1.2.0"
  # ↑ URL Git       ↑ chemin du module dans le dépôt    ↑ tag Git
}

La syntaxe ?ref=v1.2.0 fige la version. Même si de nouvelles versions sont publiées, ce projet reste sur v1.2.0.

ref peut pointer vers un tag, une branche ou un commit SHA, mais pour un module partagé entre équipes, un tag Git sémantique reste le choix le plus lisible et le plus sûr.

Depuis le Terraform Registry

module "vpc" {
  source  = "terraform-aws-modules/vpc/aws"
  version = "5.21.0"
  # ↑ contrainte de version gérée par le Registry
}

Contraintes de version

Les mêmes contraintes que pour les providers s’appliquent :

version = "1.2.0"       # exactement 1.2.0
version = "~> 1.2.0"    # >= 1.2.0 et < 1.3.0 (patchs uniquement)
version = "~> 1.2"      # >= 1.2.0 et < 2.0.0 (évolutions compatibles de la même majeure)
version = ">= 1.0, < 2.0"  # plage explicite

Contrainte	Recommandation	Cas d’usage
"1.2.0"	Production	Reproductibilité maximale
"~> 1.2.0"	Staging	Recevoir les patchs automatiquement
"~> 1.2"	Développement	Recevoir les évolutions compatibles de la même majeure

Glissez pour voir

Choisir la bonne souplesse

Plus votre environnement est sensible, plus la contrainte doit être étroite. Une version exacte maximise la reproductibilité. Une contrainte ~> réduit l’effort de maintenance, mais doit rester cohérente avec votre tolérance au changement.

Workflow de mise à jour

Quand une nouvelle version d’un module est disponible, chaque projet décide quand l’adopter :

1. Lire le changelog de la nouvelle version pour identifier les changements

2. Mettre à jour la contrainte de version dans le bloc module :

   module "reseau" {
     source = "git::https://gitlab.example.com/infra/modules.git//reseau?ref=v1.3.0"
     # ↑ v1.2.0 → v1.3.0
   }

3. Relancer terraform init pour télécharger la nouvelle version :

   terraform init -upgrade
   # -upgrade force le re-téléchargement même si une version est déjà en cache

4. Exécuter terraform plan pour voir les changements prévus :

   terraform plan
   # Vérifier qu'aucune destruction inattendue n'apparaît

5. Appliquer si le plan est correct

Un projet à la fois

L’avantage du versionnement est de pouvoir mettre à jour un projet à la fois. On met d’abord à jour le projet-dev, on vérifie que tout fonctionne, puis on passe au projet-staging, et enfin au projet-prod.

Organisation d’un dépôt multi-modules

Pour un dépôt Git contenant plusieurs modules, la convention est :

terraform-modules/
├── reseau/
│   ├── versions.tf
│   ├── variables.tf
│   ├── main.tf
│   └── outputs.tf
├── volume/
│   ├── versions.tf
│   ├── variables.tf
│   ├── main.tf
│   └── outputs.tf
├── vm/
│   └── ...
├── CHANGELOG.md
└── README.md

Le tag versionne tout le dépôt. Si les modules évoluent à des rythmes différents, deux approches existent :

Approche	Avantage	Inconvénient
Mono-dépôt (1 tag pour tout)	Simple à gérer	Un changement dans reseau/ force un nouveau tag même si vm/ n’a pas changé
Multi-dépôts (1 dépôt par module)	Versionnement indépendant	Plus de dépôts à maintenir

Glissez pour voir

Pour commencer, le mono-dépôt est recommandé. Passez au multi-dépôts quand les modules évoluent à des rythmes très différents.

CHANGELOG

Un fichier CHANGELOG.md à la racine du dépôt de modules documente l’historique des versions :

# Changelog

## [1.2.0] - 2025-03-31
### Added
- Variable `tags` optionnelle sur le module réseau

## [1.1.0] - 2025-03-15
### Added
- Output `configuration` structuré sur le module réseau

## [1.0.0] - 2025-03-01
### Added
- Module réseau initial (libvirt_network)

Ce format suit la convention Keep a Changelog.

Dépannage

Symptôme	Cause probable	Solution
terraform init ne télécharge pas la nouvelle version	Version en cache	Ajouter -upgrade à terraform init
ref not found avec source Git	Tag inexistant ou faute de frappe	Vérifier avec git tag -l sur le dépôt
Changements inattendus après mise à jour	Breaking change non documenté	Revenir à l’ancienne version et lire le changelog
version ... does not match (Registry)	Contrainte trop restrictive	Élargir la contrainte ou spécifier la version exacte

Glissez pour voir

À retenir

1. Sans versionnement, modifier un module impacte immédiatement tous les projets
2. Le versionnement sémantique (MAJOR.MINOR.PATCH) communique la nature du changement
3. Tout changement qui oblige à modifier le bloc module est un breaking change (MAJOR)
4. Les tags Git annotés (git tag -a) sont le mécanisme de versionnement
5. ?ref=vX.Y.Z (Git) ou version = "X.Y.Z" (Registry) figent la version dans un projet
6. -upgrade sur terraform init force le re-téléchargement d’une version
7. Mettez à jour un environnement à la fois : dev → staging → prod

Prochaines étapes

Tester un module

Bonnes pratiques modules

Anti-patterns modules

×

📖 Voir la documentation →