terraform state mv — déplacer ou renommer une ressource

terraform state mv renomme ou déplace une ressource dans le state sans détruire l’infrastructure réelle. Quand vous refactorisez votre code Terraform — renommer un bloc, extraire une ressource dans un module — cette commande évite un cycle destroy + recreate coûteux et risqué. Depuis Terraform 1.1, le bloc moved offre une alternative déclarative encore plus sûre.

Analogie

C’est comme renommer un fichier sur votre ordinateur : le contenu ne change pas, seul le chemin est mis à jour. state mv fait la même chose dans le state — l’infrastructure reste intacte, seule la référence est modifiée.

Prérequis : savoir utiliser terraform state list pour trouver l’adresse d’une ressource et terraform state show pour inspecter ses attributs.

Ce que vous allez apprendre

• Renommer une ressource avec terraform state mv
• Vérifier le résultat avec une simulation dry-run
• Déplacer une ressource vers un module
• Utiliser le bloc moved comme alternative déclarative (Terraform >= 1.1)
• Éviter les erreurs courantes de désynchronisation code/state

Syntaxe

terraform state mv [options] SOURCE DESTINATION

Paramètre	Rôle
SOURCE	Adresse actuelle de la ressource dans le state
DESTINATION	Nouvelle adresse souhaitée
-dry-run	Simule le déplacement sans modifier le state

Glissez pour voir

L’adresse suit le format type.nom pour une ressource racine ou module.nom_module.type.nom pour une ressource dans un module.

Renommer une ressource

Le cas le plus fréquent : vous améliorez la lisibilité de votre code en renommant un bloc. Sans state mv, Terraform détruirait l’ancienne ressource et en créerait une nouvelle.

1. Vérifier l’état initial

   Identifiez la ressource à renommer avec state list :

   terraform state list

   libvirt_network.net
   libvirt_volume.db
   libvirt_volume.web

2. Simuler le déplacement

   Utilisez -dry-run pour vérifier avant de modifier :

   terraform state mv -dry-run libvirt_volume.web libvirt_volume.frontend

   Would move "libvirt_volume.web" to "libvirt_volume.frontend"

   Aucune modification n’est faite — Terraform affiche ce qu’il ferait.

3. Exécuter le déplacement

   terraform state mv libvirt_volume.web libvirt_volume.frontend

   Move "libvirt_volume.web" to "libvirt_volume.frontend"
   Successfully moved 1 object(s).

4. Confirmer la nouvelle adresse

   terraform state list

   libvirt_network.net
   libvirt_volume.db
   libvirt_volume.frontend

   L’infrastructure n’a pas été touchée — seule la référence dans le state a changé.

5. Mettre à jour le code HCL

   Renommez le bloc dans votre fichier .tf pour correspondre au state :

   # Avant
   resource "libvirt_volume" "web" { ... }
   
   # Après
   resource "libvirt_volume" "frontend" { ... }

6. Vérifier la synchronisation

   terraform plan

   No changes. Your infrastructure matches the configuration.

   No changes confirme que le state et le code sont synchronisés. L’infrastructure est intacte.

Toujours mettre à jour le code après state mv

Si vous oubliez de renommer le bloc dans le code HCL, le prochain terraform plan affichera un destroy + create :

  # libvirt_volume.frontend will be destroyed
  # (because libvirt_volume.frontend is not in configuration)
  - resource "libvirt_volume" "frontend" { ... }

  # libvirt_volume.web will be created
  + resource "libvirt_volume" "web" { ... }

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

Terraform pense que frontend doit disparaître et web doit être créée. Le state mv est inutile sans la mise à jour du code.

Déplacer vers un module

Quand vous refactorisez votre code pour extraire une ressource dans un module, state mv évite la recréation. La destination utilise le préfixe module.<nom_module>. :

terraform state mv 'libvirt_volume.db' 'module.db_storage.libvirt_volume.disk'

Move "libvirt_volume.db" to "module.db_storage.libvirt_volume.disk"
Successfully moved 1 object(s).

La vérification confirme le résultat :

terraform state list

libvirt_network.net
libvirt_volume.frontend
module.db_storage.libvirt_volume.disk

