Providers Terraform : source explicite, alias et modules

Un provider est le plugin qui traduit vos ressources en appels d'API. On le déclare dans required_providers, on le configure dans un bloc provider, et tout semble simple, jusqu'à ce qu'un module s'en mêle. Deux confusions dominent : l'adresse source (le préfixe hashicorp/ implicite est en réalité déconseillé) et la différence entre nom local et alias.

Ce guide traite l'adresse source complète, le nom local face à l'alias, les contraintes de version selon le contexte, la place des providers dans un module, et la preuve par le plan JSON. Les comportements ont été vérifiés sur Terraform v1.15.4.

Ce que vous allez apprendre

• L'adresse source complète, et pourquoi l'implicite est déconseillé
• La différence entre nom local et alias
• Les contraintes de version selon le contexte (racine ou module)
• Pourquoi un module réutilisable ne contient pas de bloc provider
• configuration_aliases, providers = {}, et la preuve par le plan JSON

Prérequis

• Un projet Terraform initialisé (installer Terraform)
• Les contraintes de version (version constraints)

L'adresse source : toujours explicite

Depuis Terraform 0.13, source est requis dans required_providers. On lit souvent qu'il est « implicite » pour les providers HashiCorp : c'est vrai techniquement, mais la doc le classe comme une rétro-compatibilité et recommande l'inverse : « use explicit source addresses for all providers ».

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

L'adresse complète est [HOSTNAME/]NAMESPACE/TYPE. hashicorp/aws est en fait registry.terraform.io/hashicorp/aws : le hostname, souvent omis, est la porte d'entrée des registres privés et des miroirs. L'omettre revient à câbler le registre public par défaut.

Nom local et alias : deux notions distinctes

C'est la confusion la plus fréquente, et le guide d'origine la mélangeait. Ce sont deux mécanismes différents :

• Le nom local (la clé dans required_providers) identifie le provider dans le module. C'est lui qui rattache un type de ressource à un provider, par son préfixe : aws_instance va au provider de nom local aws. Un nom local différent du type impose un provider = <nom_local> sur chaque ressource.
• L'alias crée une configuration supplémentaire du même provider, pour cibler par exemple deux régions.

provider "aws" {
  region = "eu-west-3"
}

provider "aws" {
  alias  = "us"
  region = "us-east-1"
}

resource "aws_instance" "paris" {
  # provider par defaut
}

resource "aws_instance" "virginie" {
  provider = aws.us
}

Le plan JSON le confirme : configuration.provider_config liste chaque configuration avec son full_name, son alias éventuel, et chaque ressource porte un provider_config_key (aws ou aws.us).

version dans un bloc provider : déprécié

Poser un argument version dans un bloc provider {} est déprécié : « The version argument in provider configurations is deprecated, and Terraform will remove it in a future version. » La contrainte de version va dans required_providers, pas dans la configuration.

Les contraintes de version dépendent du contexte

Une même règle ne vaut pas partout, et c'est un point d'examen :

• Module racine : bornez haut et bas, typiquement ~> 5.0, « to avoid accidental upgrades to incompatible new versions ».
• Module réutilisable : ne contraignez que le minimum, et n'utilisez pas ~> : « reusable modules should constrain only their minimum allowed versions », sans quoi le module « forces users to update many modules simultaneously ».

Terraform ne fait pas correspondre les pré-releases aux opérateurs de plage, et un bloc provider {} n'accepte que des valeurs connues avant l'apply : jamais un attribut calculé d'une ressource.

Les providers et les modules

Voici le cœur du sujet, et ce que l'examen interroge. Un module destiné à être appelé ne doit contenir aucun bloc provider : « A module intended to be called by one or more other modules must not contain any provider blocks. » La configuration du provider vit dans le module racine, et traverse la frontière.

Trois mécanismes gouvernent ce passage :

• L'héritage implicite : un module enfant hérite des configurations par défaut du parent, mais pas des exigences de source et de version, que chaque module doit redéclarer dans son propre required_providers.
• configuration_aliases : dans son required_providers, un module enfant déclare qu'il attend une configuration aliasée (configuration_aliases = [aws.us]).
• providers = { ... } : le meta-argument du bloc module passe une configuration (aliasée ou non) au module enfant.

module "reseau" {
  source = "./modules/reseau"
  providers = {
    aws = aws.us
  }
}

Un provider hérité casse count et for_each

Si un module hérite d'un bloc provider (au lieu de le recevoir explicitement), il devient incompatible avec count, for_each et depends_on sur ce module, et la destruction propre devient impossible, car la configuration du provider doit survivre aux ressources qu'elle gère. D'où la règle : pas de bloc provider dans un module appelé.

Diagnostic : le schéma et la sélection

