Terraform AWS, Backend S3 et terraform_remote_state

Mettre son state dans un bucket S3 règle le partage entre opérateurs. Mais deux points décident de la suite, et tous deux se mesurent : le verrouillage n'est pas actif par défaut, et le bloc backend refuse toute valeur nommée, ce qui impose la configuration partielle.

Tout ce qui suit a été exécuté sur Terraform v1.15.4, contre un émulateur S3 local, sans mobiliser le moindre compte AWS. Deux idées répandues n'y survivent pas, celle du backend "s3" qui verrouillerait de lui-même, et celle du terraform.tfstate local qu'il faudrait nettoyer après migration.

Ce que vous allez apprendre

• Créer le bucket de state, dans un bootstrap séparé
• Pourquoi un bloc backend n'accepte aucune variable, et quoi faire à la place
• Activer un verrou réellement effectif, et le prouver
• Vérifier quelle configuration Terraform a retenue, sans la deviner
• Partager des outputs entre deux configurations, et ce que cela coûte

Prérequis

• Terraform 1.11 ou plus récent (installer Terraform). Le verrouillage S3 natif est arrivé en 1.10 ; les mesures viennent de 1.15.4.
• Un accès S3, réel ou émulé. Aucune des mesures de cette page n'a demandé de compte AWS.

Le bucket d'abord, dans un bootstrap séparé

Le backend doit exister avant d'être utilisé : la configuration qui crée le bucket ne peut pas y ranger son propre state. On la garde donc à part, avec un state local assumé.

resource "aws_s3_bucket" "state" {
  bucket = "mon-org-terraform-state"
}

resource "aws_s3_bucket_versioning" "state" {
  bucket = aws_s3_bucket.state.id

  versioning_configuration {
    status = "Enabled"
  }
}

resource "aws_s3_bucket_public_access_block" "state" {
  bucket = aws_s3_bucket.state.id

  block_public_acls       = true
  block_public_policy     = true
  ignore_public_acls      = true
  restrict_public_buckets = true
}

Le versioning n'est pas décoratif : c'est lui qui permet de revenir à une version antérieure du state après une opération malheureuse.

Le bloc backend n'accepte aucune variable

C'est la contrainte qui commande tout le reste, et elle surprend parce qu'elle contredit le reste du HCL. Mesuré :

terraform {
  backend "s3" {
    bucket = var.backend_bucket
  }
}

Error: Variables not allowed

  on main.tf line 8, in terraform:
   8:     bucket = var.backend_bucket

Variables may not be used here.

L'init sort en 1. La documentation l'énonce : « A backend block cannot refer to named values (like input variables, locals, or data source attributes). » Le backend est lu avant l'évaluation des variables, il ne peut donc rien en connaître.

La configuration partielle, en fichier

La réponse officielle est de laisser le bloc incomplet et de fournir le reste à l'init. La forme fichier vaut mieux que KEY=VALUE, que la documentation déconseille pour un secret puisque l'historique du shell le conserve. Le nommage recommandé est *.<backend>.tfbackend :

terraform {
  backend "s3" {}
}

prod.s3.tfbackend

bucket = "mon-org-terraform-state"
key    = "producer/terraform.tfstate"
region = "eu-west-3"

use_lockfile = true
encrypt      = true

terraform init -backend-config=prod.s3.tfbackend

Un même dossier sert alors plusieurs environnements, en ne changeant que le fichier passé à l'init.

Vérifier ce que Terraform a retenu

Ne le devinez pas : Terraform l'écrit. Le fichier .terraform/terraform.tfstate porte la configuration de backend résolue, et c'est la seule preuve fiable.

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

Mesuré, avec un endpoint personnalisé :

{
  "type": "s3",
  "config": {
    "bucket": "tf-state-sonde",
    "key": "producer/terraform.tfstate",
    "region": "eu-west-3",
    "use_path_style": true,
    "use_lockfile": true,
    "endpoints": { "s3": "http://localhost:4566" }
  }
}

Un aws s3 ls prouverait qu'un objet existe ; il ne dit pas quelle configuration Terraform a réellement retenue.

Ce fichier n'est pas un coffre

La documentation prévient : « Terraform will include these values in both the .terraform subdirectory and in plan files. » Mesuré, la configuration y figure entièrement résolue, access_key et secret_key compris si vous les passez ainsi. La configuration partielle protège le dépôt, pas le disque : les identifiants passent par des variables d'environnement.

Le verrouillage est un opt-in strict

Voici le point le plus important de cette page. Déclarer un backend "s3" ne verrouille rien. L'argument est use_lockfile, et il vaut false par défaut. Terraform dépose alors un objet <clé>.tflock à côté du state, par écriture conditionnelle.

La démonstration tient en deux essais. On dépose à la main un .tflock dans le bucket, puis on planifie.

