Comprendre le state Terraform

Terraform a besoin de savoir ce qui existe déjà avant de décider quoi créer, modifier ou supprimer. Le state est le fichier qui lui sert de mémoire : sans lui, Terraform considère que rien n’existe et tente de tout recréer. Ce guide explique ce qu’est le state, ce qu’il contient, et pourquoi le protéger est essentiel.

Quand vous lancez terraform apply, Terraform compare votre code (ce que vous voulez) avec le state (ce qui existe). La différence entre les deux produit le plan — la liste des actions à effectuer. Si le state est perdu ou corrompu, ce calcul devient impossible : Terraform ne peut plus distinguer une création d’une modification.

Prérequis : avoir suivi Première infrastructure ou avoir créé au moins une ressource avec terraform apply.

Ce que vous allez apprendre

• Ce qu’est le state et pourquoi Terraform en a besoin
• Ce que contient le fichier terraform.tfstate (structure JSON)
• Comment le state évolue à chaque apply (serial, backup automatique)
• Ce qui se passe quand le state est perdu
• Les règles essentielles pour protéger votre state

Ce qu’est le state

Analogie

Imaginez que vous rénovez un appartement. Vous avez un plan papier qui liste tout ce que vous avez déjà fait : « cuisine repeinte en blanc, étagère montée dans le salon, prise ajoutée dans la chambre ». Sans cette liste, vous risquez de repeindre la cuisine une deuxième fois ou d’oublier que l’étagère existe. Le state Terraform, c’est cette liste.

Le state est un fichier JSON nommé terraform.tfstate qui enregistre l’état réel de votre infrastructure. Chaque ressource créée par Terraform y est décrite avec ses attributs actuels : identifiant, nom, chemin, taille, configuration réseau…

En une phrase : le state fait le lien entre votre code HCL et les objets réels (VMs, disques, réseaux) qui existent sur l’hyperviseur ou le cloud.

Pourquoi Terraform a besoin du state

Terraform est déclaratif : vous décrivez l’état final souhaité, et il calcule les actions nécessaires. Pour ce calcul, il a besoin de trois informations :

Information	Source	Exemple
Ce que vous voulez	Votre code HCL (.tf)	name = "ma-vm.qcow2"
Ce qui existe	Le fichier state	id = "/var/lib/libvirt/images/ma-vm.qcow2"
Ce qu’il faut faire	Le plan (calculé)	No changes ou 1 to add

Glissez pour voir

Sans le state, Terraform ne dispose que de votre code. Il ne peut pas savoir si la VM existe déjà ou non. Résultat : il essaie de tout recréer — et échoue souvent parce que les ressources existent déjà.

À retenir

Le state n’est pas une copie de votre code. C’est une photographie de la réalité : les attributs qu’il contient sont ceux renvoyés par le provider après la création réelle de chaque ressource.

Créer un state — en pratique

Pour observer le state en action, créez un projet minimal avec un seul volume :

versions.tf

terraform {
  required_version = ">= 1.11.0"
  required_providers {
    libvirt = {
      source  = "dmacvicar/libvirt"
      version = "~> 0.8"
    }
  }
}

provider "libvirt" {
  uri = "qemu:///system"
}

main.tf

resource "libvirt_volume" "disk" {
  name   = "state-demo.qcow2"
  pool   = "default"
  target = { format = { type = "qcow2" } }
  create = { content = { url = "/chemin/vers/ubuntu-24.04-cloudimg.img" } }
}

outputs.tf

output "disk_path" {
  description = "Chemin du volume sur l'hôte"
  value       = libvirt_volume.disk.path
}

output "disk_name" {
  description = "Nom du volume"
  value       = libvirt_volume.disk.name
}

Appliquez :

terraform init
terraform apply -auto-approve

Résultat :

Apply complete! Resources: 1 added, 0 changed, 0 destroyed.

Outputs:

disk_name = "state-demo.qcow2"
disk_path = "/var/lib/libvirt/images/state-demo.qcow2"

Un fichier terraform.tfstate est apparu dans le répertoire. C’est le state.

Ce que contient le state

Le state est un fichier JSON lisible. Voici sa structure simplifiée après la création du volume :

{
  "version": 4,
  "terraform_version": "1.14.3",
  "serial": 2,
  "lineage": "cedddae6-a296-...",
  "outputs": {
    "disk_name": {
      "value": "state-demo.qcow2",
      "type": "string"
    },
    "disk_path": {
      "value": "/var/lib/libvirt/images/state-demo.qcow2",
      "type": "string"
    }
  },
  "resources": [
    {
      "mode": "managed",
      "type": "libvirt_volume",
      "name": "disk",
      "provider": "provider[\"registry.terraform.io/dmacvicar/libvirt\"]",
      "instances": [
        {
          "attributes": {
            "id": "/var/lib/libvirt/images/state-demo.qcow2",
            "name": "state-demo.qcow2",
            "pool": "default",
            "capacity": 3758096384
          }
        }
      ]
    }
  ]
}

Anatomie des champs principaux

Champ	Rôle	Exemple
version	Version du format du state	4 (stable depuis Terraform 0.12)
terraform_version	Version de Terraform utilisée	"1.14.3"
serial	Compteur incrémenté à chaque modification	2 → 3 → 4…
lineage	Identifiant unique du state (UUID)	"cedddae6-a296-..."
outputs	Valeurs des blocs output {}	disk_path, disk_name
resources	Liste des ressources gérées avec leurs attributs réels	libvirt_volume.disk

Glissez pour voir

Le serial : compteur de versions

Chaque terraform apply qui modifie le state incrémente le serial. C’est un mécanisme de protection : si deux personnes appliquent en parallèle, Terraform détecte que le serial attendu ne correspond pas et refuse l’opération. C’est la base du verrouillage optimiste (optimistic locking).

