infra / terraform

State Terraform : local vs remote

Leçon 51 exercice

Explication

Ce que vous allez apprendre

Comprendre le rôle exact du fichier terraform.tfstate
Inspecter le state avec terraform show et terraform state list
Identifier les trois problèmes majeurs du state local en travail d'équipe
Migrer un state local vers un backend distant S3 avec verrouillage DynamoDB
Utiliser terraform state mv/rm en toute connaissance de cause

Dans quel contexte ?

Deux développeurs de la même équipe travaillent chacun de leur côté sur la configuration Terraform vue dans les leçons précédentes. Le premier lance un apply pendant que le second en lance un autre en parallèle, sans le savoir : leurs fichiers terraform.tfstate locaux divergent immédiatement, et plus personne ne sait quelle version reflète la réalité du cloud.

D'abord, il faut comprendre à quoi sert réellement le state

Le state est un fichier JSON qui fait le lien entre ta configuration déclarative et les ressources RÉELLES existant dans le cloud, avec leurs identifiants et attributs actuels. Sans lui, Terraform devrait interroger l'intégralité du cloud à chaque exécution pour deviner ce qu'il a déjà créé — un processus lent et peu fiable.

C'est ce fichier qui permet à terraform plan de savoir instantanément "cette ressource existe déjà, celle-ci est nouvelle, celle-là a été supprimée manuellement".

Commande	Rôle
`terraform show`	Affiche le state actuel de façon lisible
`terraform state list`	Liste toutes les ressources trackées
`terraform state mv`	Renomme une ressource dans le state sans la recréer
`terraform state rm`	Retire une ressource du state SANS la détruire dans le cloud

Prérequis

Il faut avoir déjà exécuté au moins un terraform apply (voir les leçons précédentes) pour qu'un fichier terraform.tfstate existe et puisse être inspecté dans cette leçon.

Une fois le rôle du state compris, pourquoi pose-t-il problème dès qu'on travaille à plusieurs ?

Par défaut, ce fichier reste local, sur la machine de la personne qui a lancé apply. Trois problèmes surgissent alors mécaniquement : aucun partage entre développeurs (chacun a sa propre version, forcément désynchronisée), aucun verrouillage (deux apply simultanés peuvent corrompre le fichier), et un risque de fuite de secrets si le fichier est accidentellement committé dans Git.

Piège fréquent

Committer terraform.tfstate dans Git "pour le partager facilement" semble une solution rapide, mais expose potentiellement des secrets en clair dans l'historique Git (récupérable indéfiniment, même après suppression du fichier) et ne résout absolument pas le problème du verrouillage concurrent.

Voici comment on résout ce problème : un backend distant

Un backend S3 avec verrouillage DynamoDB centralise le state dans un espace de stockage partagé, accessible à toute l'équipe et à la CI, avec un mécanisme de verrouillage automatique qui empêche deux apply simultanés de se marcher dessus.

Bonne pratique

Configure toujours encrypt = true sur un backend S3, dès le premier projet, même en développement. Prendre cette habitude dès le début évite d'avoir à migrer une politique de sécurité plus tard sur un state déjà en place et potentiellement déjà exposé.

Le piège à connaître avant de manipuler le state directement

terraform state rm et terraform state push sont des opérations puissantes mais dangereuses : elles modifient la mémoire de Terraform SANS toucher au cloud réel. Une mauvaise manipulation peut faire perdre à Terraform la trace d'une ressource qui continue pourtant d'exister et de coûter de l'argent, ou inversement le faire recréer une ressource déjà présente.

Maintenant que le state est bien compris, la prochaine leçon aborde un complément naturel : comment lire des ressources qui existent déjà dans le cloud, sans les gérer directement via Terraform.

Commandes & code

State Terraform : local vs remote

# Le state (terraform.tfstate) est un fichier JSON qui mappe :
# configuration déclarée <-> ressources RÉELLES dans le cloud (avec leurs IDs, attributs actuels)
# Sans state, Terraform ne pourrait pas savoir ce qu'il a déjà créé.

# Par défaut : state LOCAL, un simple fichier terraform.tfstate dans le répertoire courant
ls -la terraform.tfstate terraform.tfstate.backup     # backup automatique avant chaque modification

# Inspecter le state
terraform show                          # affiche le state actuel en lecture humaine
terraform state list                     # liste toutes les ressources trackées dans le state
terraform state show aws_instance.web    # détail d'une ressource précise

# Manipuler le state (à utiliser avec précaution)
terraform state mv aws_instance.web aws_instance.web_v2   # renomme une ressource dans le state (sans la recréer)
terraform state rm aws_instance.old                        # retire une ressource du state SANS la détruire dans le cloud
terraform state pull > backup.tfstate                       # exporte le state distant en local
terraform state push backup.tfstate                          # ré-importe (dangereux, usage exceptionnel)

# Problèmes du state LOCAL en équipe :
# - Pas de partage : chaque dev a son propre fichier, désynchronisation garantie
# - Pas de verrouillage : deux "apply" simultanés peuvent corrompre le state
# - Secrets en clair dans le fichier, versionné par erreur dans Git si mal géré

# backend.tf : state distant sur S3, avec verrouillage via DynamoDB
terraform {
  backend "s3" {
    bucket         = "mon-org-terraform-state"
    key            = "projets/api/terraform.tfstate"    # chemin unique par projet/environnement
    region         = "eu-west-3"
    dynamodb_table = "terraform-locks"                    # table pour le verrouillage (lock)
    encrypt        = true                                  # chiffrement du state au repos
  }
}

# Après avoir ajouté/modifié un backend, il faut ré-initialiser
terraform init -migrate-state          # migre le state local existant vers le nouveau backend
terraform init -reconfigure             # change de backend sans migrer (attention, perte possible)

Résumé

Le state mappe la configuration déclarative aux ressources réelles : sans lui, Terraform "perd la mémoire" de ce qu'il gère.
Le state local ne convient pas au travail en équipe : pas de partage, pas de verrouillage automatique.
Un backend distant (S3 + DynamoDB pour le lock) est la base de tout usage Terraform en production/équipe.

Exercices pratiques

1 disponible

Mission : réparer un state corrompu par un apply concurrent

Objectif : Diagnostiquer les risques du state local en équipe et migrer proprement vers un backend distant verrouillé.

Contexte

Deux développeurs travaillent sur la même configuration Terraform, chacun avec un state LOCAL (aucun backend distant configuré). Ils lancent chacun terraform apply presque simultanément un mardi matin, sans se prévenir. Le lendemain, leurs deux fichiers terraform.tfstate ne racontent plus la même histoire de l'infrastructure.

Résoudre l’exercice →