Avec use_lockfile = true :

terraform plan -lock-timeout=0s

Error: Error acquiring the state lock

Error message: operation error S3: PutObject, https response error

Code 1. Sans l'argument, et avec le même objet toujours présent :

random_pet.nom: Refreshing state...

Code 0. Le verrou est donc purement ignoré, et deux applies concurrents se marchent dessus en silence.

DynamoDB n'est plus la réponse

Le verrouillage par table DynamoDB est déprécié et sera retiré. Le verrouillage natif S3 est arrivé en Terraform 1.10. Sur un projet neuf, use_lockfile = true suffit, sans table annexe à provisionner.

Partager des outputs entre configurations

Une fois le state distant en place, une autre configuration peut en lire les outputs racine :

data "terraform_remote_state" "producer" {
  backend = "s3"

  config = {
    bucket = "mon-org-terraform-state"
    key    = "producer/terraform.tfstate"
    region = "eu-west-3"
  }
}

output "nom_amont" {
  value = data.terraform_remote_state.producer.outputs.nom
}

Mesuré : le mécanisme est intégré, servi par terraform.io/builtin/terraform, et la valeur suit l'amont. Après avoir changé une entrée du producer puis l'avoir réappliqué, le consumer rejoué est passé de relaxed-pony à notable-lemur. Une valeur recopiée à la main, elle, serait restée figée.

Les pièges mesurés

Il n'y a pas de state local à nettoyer

Beaucoup de guides font suivre la migration d'un rm -rf .terraform terraform.tfstate terraform.tfstate.backup. Mesuré, une fois le backend S3 initialisé, le répertoire ne contient aucun terraform.tfstate local : cette commande est un rm à vide, et elle entretient l'idée fausse qu'une copie subsisterait.

fichiers terraform.tfstate* dans producer/ : AUCUN
objets dans le bucket : ['producer/terraform.tfstate']

defaults ne rattrape pas un état absent

L'argument defaults de terraform_remote_state fournit une valeur de repli « in case the state file is empty or lacks a required output ». La nuance est importante, et elle se mesure : sur un état qui existe mais auquel il manque l'output, le repli joue. Sur une clé inexistante, il ne sauve rien :

Error: Unable to find remote state

No stored state was found for the given workspace in the given backend.

Code 1. defaults gère donc une interface incomplète, pas une stack absente : la parade au « l'amont n'a pas encore été appliqué » reste d'appliquer l'amont.

Les permissions ne sont pas celles qu'on croit

La liste officielle commence par s3:ListBucket sur le bucket, « at a minimum, this must be able to list the path where the state is stored ». S'ajoutent ensuite s3:GetObject et s3:PutObject sur l'objet de state.

Le contre-pied est net : s3:DeleteObject n'est pas requis sur le fichier de state, « as Terraform does not delete it », puisqu'il l'écrase. Il l'est en revanche sur l'objet .tflock, qu'il faut bien pouvoir retirer.

Publier un output, c'est publier tout l'état

La documentation ne recommande pas, elle interdit : « Don't use terraform_remote_state if any of the resources in your configuration work with data that you consider sensitive. » La raison est que lire les outputs suppose un accès complet au snapshot d'état.

Elle ouvre d'ailleurs sa page par une alternative : « We recommend using the tfe_outputs data source […] more secure because it does not require full access to workspace state to fetch outputs. » À défaut, un magasin de paramètres dédié joue le même rôle, en ne publiant que la valeur voulue.

Hors d'AWS, tout repose sur quelques arguments

Faire fonctionner ce backend contre MinIO, Ceph ou un émulateur demande un jeu d'arguments précis : le bloc endpoints (dont endpoints.s3), use_path_style, puis skip_credentials_validation, skip_requesting_account_id, skip_metadata_api_check, skip_region_validation et skip_s3_checksum. C'est exactement ce jeu qui a permis toutes les mesures de cette page.

Le S3 compatible n'est pas garanti

« Support for S3 Compatible storage providers is offered as best effort. HashiCorp only tests the s3 backend against Amazon S3. » Un émulateur convient parfaitement pour apprendre et pour tester ; il n'engage personne en production.

Dépannage

Symptôme	Cause probable	Correction
Error: Variables not allowed	une variable dans le bloc backend	configuration partielle plus -backend-config
deux applies concurrents s'écrasent	use_lockfile absent : le verrou est un opt-in	l'ajouter, puis le prouver avec un .tflock déposé
Error acquiring the state lock	un verrou est détenu, ou orphelin	-lock-timeout en CI ; sinon retirer l'objet .tflock
Error: Backend configuration changed	backend modifié sans réinitialiser	init -migrate-state pour emporter l'état, -reconfigure pour l'abandonner
Unable to find remote state	la stack amont n'a pas été appliquée	l'appliquer ; defaults ne couvre pas ce cas
un identifiant traîne dans .terraform/	passé via -backend-config	le passer par variables d'environnement
le backend ne répond pas hors AWS	endpoints, use_path_style ou un skip_* manquant	compléter le jeu d'arguments S3 compatible

