Déboguer un terraform apply

Votre terraform apply échoue avec un message en rouge. Le fichier, la ligne et le type de problème sont indiqués — encore faut-il savoir les lire. Une fois cette compétence acquise, vous trouvez la cause en quelques secondes.

Terraform signale ses erreurs avec précision : fichier, ligne, type de problème, et souvent une suggestion de correction. Les erreurs se répartissent en 4 catégories prévisibles, chacune avec son reflexe de correction. Ce guide les présente avec les messages exacts produits en lab.

Ce que vous allez apprendre :

• Lire la structure d’un message d’erreur Terraform
• Diagnostiquer par catégorie : attribut inconnu, référence manquante, type incorrect, erreur runtime
• Appliquer le workflow validate → plan → apply pour économiser du temps
• Provoquer et corriger une erreur réelle dans un lab

Prérequis : avoir suivi le guide Première infrastructure.

Lire un message d’erreur Terraform

Avant de catégoriser les erreurs, voici la structure d’un message d’erreur Terraform :

Error: Unsupported argument
│
│   on bad.tf line 4, in resource "libvirt_volume" "bad":
│    4:   format = "qcow2"
│
│ An argument named "format" is not expected here.

Chaque message comporte :

• Le type d’erreur en gras (Unsupported argument)
• La localisation exacte : fichier + numéro de ligne + bloc concerné
• L’extrait de code fautif
• L’explication en langage naturel

Commencez toujours par lire la dernière ligne du message — c’est là que se trouve la réponse.

Workflow de débogage

L'ordre diagnostic

Avant de chercher dans la documentation, appliquez cet ordre :

1. terraform validate — détecte les erreurs de syntaxe et de schéma sans contacter le provider
2. terraform plan — détecte les erreurs logiques et de dépendance sans modifier l’infrastructure
3. terraform apply — révèle les erreurs runtime (ressource déjà existante, permissions…)

Résoudre les erreurs dans cet ordre économise du temps : inutile de faire un apply si validate échoue.

À retenir

terraform validate est gratuit : il ne contacte pas le provider et ne modifie rien. Lancez-le systématiquement après chaque modification de code.

terraform validate    # 1. Syntaxe et schéma
terraform plan        # 2. Logique et dépendances
terraform apply       # 3. Runtime

Catégorie 1 : attribut inconnu ou mal placé

C’est l’erreur la plus courante quand on migre d’une ancienne version du provider à une nouvelle, ou quand on copie-colle du code sans vérifier le schéma.

Erreur réelle capturée en lab :

# bad.tf — erreur volontaire
resource "libvirt_volume" "bad" {
  name   = "bad.qcow2"
  pool   = "default"
  format = "qcow2"    # ← attribut au mauvais endroit
}

terraform validate

Error: Unsupported argument
│
│   on bad.tf line 4, in resource "libvirt_volume" "bad":
│    4:   format = "qcow2"
│
│ An argument named "format" is not expected here.

Cause : Dans libvirt provider v0.9.7, le format d’un volume se déclare dans target.format.type, pas directement à la racine de la ressource.

Correction :

resource "libvirt_volume" "bad" {
  name   = "bad.qcow2"
  pool   = "default"
  target = {
    format = { type = "qcow2" }  # ← emplacement correct
  }
}

Réflexe : quand le message dit “not expected here”, consultez le schéma du provider dans la documentation ou avec terraform providers schema.

terraform providers schema -json | python3 -m json.tool | grep -A5 '"libvirt_volume"'

À retenir — Attribut inconnu

“Unsupported argument” signifie que l’attribut n’existe pas à cet endroit du schéma. La correction consiste à le placer dans le bon bloc imbriqué. Consultez terraform providers schema -json pour trouver l’emplacement correct.

Catégorie 2 : référence à une ressource inexistante

Terraform résout les références entre ressources lors du validate. Si la ressource référencée n’existe pas, l’erreur est immédiate.

Erreur :

resource "libvirt_domain" "bad" {
  devices = {
    disks = [{
      source = { file = { file = libvirt_volume.missing.path } }
      #                         ↑ "missing" n'est pas déclaré
    }]
  }
}

Error: Reference to undeclared resource
│
│   on bad.tf line 4, in resource "libvirt_domain" "bad":
│    4:     source = { file = { file = libvirt_volume.missing.path } }
│
│ A managed resource "libvirt_volume" "missing" has not been declared
│ in the root module.

Causes fréquentes :

• Faute de frappe dans le nom (libvirt_volume.disk vs libvirt_volume.dsk)
• La ressource est dans un autre fichier qui n’a pas encore été créé
• Le nom a changé lors d’un refactoring

Correction : Vérifiez les noms avec terraform state list si les ressources existent déjà, ou cherchez la déclaration dans vos fichiers .tf.

À retenir — Référence manquante

“Reference to undeclared resource” est souvent une faute de frappe. Comparez le nom exact dans la référence avec la déclaration resource. Un grep dans vos fichiers .tf suffit à trouver l’écart.

Catégorie 3 : type de valeur incorrect

Terraform est typé. Si une variable attend un number et reçoit une string, l’erreur est détectée à la validation.

Erreur :