Comment le state évolue

Le state n’est pas figé. Il change à chaque apply qui modifie l’infrastructure ou les outputs.

1. Premier apply : le state est créé avec serial: 1 (ou 2 selon le provider).

2. Apply suivant avec changement : Terraform écrit le nouveau state avec un serial incrémenté. L’ancien state est sauvegardé dans terraform.tfstate.backup.

3. Apply sans changement : le state ne change pas, le serial reste identique.

Vérifiez par vous-même :

# Après le premier apply
ls -lh terraform.tfstate terraform.tfstate.backup

-rw-rw-r-- 1 bob bob 1,9K mars  31 13:33 terraform.tfstate
-rw-rw-r-- 1 bob bob 1,9K mars  31 13:33 terraform.tfstate.backup

Le backup contient l’état précédent. Si un apply corrompt le state, vous pouvez restaurer le backup.

Que se passe-t-il sans state ?

C’est la démonstration la plus parlante. Supprimez temporairement le state et lancez un plan :

mv terraform.tfstate terraform.tfstate.sauvegarde
terraform plan

Résultat — Terraform veut tout recréer :

Terraform will perform the following actions:

  # libvirt_volume.disk will be created
  + resource "libvirt_volume" "disk" {
      + name       = "state-demo.qcow2"
      + pool       = "default"
      ...
    }

Plan: 1 to add, 0 to change, 0 to destroy.

Le volume existe toujours sur l’hyperviseur, mais Terraform ne le sait plus. Si vous appliquez ce plan, il tentera de créer un doublon — et échouera probablement.

Restaurez le state :

mv terraform.tfstate.sauvegarde terraform.tfstate
terraform plan

No changes. Your infrastructure matches the configuration.

Terraform retrouve sa mémoire. Le plan est vide.

Attention — Perte de state

Perdre le state est l’un des scénarios les plus graves en Terraform. Vous vous retrouvez avec une infrastructure “orpheline” que Terraform ne gère plus. La reconstruction du state est possible (terraform import), mais manuelle et fastidieuse.

Lire le state avec les commandes Terraform

Vous n’avez pas besoin d’ouvrir le fichier JSON directement. Terraform fournit des commandes dédiées :

# Lister toutes les ressources du state
terraform state list

libvirt_volume.disk

# Voir les détails d'une ressource
terraform state show libvirt_volume.disk

# libvirt_volume.disk:
resource "libvirt_volume" "disk" {
    allocation = 629989376
    capacity   = 3758096384
    id         = "/var/lib/libvirt/images/state-demo.qcow2"
    name       = "state-demo.qcow2"
    path       = "/var/lib/libvirt/images/state-demo.qcow2"
    pool       = "default"
    target     = {
        format = {
            type = "qcow2"
        }
        path   = "/var/lib/libvirt/images/state-demo.qcow2"
    }
}

À retenir

Préférez terraform state list et terraform state show à l’ouverture directe du fichier JSON. Ces commandes formatent les données et sont fiables même avec un state distant.

Le state peut contenir des données sensibles

Le state enregistre tous les attributs des ressources — y compris les mots de passe, clés SSH et tokens que le provider renvoie. Un terraform.tfstate non protégé est un risque de sécurité.

Donnée sensible	Comment elle se retrouve dans le state
Mot de passe base de données	Attribut password d’une ressource DB
Clé SSH privée	Attribut private_key d’un tls_private_key
Token API	Attribut token d’un random_password

Glissez pour voir

Règles de base :

• Ne jamais commiter terraform.tfstate dans Git
• Ajouter *.tfstate et *.tfstate.backup dans .gitignore
• Pour un vrai projet, utiliser un backend distant avec chiffrement

Ne jamais versionner le state

Un terraform.tfstate poussé sur un dépôt Git expose potentiellement tous les secrets de votre infrastructure. Même si vous le supprimez ensuite, l’historique Git le conserve.

Le .gitignore recommandé

Ajoutez ces entrées à votre .gitignore dès le premier terraform init :

# Terraform state — contient des données sensibles
*.tfstate
*.tfstate.backup
*.tfstate.*.backup

# Répertoire de travail Terraform
.terraform/

# Fichiers de variables sensibles
*.tfvars
!example.tfvars

Dépannage

Symptôme	Cause probable	Solution
terraform plan veut tout recréer	State absent ou corrompu	Vérifier terraform.tfstate, restaurer le backup
Error: resource already exists	State perdu mais ressource toujours présente	terraform import pour réassocier
serial ne correspond pas	Deux apply simultanés	Utiliser un backend distant avec verrouillage
State très volumineux	Trop de ressources dans un seul projet	Découper en plusieurs projets/stacks

Glissez pour voir

À retenir

• Le state (terraform.tfstate) est la mémoire de Terraform : il fait le lien entre votre code et l’infrastructure réelle
• Sans state, Terraform considère que rien n’existe et tente de tout recréer
• Le serial s’incrémente à chaque modification — c’est un mécanisme de protection contre les modifications concurrentes
• Le backup (terraform.tfstate.backup) contient l’état précédent — c’est votre filet de sécurité immédiat
• Le state peut contenir des données sensibles : ne jamais le commiter dans Git
• Utilisez terraform state list et terraform state show pour inspecter le state — pas l’éditeur de texte

Prochaines étapes

Backends Terraform Stocker le state à distance pour sécuriser et partager votre infrastructure.

terraform state list Lister toutes les ressources gérées par Terraform dans le state.

terraform state show Afficher les attributs détaillés d'une ressource dans le state.

×

📖 Voir la documentation →