Glissez pour voir

Mettre en pratique

Le lab un state distant, verrouillé, et lu par une autre stack monte un bucket sur un émulateur local, puis fait réparer un backend "s3" piégé : il déclare bucket = var.backend_bucket et n'a aucun argument de verrouillage. Les tests déposent eux-mêmes un .tflock et exigent que le plan échoue, puis le retirent et exigent qu'il passe : une configuration sans use_lockfile tombe donc précisément là où l'énoncé l'interdit. Il se joue hors ligne, sans compte AWS.

À retenir

• Le bucket de state se crée dans un bootstrap séparé, au state local assumé.
• Un bloc backend n'accepte aucune valeur nommée : Error: Variables not allowed, code 1.
• La configuration partielle en fichier *.s3.tfbackend est la réponse, et la forme KEY=VALUE est déconseillée pour un secret.
• use_lockfile = true est un opt-in : sans lui, un .tflock présent est purement ignoré.
• Le verrouillage natif date de Terraform 1.10 ; DynamoDB est déprécié.
• .terraform/terraform.tfstate porte la configuration résolue : c'est là qu'on vérifie, et c'est là que des identifiants atterrissent.
• Après migration, il ne reste aucun state local : le rm habituel est à vide.
• defaults comble un output manquant, jamais un état absent.
• s3:ListBucket est requis ; s3:DeleteObject ne l'est pas sur le state.
• Hors AWS, tout tient à endpoints, use_path_style et aux skip_*, avec un support « best effort ».

FAQ : questions fréquentes

Les questions ci-dessous portent sur ce qui casse en pratique : le verrou qu'on croit actif, la variable refusée dans le bloc backend, et l'identifiant qui atterrit dans .terraform/.

Le backend S3 verrouille-t-il le state par défaut ?

Non. Le verrouillage natif est un opt-in : l'argument use_lockfile vaut false par défaut. Sans lui, un fichier de verrou présent dans le bucket est purement ignoré et deux applies concurrents peuvent s'écraser.

Pourquoi ne puis-je pas utiliser une variable dans le bloc backend ?

Parce que le backend est lu avant l'évaluation des variables. La documentation l'énonce : un bloc backend ne peut référencer aucune valeur nommée, ni variable, ni local, ni attribut de data source. L'init échoue en code 1.

Comment fournir les paramètres du backend sans les figer dans le dépôt ?

Avec la configuration partielle : le bloc backend reste vide et les arguments arrivent à l'init, de préférence par un fichier nommé selon la convention étoile point backend point tfbackend plutôt que par des paires KEY=VALUE.

Comment vérifier quel backend Terraform utilise réellement ?

En lisant .terraform/terraform.tfstate, écrit par Terraform lui-même. Il contient la configuration de backend résolue : type, bucket, clé, région, endpoints et options. Un aws s3 ls prouve qu'un objet existe, pas quelle configuration a été retenue.

Faut-il supprimer le terraform.tfstate local après migration vers S3 ?

Il n'y a rien à supprimer. Mesuré, une fois le backend S3 initialisé, aucun fichier terraform.tfstate ne subsiste dans le répertoire. La commande rm que l'on voit souvent est un rm à vide.

L'argument defaults de terraform_remote_state évite-t-il toute erreur ?

Non. Il fournit une valeur de repli quand l'état existe mais qu'un output y manque. Si l'état n'existe pas du tout, Terraform échoue sur Unable to find remote state, quelle que soit la valeur déclarée en repli.

Quelles permissions IAM le backend S3 exige-t-il ?

s3:ListBucket sur le bucket, plus s3:GetObject et s3:PutObject sur le state. Contrairement à ce qu'on suppose souvent, s3:DeleteObject n'est pas requis sur le fichier de state ; il l'est sur l'objet de verrou.

Peut-on utiliser le backend S3 avec MinIO ou un émulateur local ?

Oui, avec un jeu d'arguments précis : le bloc endpoints, use_path_style, et les options skip_credentials_validation, skip_requesting_account_id, skip_metadata_api_check et skip_region_validation. Le support est toutefois annoncé comme best effort.

Pour aller plus loin

• Importer, déplacer, accepter la dérive : reprendre une ressource existante une fois le state partagé.
• Le backend S3 : la référence officielle : use_lockfile, endpoints, les skip_* et les permissions.
• L'état distant : la référence officielle : terraform_remote_state, defaults et l'avertissement de sécurité.
• Le bloc backend : la référence officielle : l'interdiction des valeurs nommées et la configuration partielle.

×

📖 Voir la documentation →