Diagnostiquer le state Terraform

Quand quelqu’un modifie manuellement une ressource — supprime un réseau via la console, change un paramètre en SSH — le state Terraform ne le sait pas. L’écart entre ce que le state décrit et ce qui existe réellement s’appelle le drift. terraform plan le détecte, terraform apply -refresh-only met le state à jour, et terraform import rattache une ressource existante que Terraform ne connaît pas encore. Ces trois mécanismes forment votre boîte à outils de diagnostic.

Analogie

Le state est un inventaire de magasin. Si quelqu’un prend un article sans le scanner, l’inventaire est faux. Un diagnostic, c’est comparer l’inventaire (state) avec les rayons (infrastructure réelle) pour trouver les écarts.

Prérequis : connaître la structure du state et savoir utiliser terraform state list et terraform state show.

Ce que vous allez apprendre

• Détecter le drift avec terraform plan
• Mettre à jour le state sans modifier l’infrastructure avec terraform apply -refresh-only
• Importer une ressource existante dans le state avec terraform import
• Utiliser le bloc import comme alternative déclarative (Terraform >= 1.5)
• Automatiser la détection de drift avec -detailed-exitcode

Qu’est-ce que le drift ?

Le drift (dérive) apparaît quand l’infrastructure réelle ne correspond plus à ce que le state décrit. Les causes les plus fréquentes sont :

Cause	Exemple concret
Modification manuelle	Quelqu’un désactive l’autostart d’un réseau via la console
Action d’un autre outil	Un script Ansible modifie une configuration
Suppression externe	Un collègue supprime une VM directement
Expiration automatique	Un certificat ou une ressource temporaire expire

Glissez pour voir

Le drift n’est pas une erreur en soi — c’est une désynchronisation entre le state et la réalité. Le problème survient si vous ne le détectez pas : le prochain apply peut produire des résultats inattendus.

Détecter le drift avec plan

terraform plan compare systématiquement le state avec l’infrastructure réelle avant de calculer les changements. Si une ressource a été modifiée en dehors de Terraform, le plan le signale.

Imaginons qu’un collègue désactive l’autostart d’un réseau directement en ligne de commande :

terraform plan

libvirt_network.net: Refreshing state... [id=a12f1d21-0a1e-4af2-9b0b-2c7c59d043df]

Terraform used the selected providers to generate the following execution plan.

  # libvirt_network.net will be updated in-place
  ~ resource "libvirt_network" "net" {
      ~ autostart = false -> true
        id        = "a12f1d21-0a1e-4af2-9b0b-2c7c59d043df"
        name      = "mon-reseau"
    }

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

Le plan montre autostart = false -> true : la valeur réelle (false) diffère de la valeur déclarée dans le code (true). Terraform propose de corriger le drift en remettant la valeur du code.

Plan détecte, il ne corrige pas

terraform plan est en lecture seule. Il vous informe du drift sans modifier ni le state, ni l’infrastructure. C’est l’étape de diagnostic — la correction vient ensuite.

Deux réponses possibles face au drift

Quand terraform plan détecte un drift, vous avez deux choix :

Stratégie	Commande	Quand l’utiliser
Corriger le drift	terraform apply	La modification manuelle était une erreur — vous voulez remettre l’infrastructure conforme au code
Accepter le drift	terraform apply -refresh-only	La modification manuelle était intentionnelle — vous voulez mettre le state à jour pour refléter la réalité

Glissez pour voir

Mettre à jour le state avec refresh-only

N’utilisez plus terraform refresh dans les guides récents ou vos scripts : préférez terraform apply -refresh-only, qui montre les écarts détectés et demande une confirmation avant d’écrire dans le state.

terraform apply -refresh-only lit l’état réel de chaque ressource et met à jour le state sans modifier l’infrastructure. C’est l’inverse d’un apply classique : au lieu de rendre l’infrastructure conforme au code, il rend le state conforme à la réalité.

terraform apply -refresh-only

libvirt_network.net: Refreshing state... [id=a12f1d21-0a1e-4af2-9b0b-2c7c59d043df]

Note: Objects have changed outside of Terraform

