Sauvegarder et restaurer le state Terraform

Un state perdu, tronqué ou amputé ne détruit rien : l'infrastructure continue de tourner, ce sont les enregistrements qui manquent. La réparation consiste donc à remettre le bon state, jamais à relancer un apply qui recréerait ce qui existe déjà. Ce guide s'adresse à qui doit mener cette réparation : sauvegarder avec terraform state pull, choisir la bonne sauvegarde, restaurer avec terraform state push, et prouver que l'opération a réussi autrement qu'en lisant une sortie à l'œil.

Toutes les affirmations mesurables de ce guide, messages d'erreur, codes de sortie et valeurs de serial, ont été rejouées sur Terraform v1.15.4 avec le provider hashicorp/local, sur un state local.

Ce que vous allez apprendre

• Sauvegarder un state, et ce que la sauvegarde ne contient pas
• Reconnaître les deux filets que Terraform pose de lui-même
• Restaurer avec state push, et la vraie portée de -force
• Choisir entre plusieurs sauvegardes candidates
• Prouver la réussite par le code de sortie, pas par la lecture

Prérequis

• Terraform 1.11 ou plus récent (installer Terraform).
• Savoir ce que contient un state, en particulier les champs serial et lineage : comprendre le state les définit, ce guide les met en œuvre.
• Sur un backend partagé, savoir lever un verrou resté en place : verrouiller le state. La procédure officielle de reprise place terraform force-unlock en étape 1, avant toute sauvegarde, parce qu'une restauration fait souvent suite à un apply interrompu.

Les exemples reposent sur une configuration jetable, sans cloud :

terraform {
  # Version epinglee : les messages d'erreur cites plus bas sont ceux de la
  # branche 1.15.x, ils ont evolue au fil des versions.
  required_version = ">= 1.7"
  required_providers {
    local = { source = "hashicorp/local", version = ">= 2.5" }
  }
}

# Un fichier sur le disque : il rend toute recreation immediatement visible.
resource "local_file" "note" {
  filename = "${path.root}/note.txt"
  content  = "note\n"
}

Que sauvegarde-t-on au juste ?

Le state, et lui seul. terraform state pull écrit sur la sortie standard le state courant, quel que soit le backend : c'est le geste de sauvegarde de référence, y compris sur un backend distant où le fichier n'est pas accessible directement.

terraform state pull > sauvegarde-2026-07-28.json

Une sauvegarde par pull n'est pas une copie fidèle

La documentation officielle prévient, et le mot qui compte est converted : « You cannot use this command to inspect the Terraform version of the remote state, as it will always be converted to the current Terraform version before output. »

Vérifié sur 1.15.4 : un state portant "terraform_version": "1.5.0", poussé puis relu par pull, ressort en 1.15.4. Le champ terraform_version d'une sauvegarde décrit donc le binaire qui l'a lue, pas celui qui a écrit l'original.

Quels filets Terraform pose-t-il tout seul ?

Deux, et ils ne couvrent pas les mêmes opérations. C'est la source de malentendu la plus fréquente sur ce sujet.

Le premier est terraform.tfstate.backup, propre au backend local. Il contient l'état d'avant la dernière écriture, n'existe pas après le premier apply, et n'est écrit qu'une fois par exécution.

Le second passe inaperçu. Une commande de manipulation du state ne touche pas à ce fichier : elle dépose un fichier horodaté.

terraform state rm local_file.note
ls terraform.tfstate*

terraform.tfstate
terraform.tfstate.1785262538.backup

Vérifié sur 1.15.4 : après ce state rm, terraform.tfstate.backup n'a pas bougé, et c'est le fichier horodaté qui porte l'état complet d'avant la commande. Le filet qui vous sauvera après une manipulation de state n'est donc pas celui que vous surveillez. Comme ces fichiers sont presque toujours gitignorés, un nettoyage de répertoire les emporte sans bruit.

L'option -backup redirige ce fichier vers le chemin de votre choix, ce qui permet de l'archiver ailleurs que dans le répertoire de travail :

terraform state rm -backup=filet-avant-retrait.json local_file.note

`-backup=-` ne désactive rien ici

La page du backend local documente -backup=- comme désactivant totalement la création des fichiers de sauvegarde, tandis que l'index des sous-commandes terraform state affirme l'inverse, « backups for state modification can not be disabled ».

Mesuré sur 1.15.4, dans deux répertoires neufs : terraform state rm -backup=- écrit quand même son terraform.tfstate.<epoch>.backup. C'est donc la seconde page qui décrit le comportement réel, au moins pour cette sous-commande.

Restaurer avec terraform state push

La commande fait le chemin inverse du pull et écrit un state complet à la place du courant. Elle oppose deux refus, et ces refus sont exactement ce qui protège l'infrastructure.

