Sauvegarder et restaurer le state Terraform

terraform state pull exporte le state complet en JSON vers la sortie standard, et terraform state push le réimporte. Ces deux commandes forment le duo sauvegarde/restauration du state. En complément, Terraform crée automatiquement un fichier .backup à chaque opération qui modifie le state. Ensemble, ces mécanismes vous protègent contre les corruptions et les erreurs de manipulation.

Analogie

Le state est la carte d’identité de votre infrastructure. pull en fait une photocopie que vous rangez en lieu sûr, et push restaure la carte originale à partir de la photocopie.

Prérequis : avoir un projet Terraform avec des ressources déployées et comprendre la structure du state.

Ce que vous allez apprendre

• Exporter le state avec terraform state pull
• Créer des sauvegardes manuelles horodatées
• Comprendre les sauvegardes automatiques (.backup)
• Restaurer un state avec terraform state push
• Gérer les conflits de version (serial)

Exporter le state avec pull

terraform state pull affiche le contenu complet du state en JSON sur la sortie standard :

terraform state pull

{
  "version": 4,
  "terraform_version": "1.14.3",
  "serial": 3,
  "lineage": "2adb552a-e139-00c0-689a-8c9bebad16a2",
  "outputs": {},
  "resources": [
    {
      "mode": "managed",
      "type": "libvirt_network",
      "name": "net",
      "provider": "provider[\"registry.terraform.io/dmacvicar/libvirt\"]",
      "instances": [...]
    },
    ...
  ]
}

Les métadonnées clés du state sont :

Champ	Rôle
version	Format du state (actuellement 4)
terraform_version	Version de Terraform qui a écrit ce state
serial	Compteur incrémenté à chaque modification — sert de garde-fou
lineage	Identifiant unique du state — empêche de mélanger deux projets
resources	Liste complète des ressources gérées

Glissez pour voir

pull fonctionne avec tous les backends

Que votre state soit en local ou dans un backend distant (S3, Consul, etc.), state pull l’exporte de la même manière. C’est la commande universelle pour obtenir le state brut.

Créer une sauvegarde manuelle

Redirigez la sortie de pull vers un fichier horodaté pour créer une sauvegarde :

terraform state pull > state-backup-$(date +%Y%m%d-%H%M%S).json

ls -la state-backup-*.json

-rw-rw-r-- 1 bob bob 3630 mars  31 14:31 state-backup-20260331-143123.json

Cette sauvegarde est un fichier JSON autonome. Vous pouvez la stocker dans un emplacement sûr séparé de votre répertoire de travail.

Bonnes pratiques de sauvegarde

• Faites une sauvegarde avant toute opération risquée (state mv, state rm, import)
• Nommez vos fichiers avec la date et l’opération : state-avant-migration-20260331.json
• Stockez les sauvegardes en dehors du répertoire du projet (pas dans Git avec le code)
• Avec un backend distant (S3), activez le versioning du bucket

Sauvegardes automatiques (.backup)

Terraform crée automatiquement un fichier terraform.tfstate.backup contenant le state précédent à chaque opération qui modifie le state (apply, state mv, state rm…) :

ls -la terraform.tfstate*

-rw-rw-r-- 1 bob bob 3630 mars  31 14:31 terraform.tfstate
-rw-rw-r-- 1 bob bob 3629 mars  31 14:31 terraform.tfstate.backup

Le fichier .backup contient toujours la version précédente du state. Vous pouvez comparer les serials pour le vérifier :

Fichier	Serial	Contenu
terraform.tfstate	5	State actuel (après le dernier apply)
terraform.tfstate.backup	3	État précédent (avant le dernier apply)

Glissez pour voir

Le .backup n'est pas une vraie stratégie de sauvegarde

Terraform ne conserve qu’un seul fichier .backup. Il reflète uniquement l’opération précédente. Si vous enchaînez apply, puis state mv, puis un nouvel apply, le .backup final peut déjà avoir écrasé le point de restauration qui vous intéressait. Ce fichier est un filet de sécurité immédiat, pas un historique ni un plan de reprise. Pour les opérations critiques, faites toujours une sauvegarde manuelle avec state pull.

Restaurer le state avec push

terraform state push écrit un fichier de state dans le backend. Pour restaurer une sauvegarde :

terraform state push state-backup-20260331-143123.json

Protection contre les régressions

Terraform refuse d’écraser un state plus récent (serial supérieur) avec un state plus ancien :

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

Ce garde-fou empêche les restaurations accidentelles qui perdraient des changements.

Forcer la restauration

Si vous êtes certain de vouloir restaurer un state ancien, utilisez -force :

terraform state push -force state-backup-20260331-143123.json

Terraform pousse le state et incrémente le serial automatiquement. Après un push forcé du serial 3, le state aura le serial 4 (3 + 1).

push -force est dangereux en équipe

Sur un backend distant partagé, push -force écrase le state pour toute l’équipe. Utilisez-le uniquement en dernier recours, après coordination avec vos collègues. Un state incohérent peut avoir des conséquences graves : ressources dupliquées, destructions involontaires.

Workflow de sauvegarde avant opération risquée

Avant toute manipulation du state (mv, rm, import), suivez cette procédure :

1. Sauvegarder le state actuel

   terraform state pull > state-avant-operation.json

   Ne comptez pas sur terraform.tfstate.backup ici : il ne représentera peut-être déjà plus le bon point de retour après la commande suivante.

2. Effectuer l’opération

   terraform state mv libvirt_volume.web libvirt_volume.frontend

3. Vérifier avec un plan

   terraform plan

   Si le plan est propre (No changes), l’opération est réussie.

4. En cas de problème — restaurer

   terraform state push -force state-avant-operation.json

Comparaison des mécanismes de sauvegarde

Mécanisme	Quand	Contenu	Conservation
terraform.tfstate.backup	Automatique à chaque opération	State précédent (N-1)	Écrasé à chaque opération
terraform state pull > fichier.json	Manuel	State complet au moment T	Conservé tant que le fichier existe
Versioning S3	Automatique (si activé)	Historique complet	Toutes les versions
Snapshot backend distant	Selon le backend	Selon configuration	Variable

Glissez pour voir

Dépannage

Symptôme	Cause probable	Solution
cannot import state with serial N over newer state with serial M	Serial du backup inférieur au state actuel	Utiliser -force si volontaire
cannot import state with serial N, which is the same as the current state	Le fichier poussé est identique au state actuel	Rien à faire — les states sont identiques
cannot import state with a different lineage	Le backup provient d’un autre projet	Vérifier que le backup correspond au bon projet
Le .backup n’existe pas	Un seul apply a été fait	Normal — .backup est créé à partir du 2ème apply
state pull retourne un state vide	Aucun apply effectué	Lancer terraform apply d’abord

Glissez pour voir

À retenir

• terraform state pull exporte le state complet en JSON vers la sortie standard — fonctionne avec tous les backends
• Redirigez vers un fichier horodaté pour créer des sauvegardes manuelles avant chaque opération risquée
• Le fichier terraform.tfstate.backup ne contient que la version N-1 — pas un historique complet
• terraform state push restaure un state depuis un fichier, avec une protection par serial contre les régressions
• -force est un dernier recours — coordonnez-vous en équipe avant un push forcé
• Pour un historique complet, activez le versioning S3 ou utilisez un backend avec snapshots

Prochaines étapes

Diagnostiquer le state Identifier et résoudre les problèmes courants du state Terraform.

Configurer un backend distant Stocker le state dans S3 avec verrouillage et versioning.

terraform state mv Renommer ou déplacer une ressource sans la recréer.

×

📖 Voir la documentation →