Terraform detected the following changes made outside of Terraform since the
last "terraform apply" command:

  # libvirt_network.net has changed
  ~ resource "libvirt_network" "net" {
      ~ autostart = true -> false
        id        = "a12f1d21-0a1e-4af2-9b0b-2c7c59d043df"
        name      = "mon-reseau"
    }

Would you like to update the Terraform state to reflect these detected changes?

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

Terraform vous montre les écarts détectés et demande confirmation. Après le refresh, le state reflète la réalité — mais votre code HCL contient toujours autostart = true. Le prochain plan proposera donc de corriger l’infrastructure.

Mettez à jour le code après un refresh-only

Si vous acceptez le drift avec refresh-only, pensez à mettre le code HCL à jour pour correspondre. Sinon, le prochain terraform apply annulera le changement que vous avez accepté.

refresh-only remplace terraform refresh

L’ancienne commande terraform refresh existe encore mais est déconseillée. Elle modifie le state sans confirmation. Préférez toujours terraform apply -refresh-only qui vous montre les changements et demande une validation.

Importer une ressource existante

terraform import rattache une ressource qui existe déjà dans l’infrastructure au state Terraform. Le cas classique : une ressource créée manuellement ou par un autre outil que vous voulez désormais gérer avec Terraform.

Workflow d’import

1. Écrire le bloc resource dans le code HCL

   Avant d’importer, le bloc resource correspondant doit exister dans votre configuration :

   resource "libvirt_network" "legacy" {
     name      = "legacy-manual-net"
     autostart = true
   
     forward = {
       mode = "nat"
     }
   
     ips = [{
       address = "10.10.99.1"
       netmask = "255.255.255.0"
       dhcp = {
         ranges = [{
           start = "10.10.99.100"
           end   = "10.10.99.200"
         }]
       }
     }]
   }

2. Identifier l’ID de la ressource existante

   Chaque provider utilise un format d’ID différent. Pour le provider libvirt, un réseau s’identifie par son UUID :

   virsh net-info legacy-manual-net

   Name:           legacy-manual-net
   UUID:           d227692a-646f-47a4-8b0a-fefbe48b6601
   Active:         yes
   Persistent:     yes
   Autostart:      yes
   Bridge:         virbr-legacy

   Le format de l'ID dépend du provider

   Chaque provider définit son propre format d’ID pour l’import. Consultez la documentation du provider pour connaître le format attendu. Par exemple : UUID pour un réseau libvirt, ARN pour une ressource AWS, ID numérique pour un groupe de sécurité.

3. Exécuter l’import

   terraform import libvirt_network.legacy d227692a-646f-47a4-8b0a-fefbe48b6601

   libvirt_network.legacy: Importing from ID "d227692a-646f-47a4-8b0a-fefbe48b6601"...
   libvirt_network.legacy: Import prepared!
     Prepared libvirt_network for import
   libvirt_network.legacy: Refreshing state... [id=d227692a-646f-47a4-8b0a-fefbe48b6601]
   
   Import successful!
   
   The resources that were imported are shown above. These resources are now in
   your Terraform state and will henceforth be managed by Terraform.

4. Vérifier avec un plan

   Après l’import, un terraform plan peut montrer des différences entre le state importé et votre code HCL :

   terraform plan

   Si le plan affiche No changes, la configuration correspond parfaitement. Sinon, ajustez votre code HCL pour correspondre à la réalité de la ressource, ou appliquez pour aligner l’infrastructure sur votre code.

Alternative déclarative : le bloc import (Terraform >= 1.5)

Depuis Terraform 1.5, vous pouvez déclarer un import directement dans le code HCL avec un bloc import. Cette approche est traçable dans le contrôle de version et reproductible en équipe.

import {
  to = libvirt_network.legacy
  id = "d227692a-646f-47a4-8b0a-fefbe48b6601"
}

resource "libvirt_network" "legacy" {
  name      = "legacy-manual-net"
  autostart = true
  # ... reste de la configuration
}

Le prochain terraform plan affiche :

  # libvirt_network.legacy will be updated in-place
  # (imported from "d227692a-646f-47a4-8b0a-fefbe48b6601")
  ~ resource "libvirt_network" "legacy" {
        autostart = true
        name      = "legacy-manual-net"
        ...
    }

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