Le garde-fou du serial empêche d'écraser des écritures plus récentes :

Failed to write state: cannot import state with serial 3 over newer state with serial 5

Le garde-fou du lineage empêche d'écraser un projet avec le state d'un autre :

Failed to write state: cannot import state with lineage "7f3c1a90-2b48-4e5d-9c17-6ad0e2b4915f" over unrelated state with lineage "88580bd8-9e4c-4a0f-b71e-2f0d3c6ab145"

Un troisième cas se produit quand deux states portent le même serial mais un contenu différent, typiquement après une édition manuelle :

Failed to write state: cannot overwrite existing state with serial 1 with a different state that has the same serial

Ces trois refus sortent en code 1. À l'inverse, pousser exactement ce qu'un pull vient de rendre est accepté en silence, en code 0 : lineage, serial et contenu coïncident, il n'y a rien à signaler.

Pourquoi -force est plus dangereux qu'il n'en a l'air

Parce qu'il neutralise les deux garde-fous d'un coup, pas seulement celui du serial. La documentation le formule sans détour, et l'avertissement est explicite : « Both of these safety checks can be disabled with the -force flag. This is not recommended. »

terraform state push -force sauvegarde-2026-07-28.json

Une restauration légitime tombe forcément sur le refus du serial, puisqu'elle remet un état antérieur : -force est donc inévitable, et c'est précisément ce qui rend l'option piégeuse. Il n'y a ni confirmation ni question, et le contrôle de lineage tombe en même temps. Vérifiez le lineage avant de forcer, jamais après :

terraform state pull | jq -r .lineage
jq -r .lineage sauvegarde-2026-07-28.json

Deux valeurs identiques, et la sauvegarde appartient bien à ce projet. Deux valeurs différentes, et vous vous apprêtiez à écraser une infrastructure avec le state d'une autre.

Quel serial obtient-on après une restauration ?

Celui de la sauvegarde, augmenté de un. Pas celui du state remplacé, ce qui surprend et porte des conséquences concrètes. Mesuré sur 1.15.4 :

Fichier	serial
le state courant, avant	15
la sauvegarde poussée	1
le state courant, après	2

Glissez pour voir

La bonne nouvelle, c'est qu'un push incrémente toujours : le state restauré porte donc un serial supérieur à celui de la sauvegarde. Une copie de fichier posée à la main par-dessus terraform.tfstate laisserait le serial identique : le contournement se lit dans le fichier longtemps après.

La mauvaise concerne les backends partagés. Votre state restauré peut porter un serial très inférieur à celui que d'autres postes ont déjà vu. Un collègue dont le cache connaît le serial 15 se retrouve devant un state à 2, et son prochain push légitime écrasera votre réparation. Prévenez l'équipe avant que quiconque ne pousse.

Comment prouver qu'une restauration a réussi ?

Par le code de sortie, jamais par la lecture d'un message. Deux contrôles suffisent, et ils s'automatisent :

1. Le plan ne propose plus rien

   terraform plan -detailed-exitcode
   echo $?

   0 signifie convergence, 2 un changement en attente, 1 une erreur. Un code 2 après une restauration est le symptôme d'une sauvegarde périmée : ses attributs ne décrivent plus le réel, et Terraform propose un remplacement, local_file.note must be replaced.

2. Le state porte les ressources attendues

   terraform show -json | jq '[.values.root_module.resources[]
     | select(.mode == "managed") | .address]'

   Le comptage se fait sur la sortie structurée, jamais sur state list, dont la mise en forme s'adresse à un humain.

Restaurer une partie seulement du state

terraform state push lit aussi son entrée sur stdin quand on lui passe un tiret, ce qui autorise une réparation chirurgicale en une ligne :

terraform state pull | jq '.serial = 42' | terraform state push -

La documentation précise que ces données sont « loaded completely into memory and verified prior to being written » : la vérification a lieu avant l'écriture. Deux précautions accompagnent cette forme. Le fichier doit être en UTF-8 sans BOM, cause numéro un des restaurations qui échouent sous Windows, où il faut passer par Set-Content. Et sur HCP Terraform ou le backend remote, l'option -ignore-remote-version existe pour passer outre le contrôle de version de l'espace de travail.

Dépannage

Le réflexe qui évite la majorité de ces situations : photographier le state avant toute écriture, puisqu'un push ne se rejoue pas.

