Utiliser un module du Terraform Registry

Le Terraform Registry est le catalogue officiel de modules réutilisables : au lieu d'écrire un VPC ou une politique IAM, vous appelez un module publié et maintenu par un tiers. Le geste tient en deux lignes, source et version, mais la mécanique derrière mérite d'être connue : un module de registre est téléchargé, il porte une version résolue, et le fichier de verrouillage qui protège vos providers ne le protège pas.

Tout ce qui suit a été exécuté sur Terraform v1.15.4 avec un module réel, cloudposse/label/null, qui ne déclare aucun provider et s'applique sans compte cloud : sorties, erreurs et contenu de modules.json compris. Deux idées très répandues n'y survivent pas, celle de l'argument version obligatoire, et celle du .terraform.lock.hcl qui figerait les modules.

Ce que vous allez apprendre

• D'où vient l'adresse en trois parties, et pourquoi elle n'est pas arbitraire
• Ce que init télécharge exactement, et dans quel fichier il l'enregistre
• Pourquoi le verrou ignore les modules, et ce qui les fige à sa place
• Comment débloquer une contrainte souple restée sur une vieille version
• Pourquoi deux appels du même module peuvent installer deux versions
• Où placer un sous-répertoire // face à un ?ref=

Prérequis

• Terraform 1.11 ou plus récent (installer Terraform).
• Savoir appeler un module et connaître le cas du module local, dont ce guide est le pendant distant.

D'où vient l'adresse en trois parties

Une source de registre s'écrit namespace/name/provider, sans préfixe ./ ni ../ :

module "etiquette" {
  source  = "cloudposse/label/null"
  version = "0.25.0"

  namespace = "demo"
  name      = "ouest"
}

Ce format n'est pas une convention de nommage arbitraire, il se déduit du dépôt publié. Les règles de publication sont explicites : « Module repositories must use this three-part name format », terraform-<PROVIDER>-<NAME>, le dépôt doit être public sur GitHub, respecter la structure standard, et porter des tags de version sémantique. Le dépôt cloudposse/terraform-null-label donne donc l'adresse cloudposse/label/null.

Partie	D'où elle vient	Exemple
namespace	l'organisation du dépôt	cloudposse
name	le <NAME> du dépôt	label
provider	le <PROVIDER> du dépôt	null

Glissez pour voir

Deux remarques utiles. Le <PROVIDER> n'est pas forcément un cloud, ici c'est null, et le module reste utilisable sans compte. Un détail explique par ailleurs bien des versions introuvables : « Tags that don't look like version numbers are ignored », un v1.2.0 étant accepté mais un release-mars invisible pour le registre.

Ce que terraform init télécharge

Contrairement au module local, l'init télécharge vraiment, et il le dit :

$ terraform init

Initializing modules...
Downloading registry.terraform.io/cloudposse/label/null 0.25.0 for etiquette...
- etiquette in .terraform/modules/etiquette

Le registre des modules, .terraform/modules/modules.json, enregistre trois informations là où un module local n'en avait que deux :

{
  "Key": "etiquette",
  "Source": "registry.terraform.io/cloudposse/label/null",
  "Version": "0.25.0",
  "Dir": ".terraform/modules/etiquette"
}

La clé Version est celle qui compte, et elle n'existe que pour un module de registre : c'est la version résolue, celle qui tourne réellement. Dir pointe cette fois sous .terraform/, la copie étant bien réelle.

Ce dossier téléchargé n'a rien de spécial, c'est le dépôt tel quel :

ls -A .terraform/modules/etiquette/

descriptors.tf  docs  examples  exports  .git  .github  LICENSE  main.tf
Makefile  outputs.tf  README.md  README.yaml  test  variables.tf

Vous y trouvez donc les fichiers du module, mais aussi ses exemples, ses tests et son .git. C'est le meilleur endroit pour lire le code que vous venez d'adopter.

Un module de registre n'a rien de magique

C'est un dépôt Git indexé par le registre. Terraform le télécharge, le place dans .terraform/modules/, puis le traite exactement comme un module local. Le registre n'apporte que deux choses, la découverte et le versionnement.

L'argument version est facultatif, et c'est un piège

Beaucoup d'articles le donnent pour obligatoire. Il ne l'est pas : retirez-le, et l'init passe.

Initializing modules...
Downloading registry.terraform.io/cloudposse/label/null 0.25.0 for etiquette...

Terraform a retenu la plus récente disponible, sans un mot d'avertissement. Rien ne l'interdit, et c'est justement ce qui rend l'omission coûteuse : le même code, initialisé demain sur un autre poste, prendra une autre version. Écrire version n'est donc pas une contrainte de l'outil, c'est une décision qui vous appartient.

Le verrou ne couvre pas les modules