Après le apply, la ressource est importée et le bloc import peut être retiré du code :

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

Commande vs bloc import

Critère	terraform import	Bloc import {}
Version minimale	Toutes	Terraform >= 1.5
Traçabilité VCS	Non (action ponctuelle)	Oui (dans le code)
Reproductibilité	Non	Oui (tout le monde applique)
Revue de code	Impossible	Possible via PR
Usage recommandé	Import rapide en solo	Projets en équipe

Glissez pour voir

Retirez le bloc import après apply

Une fois la ressource importée et le apply effectué, supprimez le bloc import de votre code. Il n’a plus d’utilité et pourrait porter à confusion.

Automatiser la détection de drift

Le flag -detailed-exitcode

terraform plan -detailed-exitcode retourne un code de sortie différent selon le résultat :

Code de sortie	Signification
0	Pas de changement — infrastructure synchronisée
1	Erreur lors du plan
2	Changements détectés — drift ou modifications à appliquer

Glissez pour voir

Quand l’infrastructure est synchronisée :

terraform plan -detailed-exitcode
echo "Exit code: $?"

No changes. Your infrastructure matches the configuration.
Exit code: 0

Quand un drift est détecté :

terraform plan -detailed-exitcode
echo "Exit code: $?"

  # libvirt_network.legacy will be updated in-place
  ~ resource "libvirt_network" "legacy" {
      ~ autostart = false -> true
        ...
    }

Plan: 0 to add, 1 to change, 0 to destroy.
Exit code: 2

Script de surveillance

Vous pouvez intégrer -detailed-exitcode dans un script CI/CD ou un cron pour détecter le drift automatiquement :

#!/bin/bash
terraform plan -detailed-exitcode -no-color > /dev/null 2>&1
EXIT_CODE=$?

case $EXIT_CODE in
  0)
    echo "OK : infrastructure synchronisée"
    ;;
  1)
    echo "ERREUR : impossible d'exécuter le plan"
    exit 1
    ;;
  2)
    echo "ALERTE : drift détecté, lancer terraform plan pour les détails"
    exit 2
    ;;
esac

Ce script peut être exécuté périodiquement par un pipeline CI/CD pour vous alerter dès qu’une modification manuelle désynchronise l’infrastructure.

Dépannage

Symptôme	Cause probable	Solution
Cannot import non-existent remote object	L’ID fourni ne correspond à aucune ressource existante	Vérifier l’ID exact (UUID, ARN, path) dans la console du provider
Plan affiche des changements après import	Le code HCL ne correspond pas exactement à la ressource réelle	Ajuster les attributs du bloc resource ou appliquer pour aligner
Resource already managed by Terraform	La ressource est déjà dans le state	Vérifier avec terraform state list avant d’importer ; si vous voulez la rattacher autrement, la retirer d’abord explicitement avec terraform state rm
refresh-only ne détecte rien	La ressource n’a pas été modifiée en dehors de Terraform	Comparer avec terraform state show et l’état réel
No state file was found	Aucun apply effectué	Lancer terraform apply d’abord pour créer le state
Format d’ID inconnu pour l’import	Chaque provider a son propre format	Consulter la doc du provider, section « Import » de chaque ressource

Glissez pour voir

À retenir

• Le drift est l’écart entre le state et l’infrastructure réelle — causé par des modifications manuelles ou externes
• terraform plan détecte le drift, terraform apply le corrige, terraform apply -refresh-only l’accepte
• terraform import rattache une ressource existante au state — le bloc resource doit exister dans le code avant l’import
• Le bloc import (Terraform >= 1.5) est l’alternative déclarative, traçable en VCS et reproductible en équipe
• Le format de l’ID d’import dépend du provider — consultez sa documentation
• -detailed-exitcode retourne 0 (synchronisé), 1 (erreur) ou 2 (drift) — idéal pour la CI/CD

Prochaines étapes

Sauvegarder et restaurer le state Protégez votre state avec pull, push, et les fichiers .backup automatiques.

Backends Terraform Configurez un backend distant pour le stockage et le verrouillage du state.

Comprendre le state Terraform Revenez aux fondamentaux : structure, rôle et fonctionnement du state.

×

📖 Voir la documentation →