Utiliser un module du Terraform Registry

Le Terraform Registry est le catalogue officiel de modules prêts à l’emploi. Au lieu de tout écrire vous-même, vous pouvez réutiliser un module créé et maintenu par la communauté ou par un éditeur. Il suffit de référencer son nom et sa version dans un bloc module pour que terraform init le télécharge automatiquement.

Prérequis : avoir lu Créer un module Terraform et Utiliser un module local.

Ce que vous allez apprendre

• Trouver un module sur le Terraform Registry
• Référencer un module public avec la syntaxe source et version
• Utiliser un sous-module avec la notation //
• Comprendre ce que terraform init télécharge concrètement
• Comparer les différentes sources de modules

Le Terraform Registry

Le Terraform Registry est accessible à l’adresse registry.terraform.io. Il héberge deux types de contenus :

• Providers : les plugins qui permettent à Terraform de communiquer avec une API (AWS, Azure, libvirt…)
• Modules : des blocs de code réutilisables qui assemblent des ressources

Chaque module du Registry possède une page avec :

• Les inputs (variables) et leurs types
• Les outputs disponibles
• Un README avec des exemples d’utilisation
• Les versions publiées et leur changelog
• Les dépendances (providers requis)

Syntaxe d’un module du Registry

La source

Un module du Registry se référence avec le format namespace/name/provider :

module "iam_account" {
  source  = "terraform-aws-modules/iam/aws"
  version = "5.52.2"
  # ↑         ↑                    ↑    ↑
  # |         namespace            name  provider
  # argument version (fortement recommandé pour figer le comportement)
}

Composant	Rôle	Exemple
namespace	Organisation ou auteur	terraform-aws-modules
name	Nom du module	iam
provider	Provider principal	aws

Glissez pour voir

L’argument version

Pour un module du Registry, l’argument version n’est pas techniquement obligatoire, mais il est fortement recommandé. Si vous l’omettez, Terraform résout la version disponible au moment du init, ce qui rend les mises à jour moins prévisibles. Terraform supporte les contraintes de version :

module "vpc" {
  source  = "terraform-aws-modules/vpc/aws"
  version = "5.21.0"
  # ↑ version exacte recommandée
}

module "vpc_flexible" {
  source  = "terraform-aws-modules/vpc/aws"
  version = "~> 5.0"
  # ↑ accepte 5.x.x mais pas 6.0.0
}

Contrainte	Signification
"5.21.0"	Version exacte uniquement
"~> 5.0"	>= 5.0 et < 6.0
"~> 5.21.0"	>= 5.21.0 et < 5.22.0 (patchs uniquement)
">= 5.0, < 6.0"	Plage explicite

Glissez pour voir

Toujours épingler une version

Sans contrainte de version, terraform init résoudra la version disponible au moment de l’initialisation. Cela peut introduire des changements non prévus dans un projet déjà stable. En pratique, écrivez toujours version = "X.Y.Z", version = "~> X.Y" ou version = "~> X.Y.Z" selon le niveau de souplesse souhaité.

Sous-modules avec //

Les modules du Registry contiennent souvent des sous-modules dans un dossier modules/. La notation // permet de cibler un sous-module spécifique :

module "iam_account" {
  source  = "terraform-aws-modules/iam/aws//modules/iam-account"
  version = "5.52.2"
  # ↑ le module principal est "iam"
  #   le sous-module ciblé est "modules/iam-account"
}

La partie avant // identifie le module du Registry. La partie après // est le chemin relatif vers le sous-module à l’intérieur du dépôt.

Ce que terraform init télécharge

Lors de l’initialisation, Terraform affiche clairement le téléchargement :

$ terraform init

Initializing modules...
Downloading registry.terraform.io/terraform-aws-modules/iam/aws 5.52.2 for iam_account...
- iam_account in .terraform/modules/iam_account/modules/iam-account

Le module est stocké dans .terraform/modules/. Le fichier .terraform/modules/modules.json enregistre la correspondance :