Symptôme	Cause probable	Solution
cannot import state with serial N over newer state with serial M	La sauvegarde est antérieure au state courant	Normal pour une restauration : vérifier le lineage, puis -force
cannot import state with lineage ... over unrelated state	La sauvegarde vient d'un autre projet	Ne pas forcer : chercher la sauvegarde du bon lineage
cannot overwrite existing state with serial N with a different state that has the same serial	Deux states au même serial, au contenu différent	Repartir d'un state pull frais plutôt que d'un fichier édité
Le plan sort en 2 après la restauration	Sauvegarde périmée	Reprendre une sauvegarde postérieure au dernier apply
Le state restauré porte un serial très bas	Comportement normal du push	Prévenir l'équipe avant tout nouveau push
Aucun terraform.tfstate.backup après un state rm	Les commandes state écrivent un fichier horodaté	Chercher terraform.tfstate.<epoch>.backup
La restauration échoue sous Windows	Fichier encodé en UTF-8 avec BOM	Réécrire avec Set-Content, sans BOM

Glissez pour voir

Mettre en pratique

Le lab sauvegarder et restaurer le state remet un projet dont le state a été amputé par un state rm malencontreux, trois sauvegardes candidates dont une seule est restaurable, et une infrastructure parfaitement intacte. Les tests comparent lineage et serial, exigent la photo préalable de l'état endommagé, et vérifient la date de modification des fichiers : le raccourci terraform apply, qui recrée l'objet manquant au lieu de réparer le state, y échoue. Il se joue hors ligne.

À retenir

• terraform state pull sauvegarde le state sur tous les backends, mais son champ terraform_version est réécrit à la version locale.
• Le backup terraform.tfstate.backup est local, absent après le premier apply, et non mis à jour par les commandes state.
• Ces commandes déposent un backup horodaté, terraform.tfstate.<epoch>.backup, que -backup=chemin redirige. Mesuré sur 1.15.4, -backup=- ne le désactive pas.
• state push refuse un serial plus ancien, un lineage étranger, et un contenu différent à serial égal. Les trois sortent en code 1.
• -force neutralise les deux garde-fous, lineage compris : contrôlez ce champ avant de forcer.
• Après un push, le serial vaut celui de la sauvegarde plus un. Un serial inchangé signe une copie de fichier, pas une restauration.
• La preuve d'une restauration réussie est plan -detailed-exitcode à 0, doublée d'un comptage sur terraform show -json.
• terraform state push - lit le state sur stdin, en UTF-8 sans BOM.

FAQ : questions fréquentes

Les questions ci-dessous portent sur ce qui bloque le plus souvent : le push refusé, le choix entre plusieurs sauvegardes, et la portée exacte de -force.

Comment sauvegarder le state Terraform ?

Avec terraform state pull, qui écrit le state courant sur la sortie standard quel que soit le backend. C'est le seul geste qui fonctionne aussi bien en local que sur un backend distant, où le fichier n'est pas accessible directement.

Pourquoi terraform state push refuse-t-il ma sauvegarde ?

Trois refus existent, tous en code 1 : un serial plus ancien que le state courant, un lineage étranger au projet, ou un contenu différent à serial égal. Le premier est normal pour une restauration, le deuxième signale la mauvaise sauvegarde.

Que fait exactement l'option -force de terraform state push ?

Elle neutralise les deux garde-fous d'un coup, celui du serial et celui du lineage, sans confirmation. Comme toute restauration légitime bute sur le serial, l'option est inévitable : il faut donc vérifier le lineage avant de forcer.

Quel serial obtient-on après une restauration ?

Celui de la sauvegarde poussée, augmenté de un, et non celui du state remplacé. Mesuré sur 1.15.4 : un serial 1 poussé sur un serial 15 donne 2. Un serial resté identique signe une copie de fichier, pas un push.

Terraform crée-t-il une sauvegarde automatique du state ?

Oui, mais deux mécanismes distincts cohabitent. Les opérations ordinaires écrivent terraform.tfstate.backup, propre au backend local, tandis que les commandes state déposent un fichier horodaté qui, lui, contient l'état d'avant la commande.

Comment savoir si une restauration de state a réussi ?

Par le code de sortie de terraform plan -detailed-exitcode, qui doit valoir 0, doublé d'un comptage des ressources sur terraform show -json. Un code 2 signale une sauvegarde périmée, dont les attributs ne décrivent plus le réel.

Peut-on restaurer une partie du state seulement ?

Oui, en branchant pull, jq et push en pipeline : terraform state push accepte un tiret pour lire le state sur son entrée standard. Le fichier doit être en UTF-8 sans BOM, cause fréquente d'échec sous Windows.

Pour aller plus loin

• Quiz Gérer le state Terraform : Un contrôle des acquis sur les backends, le verrouillage et les opérations de state.
• Séparer dev, staging et prod : Le cloisonnement des states, pour qu'une restauration ne touche qu'un seul périmètre.
• Organiser un dépôt Terraform : La structure de dépôt qui rend chaque state identifiable et sa sauvegarde traçable.

×

📖 Voir la documentation →