Voici le point le plus mal connu du sujet, et la documentation ne le cache pas : « At present, the dependency lock file tracks only provider dependencies. Terraform does not remember version selections for remote modules. »

Deux observations le prouvent. Dans un projet qui déclare un provider, le verrou ne parle que de lui :

grep -c cloudposse .terraform.lock.hcl

0

Et dans un projet dont la seule dépendance est un module de registre, il n'y a aucun fichier de verrouillage : l'init n'en crée même pas.

Ce qui fige un module, c'est vous

Un provider non épinglé reste reproductible grâce au verrou. Un module non épinglé ne l'est pas. La seule chose qui fixe une version de module est la contrainte que vous écrivez, et la seule qui la fixe complètement est une version exacte : « You can use an exact version constraint to ensure that Terraform will always select the same module version. »

Pourquoi votre ~> 5.0 reste bloqué

Ce comportement ne se devine pas, et tout le monde finit par le rencontrer. Avec une contrainte souple, la version retenue au premier init reste installée aux suivants :

$ terraform init          # premier init, contrainte ~> 0.24
Downloading registry.terraform.io/cloudposse/label/null 0.24.1 for etiquette...

$ terraform init          # second init, rien ne bouge
Initializing modules...

modules.json porte toujours 0.24.1, alors que 0.25.0 existe et satisfait la contrainte. La documentation l'énonce : « Terraform uses the newest installed version of the module that meets the constraint. » Une seule option débloque la situation :

$ terraform init -upgrade
Upgrading modules...
Downloading registry.terraform.io/cloudposse/label/null 0.25.0 for etiquette...

Le cas symétrique est instructif. Faites reculer la contrainte vers une version antérieure : la copie installée ne satisfait plus la contrainte, donc l'init télécharge, sans -upgrade.

Situation au moment de l'init	Ce que fait init seul
aucune copie installée	télécharge la plus récente qui satisfait
la copie installée satisfait la contrainte	la conserve, même si plus récent existe
la copie installée ne satisfait plus	télécharge une version conforme
avec -upgrade	réévalue dans tous les cas

Glissez pour voir

La conséquence pratique est brutale : sur un poste vierge ou dans une CI, aucune copie n'est installée, donc la plus récente s'installe. Le même code n'utilise pas la même version chez vous et dans le pipeline, et c'est exactement ce que le verrou empêcherait s'il couvrait les modules.

La résolution se fait par appel, pas par projet

Deux blocs module du même module, avec deux contraintes différentes, installent deux versions dans un seul projet :

module "etiquette" {
  source  = "cloudposse/label/null"
  version = "~> 0.24"

  namespace = "atelier"
  name      = "large"
}

module "etiquette_patch" {
  source  = "cloudposse/label/null"
  version = "~> 0.24.1"

  namespace = "atelier"
  name      = "etroit"
}

Downloading registry.terraform.io/cloudposse/label/null 0.25.0 for etiquette...
Downloading registry.terraform.io/cloudposse/label/null 0.24.1 for etiquette_patch...

Chaque appel a son entrée dans modules.json et son dossier dans le cache. C'est utile pour migrer progressivement un projet d'une version à l'autre, et c'est un piège de lecture : le numéro visible sur la page du registre ne dit rien de ce que votre appel a installé.

Les formes de contraintes elles-mêmes sont détaillées dans contraintes de version ; retenez ici que ~> laisse bouger le composant le plus à droite.

Le sous-répertoire //, et l'ordre qui compte

// n'est pas une notion de registre mais de paquet : elle désigne un sous-répertoire à l'intérieur de ce que Terraform a téléchargé, dépôt Git ou archive compris.

module "iam_account" {
  source  = "terraform-aws-modules/iam/aws//modules/iam-account"
  version = "5.52.2"
}

Sur une source Git, elle cohabite avec un argument de requête comme ?ref=, et l'ordre des deux n'est pas libre : « If the source address has arguments, such as the ref argument [...] the sub-directory portion must be before those arguments ».

# correct
source = "git::https://example.com/reseau.git//modules/vpc?ref=v1.2.0"

# correct aussi, raccourci GitHub
source = "github.com/hashicorp/example//modules/vpc?ref=v1.2.0"

L'ordre inverse produit une erreur qui nomme le vrai coupable, la révision :

Error: Failed to download module

error downloading '...?ref=0.25.0%2F%2Fexports': invalid ref: "0.25.0//exports"

Terraform a pris 0.25.0//exports pour un nom de révision, ce qu'il n'est évidemment pas.

Toutes les sources acceptées par source

Le tableau ci-dessous reprend la liste officielle. Les deux premières lignes sont celles que vous écrirez presque toujours, les autres méritent d'être connues pour les reconnaître dans le code d'autrui :

