terraform state rm, retirer une ressource du state

terraform state rm retire une ressource du state sans la détruire dans l'infrastructure réelle. L'inverse d'un import : la ressource continue d'exister, mais Terraform cesse de la gérer. C'est la commande indispensable quand vous voulez « dé-manager » une ressource, par exemple pour la rattacher à un autre projet Terraform ou la gérer manuellement. Depuis Terraform 1.7, le bloc removed offre une alternative déclarative.

Analogie

Imaginez un carnet d'adresses. state rm efface l'entrée du carnet, mais la personne existe toujours. Vous perdez juste la trace, si vous avez besoin de la re-contacter, il faudra la réimporter (terraform import).

Prérequis : savoir utiliser terraform state list et terraform state show pour identifier la ressource à retirer.

Ce que vous allez apprendre

• Retirer une ressource du state avec terraform state rm
• Simuler avec -dry-run avant de modifier
• Synchroniser le code HCL après le retrait
• Utiliser le bloc removed comme alternative déclarative (Terraform >= 1.7)
• Comprendre les conséquences : ressource orpheline vs ressource détruite

Syntaxe

terraform state rm [options] ADRESSE

Paramètre	Rôle
ADRESSE	Adresse de la ressource à retirer (ex : libvirt_volume.db)
-dry-run	Simule le retrait sans modifier le state

Glissez pour voir

Retirer une ressource du state

Le scénario type : un volume a été créé par Terraform, mais vous décidez de le gérer manuellement ou de le rattacher à un autre projet.

1. Identifier la ressource à retirer

   terraform state list

   libvirt_network.net
   libvirt_volume.db
   libvirt_volume.web

2. Simuler le retrait

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

   terraform state rm -dry-run libvirt_volume.db

   Would remove libvirt_volume.db

3. Exécuter le retrait

   terraform state rm libvirt_volume.db

   Removed libvirt_volume.db
   Successfully removed 1 resource instance(s).

4. Vérifier le state

   terraform state list

   libvirt_network.net
   libvirt_volume.web

   Le volume db n'apparaît plus dans le state.

5. Confirmer que l'infrastructure existe toujours

   La ressource physique est intacte, state rm ne touche jamais l'infrastructure :

   ls -la /var/lib/libvirt/images/db-server.qcow2

   -rw------- 1 root root 196672 mars  31 14:24 /var/lib/libvirt/images/db-server.qcow2

Attention : le code HCL décrit encore la ressource

Après un state rm, si le bloc resource reste dans votre code, le prochain terraform plan tentera de recréer la ressource :

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

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

Terraform ne sait plus que cette ressource existe, il veut la créer à nouveau. Vous devez supprimer le bloc du code ou, si la ressource existe déjà, l'apply échouera avec un conflit de nom.

Synchroniser le code après state rm

Pour obtenir un plan propre, supprimez le bloc resource correspondant du fichier .tf :

# Supprimer ce bloc après state rm
resource "libvirt_volume" "db" {
  name = "db-server.qcow2"
  # ...
}

Puis vérifiez :

terraform plan

No changes. Your infrastructure matches the configuration.

Alternative déclarative : le bloc removed

Depuis Terraform 1.7, le bloc removed permet de retirer une ressource du state directement dans le code HCL. Plus besoin de commande manuelle, le retrait s'applique automatiquement au prochain apply.

Remplacez le bloc resource par un bloc removed :

removed {
  from = libvirt_volume.web

  lifecycle {
    destroy = false
  }
}

Le lifecycle { destroy = false } indique à Terraform de retirer la ressource du state sans la détruire. Le plan affiche clairement l'intention :

 # libvirt_volume.web will no longer be managed by Terraform,
 # but will not be destroyed
 # (destroy = false is set in the configuration)
 . resource "libvirt_volume" "web" {
        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 retrait :

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

La ressource est sortie du state mais existe toujours dans l'infrastructure. Le warning de Terraform le confirme :

Warning: Some objects will no longer be managed by Terraform

If you apply this plan, Terraform will discard its tracking information
for the following objects, but it will not delete them:
 - libvirt_volume.web

After applying this plan, Terraform will no longer manage these objects.
You will need to import them into Terraform to manage them again.

Ne retirez pas destroy = false par inadvertance

Si vous supprimez lifecycle { destroy = false }, vous perdez le garde-fou explicite qui transforme l'opération en simple retrait du state. Le plan redevient alors une suppression classique de la ressource gérée. Gardez cette ligne tant que votre intention est bien de conserver l'infrastructure existante.

state rm ou removed : lequel choisir ?

Critère	terraform state rm	Bloc removed
Version minimale	Toutes	Terraform >= 1.7
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
Sécurité	Risque d'oublier de mettre à jour le code	Code auto-synchronisé
Possibilité de détruire	Non, retrait pur	Configurable via destroy = true

Glissez pour voir

Recommandation

Privilégiez le bloc removed en équipe. Le retrait est versionné dans Git et le lifecycle { destroy = false } rend l'intention explicite. Supprimez le bloc removed une fois que chaque environnement a appliqué le changement.

Cas d'usage courants

Besoin	Solution
Cesser de gérer une ressource créée manuellement avant Terraform	state rm puis supprimer le bloc
Transférer une ressource à un autre projet Terraform	state rm dans le projet A, terraform import dans le projet B
Supprimer le suivi d'une data source	state rm data.type.nom
Retirer un module complet	state rm 'module.nom_module'

Glissez pour voir

Erreur : adresse inexistante

Si l'adresse n'existe pas dans le state :

terraform state rm libvirt_volume.inexistant

╷
│ Error: Invalid target address
│
│ No matching objects found. To view the available instances, use "terraform
│ state list". Please modify the address to reference a specific instance.
╵

Vérifiez toujours l'adresse avec terraform state list.

Dépannage

Symptôme	Cause probable	Solution
Invalid target address	L'adresse n'existe pas dans le state	Vérifier avec terraform state list
Plan veut recréer la ressource après rm	Le bloc resource est encore dans le code	Supprimer le bloc du .tf
L'apply échoue avec un conflit de nom	La ressource physique existe déjà (même nom)	state rm + supprimer le bloc, ou terraform import
No state file was found	Aucun apply effectué	Lancer terraform apply d'abord
Le removed block ne fonctionne pas	Version Terraform < 1.7	Mettre à jour ou utiliser state rm

Glissez pour voir

À retenir

• terraform state rm retire une ressource du state uniquement, l'infrastructure réelle n'est pas touchée
• Utilisez -dry-run pour simuler le retrait avant de modifier le state
• Après un state rm, supprimez le bloc du code HCL pour éviter une recréation au prochain plan
• Le bloc removed (Terraform >= 1.7) est l'alternative déclarative, avec lifecycle { destroy = false } pour empêcher la destruction
• Pour re-gérer une ressource retirée, utilisez terraform import
• C'est l'opération inverse de terraform import : import ajoute au state, rm retire du state

Prochaines étapes

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.

terraform state mv Renommer ou déplacer une ressource sans la recréer.

×

📖 Voir la documentation →