Backends Terraform : configuration partielle, -backend-config et migration

Par défaut, Terraform stocke le state dans un fichier local (terraform.tfstate). C'est suffisant pour apprendre, mais en équipe on le déplace vers un backend distant (S3, GCS, HCP…) pour partager le state et le verrouiller. Le vrai sujet n'est pas « choisir un backend », c'est comment le configurer proprement : le bloc backend a une contrainte surprenante, et la migration a des pièges qui coûtent cher.

Les comportements mesurables de ce guide (messages d'init, résolution de la configuration partielle, préservation du lineage) ont été rejoués sur Terraform v1.15.4. Les arguments propres au backend S3 (use_lockfile, skip_s3_checksum) reposent sur la doc officielle.

Ce que vous allez apprendre

• Pourquoi le bloc backend n'accepte ni variable ni local
• La configuration partielle et -backend-config, un fichier par environnement
• La migration du state : -migrate-state contre -reconfigure
• Le verrouillage S3, opt-in, et la dépréciation de DynamoDB
• Le diagnostic : .terraform/terraform.tfstate, et où fuitent les secrets

Le bloc backend n'accepte aucune valeur nommée

C'est le piège central, et la doc est nette : « A backend block cannot refer to named values (like input variables, locals, or data source attributes). » Le bloc est lu très tôt, avant l'évaluation des variables. Vérifié sur 1.15.4, ceci échoue :

terraform {
  backend "local" {
    path = var.chemin # Error: Variables not allowed
  }
}

On ne peut donc pas paramétrer un backend par des variables. C'est la raison d'être de la configuration partielle.

Aucune règle d'ordre

Contrairement à une idée répandue, le bloc backend n'a pas à se placer avant required_providers. HCL est insensible à l'ordre des blocs. La seule contrainte réelle : « A configuration can only provide one backend block. »

La configuration partielle et -backend-config

On laisse le bloc incomplet et on fournit le reste à l'init :

terraform {
  backend "local" {} # partiel : aucune valeur ici
}

Trois formes de -backend-config existent : un fichier (nommage recommandé *.<backend>.tfbackend), une paire KEY=VALUE, ou la saisie interactive :

terraform init -backend-config=dev.local.tfbackend
terraform init -backend-config="path=etat/dev/terraform.tfstate"

Un fichier par environnement (dev, prod…) alimente le même bloc sans jamais coder le chemin en dur. Sans ce mécanisme, un même dossier ne peut pas servir deux environnements. Réinitialisé sans -backend-config, un bloc partiel résout ses valeurs à null : c'est la preuve qu'il est bien partiel.

-backend-config écrase en silence

Si vous laissez une valeur codée en dur dans le bloc et passez un -backend-config différent, la valeur de la ligne de commande l'emporte, sans avertissement. Le seul moyen de connaître la valeur effective est de relire .terraform/terraform.tfstate.

Le fichier .terraform/terraform.tfstate : votre diagnostic

Terraform enregistre le backend réellement retenu dans .terraform/terraform.tfstate : backend.type, la backend.config résolue et un hash. Ce n'est pas le state lui-même.

jq '.backend | {type, path: .config.path}' .terraform/terraform.tfstate

C'est l'outil de diagnostic numéro un d'un problème de backend, et le seul moyen de voir ce que -backend-config a produit. À noter : il n'existe pas tant que le backend est le local implicite.

La config résolue fuite en clair

La doc prévient : « Terraform will include these values in both the .terraform subdirectory and in plan files. » La backend.config résolue (identifiants d'accès compris) est stockée en clair dans .terraform/ et dans un fichier de plan -out. C'est pourquoi les identifiants passent par des variables d'environnement, jamais par le HCL ni un fichier -backend-config commité.

Migrer le state : -migrate-state contre -reconfigure

Quand la configuration du backend change, un terraform init nu refuse de tourner. Vérifié sur 1.15.4, message exact :

Error: Backend configuration changed

Either -reconfigure or -migrate-state must be supplied to update the backend
configuration.

Il n'y a donc aucun risque de perte silencieuse : c'est un arrêt franc qui vous force à choisir, en connaissance de cause, entre deux comportements opposés :

Option	Ce qu'elle fait	Quand
-migrate-state	copie le state existant vers le nouveau backend	déplacer un projet vivant
-reconfigure	ignore le state de l'ancien backend, repart de zéro	changer sans rien emporter

Glissez pour voir

Une migration réussie conserve le lineage du state : c'est la preuve d'une copie, pas d'un apply neuf (qui fabriquerait un lineage différent). Se tromper d'option est une source classique de state perdu.

Pour une migration non interactive (en CI, objectif 3c), ajoutez -force-copy, qui répond « yes » à la place de l'opérateur :

terraform init -migrate-state -force-copy -backend-config=dev.local.tfbackend

Retirer le bloc backend est aussi un changement

Après un « no » à une migration, retirer le bloc backend ne remet pas les choses en place : c'est encore un changement de backend, et init renvoie le même Backend configuration changed. Il faut poser -reconfigure (revenir au local sans rien emporter) ou -migrate-state (rapatrier), sciemment.

Le verrouillage : opt-in sur S3, DynamoDB déprécié

Un backend distant peut verrouiller le state pour éviter deux écritures simultanées, mais ce n'est pas automatique partout. Sur le backend S3, « State locking is an opt-in feature » : use_lockfile vaut false par défaut. Une configuration S3 sans use_lockfile = true n'a donc aucun verrou, malgré ce qu'on croit souvent.

L'ancien mécanisme par DynamoDB (dynamodb_table) est désormais déprécié : « DynamoDB-based locking is deprecated and will be removed in a future minor version. » Le chemin actuel est use_lockfile = true (verrou par fichier .tflock dans le bucket).

Backends S3-compatibles (MinIO, Ceph…)

Le backend s3 fonctionne avec des stockages compatibles, mais « Support for S3 Compatible storage providers is offered as best effort ». Deux points utiles :

• skip_s3_checksum = true est destiné aux implémentations non AWS (« Useful for some S3-Compatible APIs »), avec les autres skip_*.
• region est obligatoire, mais peut venir de l'environnement (AWS_REGION) comme les identifiants ; un serveur compatible l'accepte quelle qu'elle soit.

Mettre en pratique

Le lab backends fait passer un projet du backend local implicite à un backend local paramétré : bloc partiel, -backend-config par environnement, et migration prouvée par la préservation du lineage. Il se joue hors ligne, sans compte cloud.

À retenir

• Le bloc backend n'accepte aucune valeur nommée : d'où la configuration partielle et -backend-config, un fichier par environnement.
• Un init après changement de backend refuse : il faut choisir entre -migrate-state (copie) et -reconfigure (abandonne).
• Une migration réussie conserve le lineage ; -force-copy la rend non interactive.
• Le verrou S3 est opt-in (use_lockfile = true) ; DynamoDB est déprécié.
• .terraform/terraform.tfstate porte la config résolue (et la fuite en clair) : c'est votre diagnostic.

FAQ : questions fréquentes

Les questions ci-dessous portent sur les pièges du backend : la variable qu'on ne peut pas utiliser, le choix entre migrer et reconfigurer, et le verrou qu'on croit actif. Chaque réponse donne la vérification correspondante.

Peut-on utiliser une variable dans le bloc backend ?

Non. Le bloc backend n'accepte aucune valeur nommee : ni variable, ni local, ni attribut de data source. Un path = var.chemin fait echouer init sur Error: Variables not allowed. C'est pour cela qu'existe la configuration partielle, alimentee par -backend-config.

Comment un même projet sert-il dev et prod ?

Avec la configuration partielle : un bloc backend vide, puis un fichier -backend-config par environnement (dev.local.tfbackend, prod.local.tfbackend), nommes *.backend.tfbackend. terraform init -backend-config=dev... alimente le meme bloc sans coder le chemin en dur.

Quelle différence entre -migrate-state et -reconfigure ?

-migrate-state COPIE le state existant vers le nouveau backend, en conservant son lineage. -reconfigure IGNORE le state de l'ancien backend et repart de zero. Se tromper d'option est une source classique de state perdu : migrate pour deplacer, reconfigure pour repartir a neuf.

Pourquoi terraform init refuse après un changement de backend ?

Parce que Terraform refuse de deviner : Error: Backend configuration changed, Either -reconfigure or -migrate-state must be supplied. C'est un arret franc, sans perte silencieuse, qui force a choisir entre copier le state (migrate) ou l'abandonner (reconfigure).

Ma configuration S3 verrouille-t-elle le state ?

Pas par defaut. Sur le backend S3, le verrouillage est opt-in : use_lockfile vaut false par defaut. Une config S3 sans use_lockfile = true n'a aucun verrou. L'ancien mecanisme DynamoDB (dynamodb_table) est deprecie et sera retire ; le chemin actuel est use_lockfile = true.

Où voir le backend réellement configuré ?

Dans .terraform/terraform.tfstate, ecrit a l'init : il contient backend.type, la backend.config resolue et un hash. C'est le seul moyen de savoir ce que -backend-config a produit. Il n'existe pas tant que le backend reste le local implicite. La config resolue y est en clair.

Comment migrer un state en CI sans interaction ?

En ajoutant -force-copy a la migration : terraform init -migrate-state -force-copy -backend-config=dev... Ce flag repond yes a la place de l'operateur, ce qui permet de migrer depuis un pipeline sans saisie interactive, tout en conservant le lineage du state.

Pour aller plus loin

• terraform state mv : deplacer une ressource dans le state sans la detruire.
• Sauvegarder et restaurer le state Terraform : ce qui reste quand un backend distant est perdu.
• Variables par environnement : le pendant applicatif du -backend-config par environnement.
• Backends : la reference officielle : la liste complete des arguments du backend S3.
• Backend pg : le backend PostgreSQL, et pourquoi il refuse force-unlock.

×

📖 Voir la documentation →