Un terraform plan après mise à jour du code confirme : No changes.

Déplacement dans l'autre sens

Le déplacement fonctionne dans les deux directions. Pour sortir une ressource d’un module vers la racine :

terraform state mv 'module.db_storage.libvirt_volume.disk' 'libvirt_volume.db'

Alternative déclarative : le bloc moved

Depuis Terraform 1.1, le bloc moved permet de déclarer un renommage directement dans le code HCL. Terraform gère le déplacement automatiquement au prochain apply — sans commande manuelle.

resource "libvirt_volume" "web_disk" {
  name     = "web-server.qcow2"
  pool     = "default"
  capacity = 4294967296
  # ...
}

moved {
  from = libvirt_volume.frontend
  to   = libvirt_volume.web_disk
}

Le terraform plan affiche clairement le déplacement prévu :

  # libvirt_volume.frontend has moved to libvirt_volume.web_disk
    resource "libvirt_volume" "web_disk" {
        id   = "/var/lib/libvirt/images/web-server.qcow2"
        name = "web-server.qcow2"
        # (8 unchanged attributes hidden)
    }

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

Un terraform apply finalise le déplacement — 0 destruction, 0 création :

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

Le bloc moved fonctionne aussi pour accompagner un refactoring vers un module :

moved {
  from = libvirt_volume.db
  to   = module.db_storage.libvirt_volume.disk
}

Cette approche est souvent plus sûre qu’une commande manuelle quand le déplacement fait partie d’une refonte versionnée dans Git.

state mv ou moved : lequel choisir ?

Critère	terraform state mv	Bloc moved
Version minimale	Toutes	Terraform >= 1.1
Mode	Impératif (commande CLI)	Déclaratif (dans le code)
Traçabilité	Aucune trace dans le code	Visible dans l’historique Git
Collaboration	Chaque membre doit exécuter la commande	Automatique pour toute l’équipe
Risque d’oubli	Élevé (code à mettre à jour manuellement)	Faible (code et déplacement couplés)
Backends distants	Fonctionne partout	Fonctionne partout

Glissez pour voir

Recommandation

Privilégiez le bloc moved quand vous travaillez en équipe. Le déplacement est versionné dans Git et s’applique automatiquement pour chaque membre de l’équipe au prochain terraform apply. Vous pouvez supprimer le bloc moved une fois que chaque environnement a appliqué le changement.

Erreur : adresse source invalide

Si l’adresse source n’existe pas dans le state, Terraform refuse le déplacement :

terraform state mv libvirt_volume.inexistant libvirt_volume.autre

╷
│ Error: Invalid source address
│
│ Cannot move libvirt_volume.inexistant: does not match anything in the current
│ state.
╵

Vérifiez toujours l’adresse exacte avec terraform state list avant un state mv.

Dépannage

Symptôme	Cause probable	Solution
Invalid source address	L’adresse source n’existe pas dans le state	Vérifier avec terraform state list
Plan affiche destroy + create après mv	Le code HCL n’a pas été mis à jour	Renommer le bloc dans le .tf pour correspondre
Cannot move to address already in state	La destination existe déjà	Choisir un autre nom ou retirer l’existant d’abord
No state file was found	Aucun apply effectué	Lancer terraform apply d’abord
Le moved block ne fonctionne pas	Version Terraform < 1.1	Mettre à jour ou utiliser state mv

Glissez pour voir

À retenir

• terraform state mv renomme ou déplace une ressource dans le state sans toucher à l’infrastructure
• Utilisez -dry-run pour simuler avant de modifier le state
• Pensez toujours à mettre à jour le code HCL après un state mv — sinon le prochain plan détruira et recréera la ressource
• Le déplacement vers un module utilise le préfixe module.<nom>. dans l’adresse destination
• Le bloc moved (Terraform >= 1.1) est l’alternative déclarative recommandée en équipe — traçable et automatique
• Un terraform plan qui affiche No changes confirme que le renommage est réussi

Prochaines étapes

terraform state rm Retirer une ressource du state sans la détruire.

Sauvegarder et restaurer le state Manipuler le state avec pull, push, et les sauvegardes automatiques.

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

×

📖 Voir la documentation →