Source	Format source	version	Ce que fait Terraform
Local	"./modules/reseau"	refusé	lecture sur place
Registre public	"namespace/name/provider"	accepté	téléchargement depuis registry.terraform.io
Registre privé	"app.terraform.io/org/name/provider"	accepté	jeton dans la configuration CLI
GitHub	"github.com/org/repo//sous-dir?ref=tag"	non, ?ref=	clone Git
Bitbucket	"bitbucket.org/org/repo"	non	dépôts publics seulement, l'API décidant Git ou Mercurial
Git générique	"git::https://exemple.com/repo.git"	non, ?ref=	clone Git, ?depth=1 possible
Mercurial	"hg::https://exemple.com/repo"	non	clone Mercurial
HTTP	"https://exemple.com/module"	non	indirection via terraform-get=1
Archive	"https://exemple.com/mod.zip"	non	extensions reconnues, ou ?archive=zip
S3	"s3::https://bucket/mod.zip"	non	authentification AWS, pas un simple HTTP
GCS	"gcs::https://storage.googleapis.com/..."	non	authentification Google

Glissez pour voir

Deux pièges valent d'être signalés. Sur une source Git, ?depth=1 accélère le clone mais change la sémantique de ref : « setting the depth argument makes Terraform pass your ref argument [...] to the --branch argument to git clone », donc un commit brut n'est plus accepté, seulement une branche ou un tag. Et s3:: n'est pas un téléchargement anonyme, le module installer cherche des identifiants AWS, variables d'environnement puis profil puis rôle d'instance.

Les identifiants ne se configurent pas dans Terraform

Chaque protocole utilise son mécanisme habituel : Git s'appuie sur votre configuration Git et vos clés SSH, HTTP sur un fichier .netrc (chemin surchargeable par la variable NETRC), et un registre privé sur un jeton déclaré dans la configuration CLI. Terraform n'a aucun argument de bloc pour ces secrets.

Prouver ce qui est réellement installé

La sortie humaine de l'init défile et disparaît. Deux artefacts, en revanche, restent, et ils ne disent pas la même chose :

Artefact	Ce qu'il donne
.terraform/modules/modules.json	la version résolue, réellement installée
terraform show -json <plan>	la contrainte écrite dans la configuration

Glissez pour voir

terraform plan -out=plan.tfplan
terraform show -json plan.tfplan | jq '.configuration.root_module.module_calls'

{
  "etiquette": {
    "source": "cloudposse/label/null",
    "version_constraint": "0.25.0",
    "expressions": { "namespace": { "constant_value": "demo" } }
  }
}

Notez que source est ici l'adresse telle que vous l'avez écrite, sans l'hôte du registre que modules.json ajoute. Le champ version_constraint n'existe pas pour un module local, et c'est lui qui permet à une revue ou une CI de refuser un appel non épinglé. La comparaison des deux fichiers répond à la seule question qui compte : ma contrainte est-elle souple, et ai-je une version périmée installée ?

terraform validate ne remplace pas l'init

On lit souvent que validate vérifie une configuration à module distant sans rien télécharger. C'est faux, et la mesure est immédiate sur un dossier neuf :

$ terraform validate

Error: Module not installed

This module is not yet installed. Run "terraform init" to install all modules
required by this configuration.

Ce qui est vrai, c'est que validate n'a besoin d'aucun credential de cloud. Mais il exige un init réussi, donc le téléchargement du module et du provider. Hors ligne, une configuration à module de registre ne se valide pas, et c'est une contrainte à connaître pour une CI en réseau fermé.

Quand préférer le registre au module local

La documentation répartit les deux mécanismes en une phrase : « We recommend using local file paths for closely-related modules used primarily for the purpose of factoring out repeated code elements, and using a native Terraform module registry for modules intended to be shared by multiple calling configurations. »

Situation	Ce qui convient
brique standard (VPC, IAM, réseau)	module de registre, épinglé
besoin spécifique à votre organisation	module local ou registre privé
découverte d'un service cloud	module de registre, comme code de référence
infrastructure critique	registre épinglé, après lecture du code

Glissez pour voir

Lisez le code avant d'adopter

Un module populaire n'est pas un module adapté à votre contexte. Le dossier .terraform/modules/<nom>/ contient tout le dépôt : vérifiez les ressources créées, les valeurs par défaut de sécurité, et le nombre de providers qu'il tire. Un module qui crée dix ressources là où vous en attendiez deux est un incident en attente.

Dépannage

Symptôme	Cause probable	Correction
Unresolvable module version constraint	aucune version publiée ne satisfait la contrainte	le message donne la plus récente, ajuster
Invalid registry module source address	argument version sur une source locale	retirer version
Invalid module source address	chemin local sans préfixe ./ ou ../	ajouter le préfixe
invalid ref: "0.25.0//exports"	// placé après le ?ref=	remettre le sous-répertoire avant
Unknown module version	version référençant une variable sans const = true	ajouter const = true à la variable
Module not installed	init non joué, ou modules.json supprimé	terraform init
la version installée ne bouge pas	la copie installée satisfait encore la contrainte	terraform init -upgrade
Error downloading modules	réseau, proxy, ou dépôt privé	vérifier l'accès à registry.terraform.io, les clés SSH, le .netrc

