Contraintes de version Terraform : encadrer Terraform, providers et modules

Les contraintes de version servent à définir quelles versions de Terraform, des providers et des modules sont acceptables pour votre configuration. Sans elles, vous laissez trop de place aux écarts entre postes de travail, pipelines CI et futures mises à jour. Avec elles, vous stabilisez le projet sans figer inutilement tout l’écosystème.

Cette page couvre les trois endroits où Terraform attend réellement des contraintes de version : required_version, required_providers et l’argument version d’un module issu du Registry.

Où écrire une contrainte de version

1. Version de Terraform lui-même

terraform {
  required_version = ">= 1.14.0"
}

Cette contrainte indique quelle version de Terraform Core peut interpréter la configuration.

2. Version des providers

terraform {
  required_providers {
    libvirt = {
      source  = "dmacvicar/libvirt"
      version = "~> 0.8"
    }
  }
}

Ici, vous encadrez le plugin qui dialogue avec l’infrastructure cible.

3. Version d’un module du Registry

module "network" {
  source  = "terraform-aws-modules/vpc/aws"
  version = "~> 5.0"

  name = "demo-vpc"
}

Pour un module distant, l’argument version évite qu’une future mise à jour majeure change le comportement sans contrôle.

Les opérateurs à connaître

Opérateur	Effet	Exemple
`=` ou rien	impose une version exacte	`= 1.14.3`
`!=`	exclut une version précise	`!= 5.10.0`
`>` `>=`	demande une version plus récente	`>= 1.14.0`
`<` `<=`	borne vers le bas	`< 2.0.0`
`~>`	autorise seulement l’incrément du composant le plus à droite	`~> 5.0`

Exemples utiles :

version = ">= 1.2.0, < 2.0.0"
version = "~> 5.0"
version = "~> 1.14.0"

Comment lire `~>` correctement

~> est souvent l’opérateur le plus utile, mais aussi l’un des plus mal compris.

~> 5.0 autorise 5.1, 5.9, 5.99, mais pas 6.0 ;
~> 5.0.2 autorise 5.0.3, 5.0.9, mais pas 5.1.0.

Autrement dit, seul le composant le plus à droite peut continuer à évoluer.

Bonnes pratiques selon le type de projet

La documentation officielle Terraform distingue bien deux cas.

Root module

Pour un projet réellement exécuté par votre équipe, il est raisonnable de poser une borne supérieure sur les providers :

terraform {
  required_version = ">= 1.14.0"

  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.0"
    }
  }
}

Vous gardez ainsi une plage maîtrisée, tout en laissant passer correctifs et évolutions compatibles.

Module réutilisable

Pour un module partagé, la recommandation officielle est plus souple : contraindre surtout le minimum compatible.

terraform {
  required_version = ">= 1.14.0"

  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = ">= 5.0.0"
    }
  }
}

L’objectif est de ne pas enfermer inutilement l’utilisateur du module dans une plage trop étroite.

Cas particulier des pré-releases

Si vous visez une version de pré-release, la documentation officielle indique qu’il faut utiliser une version exacte.

required_version = "= 1.15.0-beta1"

Les opérateurs >, >=, <, <= et ~> ne sélectionnent pas automatiquement les pré-releases.

Erreurs fréquentes

Utiliser une version exacte partout et rendre toute évolution inutilement coûteuse.
Ne poser aucune borne sur un provider dans un root module.
Employer ~> 1.0.0 alors que vous vouliez probablement ~> 1.0.
Oublier que la contrainte peut aussi s’appliquer aux modules distants du Registry.
Croire que le lock file suffit à documenter la politique de version du projet.

Que faire quand vous mettez à jour

Quand vous élargissez ou modifiez une contrainte, regénérez la résolution locale :

terraform init -upgrade

Ensuite, relisez le plan et le lock file avant de commiter.

À retenir

Les contraintes de version existent pour Terraform Core, les providers et les modules distants.
~> est souvent le meilleur compromis pour un root module.
Un module réutilisable doit en général rester plus souple et contraindre surtout le minimum compatible.
Le lock file complète les contraintes, il ne les remplace pas.
Les pré-releases demandent une version exacte.

Prochaines étapes

Les providers Terraform À lire si vous voulez relier ces contraintes de version au téléchargement réel des providers

Structure d'un projet Terraform Pour voir où placer versions.tf, providers.tf et le reste du projet

Style guide Terraform Pour garder un projet lisible quand les fichiers et les contraintes commencent à se multiplier