Deux outils machine, souvent ignorés :

• terraform providers schema -json décrit le schéma complet de chaque provider (attributs, types, write_only) : c'est l'outil de référence quand un argument semble manquant.
• terraform version -json expose provider_selections, l'adresse complète vers la version réellement retenue :

terraform version -json | jq '.provider_selections'

Pour la CI, terraform init -lockfile=readonly vérifie les empreintes du lock sans le réécrire ; il est incompatible avec -upgrade.

Dépannage

Ces symptômes touchent à la source, à l'alias ou aux modules.

Symptôme	Cause	Solution
Une ressource va au mauvais provider	Son préfixe ne correspond pas au nom local attendu	Poser provider = <nom_local> sur la ressource
provider configuration not present	Un module attend une config aliasée non passée	La passer via providers = { aws = aws.us }
provider blocks are not allowed (module)	Un bloc provider dans un module appelé	Le remonter au module racine, passer par providers
Avertissement de dépréciation sur version	version dans un bloc provider {}	Déplacer la contrainte dans required_providers
count/for_each refusés sur un module	Le module hérite d'un bloc provider	Passer la config explicitement, sans bloc dans l'enfant

Glissez pour voir

À retenir

1. source est requis et doit être explicite ; l'adresse est [HOSTNAME/]NAMESPACE/TYPE.
2. Nom local ≠ alias : le nom local rattache les ressources, l'alias ajoute une configuration du même provider.
3. La contrainte va dans required_providers, pas dans provider {} (où version est déprécié).
4. Module racine : borné (~> 5.0). Module réutilisable : minimum seul, pas de ~>.
5. Un module appelé ne contient aucun bloc provider ; il hérite des configs par défaut, redéclare source/version, et reçoit les alias par configuration_aliases + providers = {}.
6. Un provider hérité casse count/for_each/depends_on.
7. version -json et providers schema -json sont les preuves machine.

FAQ : questions fréquentes

Les questions ci-dessous reprennent les confusions les plus fréquentes sur les providers : l'adresse source, la différence nom local / alias, et les providers dans les modules.

Faut-il toujours écrire le source complet d'un provider Terraform ?

Oui, c'est recommandé. source est requis depuis Terraform 0.13, et l'omission du préfixe hashicorp/ n'est qu'une rétro-compatibilité. La doc recommande d'utiliser des adresses source explicites pour tous les providers. L'adresse complète est HOSTNAME/NAMESPACE/TYPE.

Quelle différence entre nom local et alias d'un provider Terraform ?

Le nom local, clé dans required_providers, identifie le provider dans le module et rattache les ressources par leur préfixe ; un nom local différent du type impose provider= sur chaque ressource. L'alias crée une configuration supplémentaire du même provider, par exemple pour deux régions.

Un module Terraform peut-il contenir un bloc provider ?

Non pour un module réutilisable : la doc est explicite, un module destiné à être appelé ne doit contenir aucun bloc provider. La configuration vit dans le module racine. Un module qui hérite d'un bloc provider devient de plus incompatible avec count, for_each et depends_on.

Comment passer un provider aliasé à un module enfant en Terraform ?

Le module enfant déclare qu'il attend une config aliasée avec configuration_aliases dans son required_providers, et le module appelant la passe avec le meta-argument providers du bloc module. Un module enfant hérite des configs par défaut du parent, mais pas des exigences de source et version.

Peut-on mettre l'argument version dans un bloc provider Terraform ?

C'est déprécié. La doc indique que l'argument version dans une configuration de provider est déprécié et sera retiré. La contrainte de version va dans required_providers, pas dans le bloc provider. Un bloc provider n'accepte par ailleurs que des valeurs connues avant l'apply.

Quelle contrainte de version mettre selon qu'on écrit un module racine ou réutilisable ?

Dans un module racine, bornez haut et bas, typiquement ~> 5.0, pour éviter les montées incompatibles. Dans un module réutilisable, ne contraignez que le minimum et n'utilisez pas ~>, sinon le module force ses utilisateurs à mettre à jour plusieurs modules en même temps.

Comment prouver quel provider une ressource Terraform utilise ?

Avec le plan JSON : configuration.provider_config liste chaque configuration avec son full_name et son alias, et chaque ressource porte un provider_config_key. terraform version -json expose aussi provider_selections, l'adresse complète vers la version retenue de chaque provider.

Pour aller plus loin

• Les data sources Terraform : La lecture d'objets existants par le provider que vous venez de configurer.
• Fonctions définies par les providers : Les fonctions livrées par le provider lui-même, en plus des fonctions du langage.
• Contraintes de version Terraform : Les opérateurs et le lock file qui stabilisent la version de chaque provider.

×

📖 Voir la documentation →