{
  "Modules": [
    {
      "Key": "iam_account",
      "Source": "registry.terraform.io/terraform-aws-modules/iam/aws//modules/iam-account",
      "Version": "5.52.2",
      "Dir": ".terraform/modules/iam_account/modules/iam-account"
    }
  ]
}

Le contenu téléchargé est un module Terraform classique — les mêmes fichiers qu’un module local :

.terraform/modules/iam_account/modules/iam-account/
├── main.tf
├── outputs.tf
├── README.md
├── variables.tf
└── versions.tf

Transparence

Un module du Registry n’a rien de magique. C’est un dépôt Git publié sur le Registry. terraform init le télécharge et le place dans .terraform/modules/. Ensuite, Terraform le traite exactement comme un module local.

Registry vs Git

L’argument version fonctionne pour les modules du Registry. Pour une source Git, on fige la révision avec ?ref= et cette valeur peut être un tag, une branche ou un commit SHA.

Exemple complet

Voici un exemple complet qui utilise un module du Registry pour configurer une politique de mots de passe AWS :

versions.tf

terraform {
  required_version = ">= 1.11.0"
}

main.tf

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

  account_alias = "mon-compte-demo"

  minimum_password_length      = 14
  require_numbers              = true
  require_symbols              = true
  require_lowercase_characters = true
  require_uppercase_characters = true
}

Le terraform validate confirme la validité de cette configuration — même sans credentials AWS, la syntaxe est vérifiée :

$ terraform validate
Success! The configuration is valid.

Les différentes sources de modules

Le bloc source accepte plusieurs formats selon l’origine du module :

Source	Format source	version	Téléchargement
Local	"./modules/reseau"	Non supporté	Lecture directe sur disque
Registry public	"namespace/name/provider"	Obligatoire	registry.terraform.io
Registry privé	"app.terraform.io/org/name/provider"	Obligatoire	Terraform Cloud/Enterprise
GitHub	"github.com/org/repo//modules/X"	Non (utiliser ref)	Clone Git
Git générique	"git::https://example.com/repo.git"	Non (utiliser ref)	Clone Git
S3	"s3::https://bucket/module.zip"	Non	Téléchargement HTTP

Glissez pour voir

Les modules locaux et du Registry public couvrent la grande majorité des cas d’usage.

Quand utiliser un module du Registry

Situation	Recommandation
Infrastructure standard (VPC, IAM, S3…)	Module du Registry — gain de temps considérable
Besoin très spécifique à votre entreprise	Module local ou privé
Apprentissage d’un service cloud	Module du Registry — code de référence
Infrastructure critique en production	Module du Registry épinglé + revue du code source

Glissez pour voir

Lire le code avant d'utiliser

Avant d’adopter un module du Registry en production, lisez son code source. Un module populaire avec beaucoup de stars GitHub n’est pas forcément adapté à votre contexte. Vérifiez qu’il ne crée pas de ressources inattendues et que les defaults correspondent à vos besoins de sécurité.

Dépannage

Symptôme	Cause probable	Solution
Module not found	Nom du module incorrect	Vérifier le format namespace/name/provider sur le Registry
version ... does not match	Contrainte de version incompatible	Consulter les versions disponibles sur la page du module
Error downloading modules	Problème réseau ou proxy	Vérifier la connectivité à registry.terraform.io
Could not download module avec Registry privé	Token manquant	Configurer credentials dans ~/.terraformrc
Module téléchargé mais terraform plan échoue	Variables obligatoires non fournies	Lire les Inputs sur la page du module

Glissez pour voir

À retenir

1. Le Terraform Registry héberge des modules réutilisables créés par la communauté
2. La source suit le format namespace/name/provider avec une version obligatoire
3. La notation // cible un sous-module dans un dépôt multi-modules
4. terraform init télécharge le module dans .terraform/modules/
5. Un module du Registry a la même structure qu’un module local (main.tf, variables.tf, outputs.tf)
6. Épinglez toujours la version pour éviter les mises à jour surprises

Prochaines étapes

Versionner ses modules

Tester un module

Bonnes pratiques modules

×

📖 Voir la documentation →