Glissez pour voir

Mettre en pratique

Le lab module du registre remet trois projets et un seul module public. Il faut en épingler une version exacte, en laisser une souple, garder un troisième appel dans une fenêtre de correctifs, et adresser un sous-répertoire Git sur un tag. Les tests ne lisent aucun .tf : ils comparent les trois modules.json, la version_constraint du plan, et l'absence de fichier de verrouillage là où le projet ne déclare aucun provider. Il exige un accès réseau.

À retenir

• L'adresse namespace/name/provider se déduit du dépôt terraform-<PROVIDER>-<NAME>, elle ne s'invente pas.
• Un module de registre est téléchargé dans .terraform/modules/, et modules.json porte sa version résolue.
• L'argument version est facultatif : sans lui, la plus récente s'installe silencieusement.
• Le verrou ne suit que les providers : un projet sans provider n'en produit même pas.
• Sous contrainte souple, init conserve la copie installée ; -upgrade est le seul moyen de la faire bouger.
• Une CI part d'un cache vide et prend donc la plus récente admissible : seule une version exacte garantit l'identité.
• La résolution se fait par appel : deux appels du même module peuvent installer deux versions.
• Le sous-répertoire // appartient au paquet, et se place avant les arguments de requête.
• validate exige un init réussi : hors ligne, une configuration à module distant ne se valide pas.

FAQ : questions fréquentes

Les questions ci-dessous portent sur ce qui casse en pratique : la version qui ne bouge pas, le verrou qui ne verrouille rien, et l'adresse Git dont l'ordre est refusé.

L'argument version est-il obligatoire pour un module du Registry ?

Non, il est facultatif : sans lui, terraform init installe la version la plus récente publiée, sans avertissement. Comme le fichier de verrouillage ne suit pas les modules, la contrainte que vous écrivez est la seule chose qui rende l'installation reproductible.

Le fichier .terraform.lock.hcl verrouille-t-il les modules ?

Non, il ne suit que les providers. La documentation est explicite : Terraform ne mémorise aucune sélection de version pour les modules distants. Un projet dont la seule dépendance est un module de registre ne produit même aucun fichier de verrouillage.

Pourquoi mon module reste-t-il sur une ancienne version malgré ma contrainte ?

Parce que terraform init conserve la copie déjà installée tant qu'elle satisfait la contrainte, même si une version plus récente existe. Seul terraform init -upgrade réévalue la contrainte et télécharge la plus récente admissible.

Deux appels du même module peuvent-ils utiliser deux versions différentes ?

Oui, la résolution se fait par appel de module et non par projet. Deux blocs module visant la même source avec deux contraintes différentes installent deux versions, chacune dans son dossier du cache et sa propre entrée de modules.json.

Comment cibler un sous-répertoire d'un dépôt avec Terraform ?

Avec la notation // suivie du chemin interne. Sur une source Git portant des arguments comme ref, le sous-répertoire doit venir avant ces arguments, sinon Terraform interprète la fin de l'adresse comme un nom de révision et le téléchargement échoue.

Comment savoir quelle version de module tourne réellement ?

En lisant .terraform/modules/modules.json, qui porte la version résolue dans une clé Version absente des modules locaux. Le JSON du plan donne l'autre moitié de l'information, la contrainte écrite, sous module_calls.nom.version_constraint.

Pourquoi Terraform refuse-t-il l'argument version sur mon module ?

Parce que version ne s'applique qu'aux modules de registre. Sur une source locale, l'init s'arrête sur Invalid registry module source address ; sur une source Git, c'est l'argument ref qui fige la révision, et il accepte un tag, une branche ou un commit.

D'où vient le format namespace/name/provider d'un module ?

Du nom du dépôt publié. La règle de publication impose un nom en trois parties, terraform-PROVIDER-NAME, sur un dépôt GitHub public respectant la structure standard. Le dépôt cloudposse/terraform-null-label donne donc l'adresse cloudposse/label/null.

Pour aller plus loin

• Tester un module Terraform : valider un module avant de l'adopter, avec terraform test.
• Anti-patterns des modules : ce qui rend un module du registre impossible à monter de version.
• Bonnes pratiques des modules : les critères qui distinguent un module réutilisable d'un module jetable.
• Sources de modules : la référence officielle : toutes les formes de source, protocoles compris.
• Publier un module sur le registre : les conditions de nommage, de structure et de tags.
• Le fichier de verrouillage : ce qu'il suit, et ce qu'il ne suit pas.

×

📖 Voir la documentation →