resource "libvirt_domain" "bad" {
  memory = "512"    # ← string au lieu de number
}

Error: Incorrect attribute value type
│
│   on bad.tf line 3, in resource "libvirt_domain" "bad":
│    3:   memory = "512"
│
│ Inappropriate value for attribute "memory": a number is required.

Correction : memory = 512 (sans guillemets).

À retenir — Type incorrect

“Incorrect attribute value type” : vérifiez la présence ou l’absence de guillemets. En HCL, "512" est une string, 512 est un number.

Types de base en HCL

• string : entre guillemets — "lab02-vm"
• number : sans guillemets — 512
• bool : sans guillemets — true ou false

Les guillemets transforment n’importe quelle valeur en chaîne. "512" est une string, 512 est un number.

Catégorie 4 : erreurs runtime (après validate et plan)

Certaines erreurs n’apparaissent qu’à terraform apply, quand Terraform interagit réellement avec le provider :

Ressource déjà existante :

Error: Error creating libvirt network: Domain already exists lab14-net

Cela arrive quand la ressource existe dans libvirt mais pas dans le state Terraform (par exemple, après un crash pendant un apply précédent).

Solutions selon la situation :

Situation	Solution
La ressource a été créée manuellement	terraform import pour l’adopter
Le state a été perdu	Recréer le state avec terraform import
Doublon involontaire	Supprimer la ressource manuellement, puis apply

Glissez pour voir

Permission refusée :

Error: virError(Code=1, Domain=10, Message='authentication failed')

Vérifiez que l’utilisateur a accès à qemu:///system :

groups $USER | grep -q libvirt || sudo usermod -aG libvirt $USER

Image de base absente :

Error: error creating libvirt volume: internal error: ...
Cannot access storage file '/chemin/vers/ubuntu-24.04-cloudimg.img'

L’image de base n’existe pas au chemin indiqué. Vérifiez :

ls -lh ~/images/ubuntu-24.04-cloudimg.img

À retenir — Erreurs runtime

Les erreurs runtime ne sont détectées ni par validate ni par plan. Elles apparaissent uniquement à terraform apply quand le provider interagit avec l’infrastructure réelle. Les causes typiques : ressource déjà existante, permissions insuffisantes, fichier absent.

Lab : provoquer et corriger une erreur

1. Créez un répertoire de test :

   mkdir -p ~/terraform-debug-apply
   cd ~/terraform-debug-apply

2. Créez versions.tf (correct) puis bad.tf avec une erreur volontaire :

   cat > bad.tf << 'EOF'
   resource "libvirt_volume" "bad" {
     name   = "bad.qcow2"
     pool   = "default"
     format = "qcow2"
   }
   EOF

3. Lancez le validate pour voir l’erreur :

   terraform init
   terraform validate

   Error: Unsupported argument
   │   on bad.tf line 4, in resource "libvirt_volume" "bad":
   │    4:   format = "qcow2"
   │ An argument named "format" is not expected here.

4. Corrigez le fichier :

   cat > bad.tf << 'EOF'
   resource "libvirt_volume" "bad" {
     name   = "bad.qcow2"
     pool   = "default"
     target = { format = { type = "qcow2" } }
     create = { content = { url = pathexpand("~/images/ubuntu-24.04-cloudimg.img") } }
   }
   EOF
   terraform validate
   # → Success! The configuration is valid.

5. Supprimez le fichier de test et nettoyez :

   rm bad.tf

Outils de diagnostic utiles

Commande	Utilité
terraform validate	Vérifie syntaxe et schéma (rapide, sans accès provider)
terraform plan	Montre ce qui sera créé/modifié/détruit
terraform show	Affiche l’état actuel des ressources
terraform state list	Liste toutes les ressources dans le state
TF_LOG=DEBUG terraform apply	Active les logs détaillés pour les erreurs obscures
terraform providers schema -json	Affiche le schéma complet de tous les providers

Glissez pour voir

Pour les erreurs difficiles à diagnostiquer, TF_LOG=DEBUG affiche toutes les requêtes API envoyées au provider :

TF_LOG=DEBUG terraform apply 2>&1 | grep -i error

TF_LOG : à utiliser avec modération

Le niveau DEBUG génère des centaines de lignes. Filtrez avec grep ou redirigez vers un fichier : TF_LOG=DEBUG terraform apply 2>debug.log

Les niveaux disponibles, du moins au plus verbeux : ERROR, WARN, INFO, DEBUG, TRACE.

À retenir

• Lisez toujours la dernière ligne d’un message d’erreur Terraform — c’est là que se trouve l’explication.
• L’ordre de diagnostic : validate → plan → apply.
• Unsupported argument : l’attribut n’existe pas ou est mal placé dans la hiérarchie.
• Reference to undeclared resource : faute de frappe ou ressource manquante.
• Incorrect attribute value type : guillemets en trop ou manquants.
• Les erreurs runtime apparaissent à apply et concernent l’état réel de l’infrastructure.

Prochaines étapes

Provisionner avec Ansible Connecter Terraform et Ansible pour configurer automatiquement vos VM après création.

Comprendre le state Terraform Comment Terraform mémorise l'infrastructure et pourquoi le state est critique.

×

📖 Voir la documentation →