Verrouiller le state Terraform

Quand deux personnes lancent terraform apply en même temps sur le même projet, les deux tentent de modifier le state. Sans protection, le second écrase le travail du premier — ou pire, le state devient incohérent. Le verrouillage (locking) résout ce problème : Terraform pose un verrou sur le state avant toute modification et le libère ensuite. Ce guide vous montre comment ce mécanisme fonctionne et comment réagir quand un verrou reste bloqué.

Analogie

Le verrouillage du state fonctionne comme la serrure des toilettes dans un avion : quand quelqu’un entre, la porte affiche « occupé » et personne d’autre ne peut entrer. Une fois la personne sortie, la serrure se libère. Si la personne ne sort jamais (crash), le personnel de bord peut forcer l’ouverture — c’est l’équivalent de terraform force-unlock.

Prérequis : avoir compris le rôle du state Terraform et idéalement avoir configuré un backend distant.

Ce que vous allez apprendre

• Ce qu’est le verrouillage et pourquoi il est indispensable
• Comment fonctionne le verrou avec le backend local (fichier .lock.info)
• Ce qui se passe quand deux apply tournent en même temps
• Comment lire les informations du verrou (ID, opération, auteur, date)
• Comment débloquer un verrou orphelin avec terraform force-unlock
• Les différences de verrouillage selon le backend

Ce qu’est le verrouillage

Le verrouillage (ou state locking) est un mécanisme qui empêche deux opérations Terraform d’écrire dans le state en même temps. Il s’active automatiquement pour toute commande qui modifie le state : apply, destroy, import, state mv, state rm.

En une phrase : un seul apply à la fois, toujours.

Pourquoi c’est indispensable

Sans verrouillage, voici ce qui peut arriver quand Alice et Bob travaillent sur le même projet :

Étape	Alice	Bob	Résultat
1	Lit le state (serial 5)
2		Lit le state (serial 5)	Même point de départ
3	apply → crée VM-A		Serial 6
4		apply → crée VM-B	Écrase le serial 6 d’Alice
5			VM-A disparaît du state

Glissez pour voir

Le state de Bob ne contient pas VM-A — elle est « orpheline ». Terraform ne la gère plus, mais elle existe toujours sur l’hyperviseur. Le verrouillage empêche l’étape 2 : Bob doit attendre qu’Alice ait fini.

Le verrouillage est transparent

Vous n’avez rien à configurer pour activer le verrouillage. Il est activé par défaut sur tous les backends qui le supportent. Vous n’interagissez avec lui que quand il y a un problème.

Comment fonctionne le verrou — backend local

Avec le backend local (par défaut), Terraform crée un fichier .terraform.tfstate.lock.info dans le dossier du projet au début de chaque opération qui modifie le state.

Observer le verrou en action

Pour voir le verrou, il faut qu’un apply prenne assez de temps. Utilisez une ressource terraform_data avec un provisioner qui attend :

# main.tf — ressource lente pour observer le verrou
resource "terraform_data" "slow" {
  input = "verrouillage-demo"

  provisioner "local-exec" {
    command = "echo 'Début du déploiement...' && sleep 30 && echo 'Fin du déploiement.'"
  }
}

1. Lancez l’apply dans un premier terminal

   terraform apply -auto-approve

   Le provisioner affiche « Début du déploiement… » et attend 30 secondes.

2. Pendant ce temps, dans un second terminal, affichez le fichier de verrou

   cat .terraform.tfstate.lock.info

   {
       "ID": "b53d7713-b782-99eb-2e08-8363f2719c1e",
       "Operation": "OperationTypeApply",
       "Info": "",
       "Who": "bob@master1",
       "Version": "1.14.3",
       "Created": "2026-03-31T12:05:34.096511527Z",
       "Path": "terraform.tfstate"
   }

3. Toujours dans le second terminal, tentez un apply concurrent

   terraform apply -auto-approve

   Terraform refuse immédiatement :

   ╷
   │ Error: Error acquiring the state lock
   │
   │ Error message: resource temporarily unavailable
   │ Lock Info:
   │   ID:        b53d7713-b782-99eb-2e08-8363f2719c1e
   │   Path:      terraform.tfstate
   │   Operation: OperationTypeApply
   │   Who:       bob@master1
   │   Version:   1.14.3
   │   Created:   2026-03-31 12:05:34.096511527 +0000 UTC
   │
   │ Terraform acquires a state lock to protect the state from being written
   │ by multiple users at the same time. Please resolve the issue above and try
   │ again. For most commands, you can disable locking with the "-lock=false"
   │ flag, but this is not recommended.
   ╵

4. Une fois le premier apply terminé, vérifiez que le verrou a disparu

   ls .terraform.tfstate.lock.info

   ls: cannot access '.terraform.tfstate.lock.info': No such file or directory

Synthèse

Le cycle de vie du verrou est automatique : créé au début de l’opération, supprimé à la fin. Tant qu’il existe, toute autre commande qui modifie le state est rejetée.

Lire les informations du verrou

Le fichier .terraform.tfstate.lock.info contient un objet JSON avec six champs :

Champ	Description	Exemple
ID	Identifiant unique du verrou (UUID)	b53d7713-b782-99eb-...
Operation	Type d’opération en cours	OperationTypeApply, OperationTypeDestroy
Who	Utilisateur et machine qui détiennent le verrou	bob@master1
Version	Version de Terraform qui a posé le verrou	1.14.3
Created	Date et heure de création du verrou (UTC)	2026-03-31T12:05:34Z
Path	Chemin du state verrouillé	terraform.tfstate

Glissez pour voir

Ces informations sont précieuses pour diagnostiquer un verrou bloqué : vous savez qui fait quoi depuis quand.

Débloquer un verrou orphelin

Un verrou peut rester actif si Terraform plante ou si l’utilisateur fait Ctrl+C au mauvais moment. Le fichier .lock.info reste mais personne ne le détient — c’est un verrou orphelin.

Avec le backend local

Sur le backend local, le verrou utilise le système de fichiers. Si Terraform plante, le fichier .terraform.tfstate.lock.info peut subsister. Pour le supprimer :

rm .terraform.tfstate.lock.info

Vérifiez d’abord que personne n’est réellement en train de faire un apply (consultez le champ Who et Created dans le fichier).

Avec un backend distant

Les backends distants (S3, Consul, PostgreSQL…) gèrent le verrou côté serveur. Terraform fournit la commande force-unlock pour ces cas :

terraform force-unlock LOCK_ID

Le LOCK_ID est le champ ID affiché dans le message d’erreur. Par exemple :

terraform force-unlock b53d7713-b782-99eb-2e08-8363f2719c1e

Terraform demande confirmation avant de supprimer le verrou :

Do you really want to force-unlock?
  Terraform will remove the lock on the remote state.
  This will allow local Terraform commands to modify this state, even though it
  may still be in use. Only 'yes' will be accepted to confirm.

  Enter a value: yes

Ne forcez le déverrouillage que si vous êtes certain

force-unlock supprime le verrou même si un apply est en cours. Si quelqu’un est réellement en train de modifier l’infrastructure, forcer le déverrouillage provoque les mêmes corruptions que l’absence de verrouillage. Vérifiez toujours le champ Who et Created avant de forcer.

Le flag -lock=false

Terraform permet de désactiver le verrouillage avec le flag -lock=false :

terraform apply -lock=false

Ne jamais utiliser -lock=false en équipe

Ce flag est un dernier recours pour des situations exceptionnelles (débogage, backend cassé). En production, il expose votre state à exactement le problème que le verrouillage est censé empêcher.

Verrouillage selon le backend

Chaque backend implémente le verrouillage différemment :

Backend	Mécanisme de verrouillage	Force-unlock
local	Fichier .terraform.tfstate.lock.info (verrou système)	Non (rm manuel)
s3	Fichier .tflock dans le bucket (Terraform ≥ 1.10) ou DynamoDB	Oui
consul	Session lock Consul	Oui
pg	Advisory lock PostgreSQL	Oui
gcs	Objet lock dans le bucket	Oui
azurerm	Blob lease	Oui

Glissez pour voir

S3 : verrouillage natif depuis Terraform 1.10

Avant Terraform 1.10, le backend S3 nécessitait une table DynamoDB séparée pour le verrouillage. Depuis la version 1.10, le verrouillage est natif via les écritures conditionnelles S3 (fichier .tflock). Si vous utilisez une version récente, aucune configuration DynamoDB n’est nécessaire.

Dépannage

Symptôme	Cause probable	Solution
Error acquiring the state lock	Un autre apply est en cours	Attendre sa fin, vérifier le champ Who
Verrou bloqué depuis des heures	Terraform a planté ou a été tué	Backend local : rm .terraform.tfstate.lock.info ; distant : terraform force-unlock LOCK_ID
Local state cannot be unlocked by another process	force-unlock sur backend local	Utiliser rm au lieu de force-unlock pour le backend local
Verrou bloqué après Ctrl+C	Interruption pendant l’écriture du state	Vérifier l’intégrité du state (terraform state list), puis supprimer le verrou

Glissez pour voir

À retenir

• Le verrouillage empêche deux opérations Terraform d’écrire dans le state en même temps — il est activé par défaut
• Avec le backend local, le verrou est un fichier .terraform.tfstate.lock.info — créé au début, supprimé à la fin
• Le verrou contient l’identifiant, l’opération, l’auteur et la date — utiles pour diagnostiquer un blocage
• Un verrou orphelin (crash, Ctrl+C) se supprime avec rm (local) ou terraform force-unlock (distant)
• Le flag -lock=false désactive le verrouillage — à ne jamais utiliser en équipe
• Depuis Terraform 1.10, le backend S3 gère le verrouillage nativement sans DynamoDB

Prochaines étapes

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.

Sauvegarder et restaurer le state Protéger votre state avec des sauvegardes et restaurer en cas de problème.

×

📖 Voir la documentation →