OpenTofu : refactor, import, moved et removed

Le vrai sujet d'une infrastructure IaC n'est pas seulement "créer des ressources", mais les faire evoluer sans casser leur historique. Vous renommez un module, vous passez une ressource vers for_each, vous reprenez une ressource existante créée hors du state, ou vous voulez retirer un objet de la configuration sans le detruire. Sans aide explicite, OpenTofu voit souvent ces changements comme un vieux bloc a detruire et un nouveau bloc a créer.

OpenTofu propose plusieurs outils pour rendre ces transitions declaratives : import, moved et removed. Le plus important est de leur donner le bon role. import sert a raccrocher un objet existant a votre state. moved sert a dire qu'un objet a change d'adresse logique. removed sert a dire qu'un objet doit sortir de la configuration, avec ou sans destruction selon votre intention. Cette page vous montre comment les combiner proprement sur des dépôts qui vivent longtemps.

Ce que vous allez apprendre

choisir entre commande d'import et import block ;
utiliser moved pour renommer ou redistribuer des ressources ;
utiliser removed pour oublier un objet sans le detruire ;
faire evoluer des ressources ou modules avec count et for_each ;
garder un historique de refactor clair pour les mainteneurs suivants.

Pourquoi ces blocs existent

OpenTofu raisonne principalement avec les adresses des objets dans le state. Si vous changez une adresse sans explication, il ne peut pas deviner s'il s'agit :

du même objet deplace ;
d'un objet a importer ;
d'un objet a oublier ;
ou d'un objet a recréer.

Les blocs de refactor existent donc pour transformer une intention implicite en intention déclarative et lisible.

1 - `import` : reprendre un objet déjà existant

OpenTofu dispose de deux façons principales d'importer :

la commande tofu import ;
le import block dans la configuration.

L'approche la plus interessante pour les équipes et la CI est souvent le import block, car elle est visible dans le code et passe par le cycle normal plan -> apply.

Exemple minimal avec `import` block

import {
  to = aws_instance.example
  id = "i-abcd1234"
}

resource "aws_instance" "example" {
  ami           = "ami-12345678"
  instance_type = "t3.micro"
}

Le point important est le suivant : il faut déjà une configuration de ressource. OpenTofu n'accepte pas un import sans savoir dans quel bloc la ressource devra vivre.

Quand préférer `import` block a `tofu import`

Situation	Bon choix
operation ponctuelle en local	`tofu import`
revue en équipe	`import` block
pipeline CI/CD	`import` block
imports multiples et historisation du changement	`import` block

Exemple avec module et `for_each`

OpenTofu permet aussi :

import {
  to = module.instances.aws_instance.example
  id = "i-abcd1234"
}

ou encore :

import {
  to = aws_instance.example["blue"]
  id = "i-abcd1234"
}

2 - `moved` : dire qu'un objet a change d'adresse

Le bloc moved sert a expliquer qu'un objet déjà connu du state doit être considere comme le même objet, mais a une nouvelle adresse logique.

Syntaxe minimale :

moved {
  from = aws_instance.old_name
  to   = aws_instance.new_name
}

Renommer une ressource

resource "aws_instance" "web" {
  ami           = "ami-12345678"
  instance_type = "t3.micro"
}

moved {
  from = aws_instance.app
  to   = aws_instance.web
}

OpenTofu comprend alors que aws_instance.app n'est pas a detruire, mais a re-interpreter comme aws_instance.web.

Passer d'une ressource simple a `for_each`

locals {
  instances = {
    blue = { instance_type = "t3.micro" }
  }
}

resource "aws_instance" "web" {
  for_each      = local.instances
  ami           = "ami-12345678"
  instance_type = each.value.instance_type
}

moved {
  from = aws_instance.web
  to   = aws_instance.web["blue"]
}

Le cas d'usage est très fréquent : vous partez d'une ressource unique, puis vous generalisez avec for_each.

Renommer un appel de module

module "network_v2" {
  source = "../modules/network"
}

moved {
  from = module.network
  to   = module.network_v2
}

Ici encore, l'objectif n'est pas de créer un nouveau module, mais de conserver le lien historique entre les adresses.

3 - `moved` pour des refactors plus lourds

Le bloc moved devient encore plus utile quand vous :

transformez un count en for_each ;
decoupez un gros module en plusieurs petits modules ;
enchaînez plusieurs renommages dans le temps.

Exemple de chaîne de moves

moved {
  from = aws_instance.a
  to   = aws_instance.b
}

moved {
  from = aws_instance.b
  to   = aws_instance.c
}

Cette écriture garde un historique d'upgrade plus robuste qu'un seul move ecrasant les étapes intermédiaires.

Pourquoi il ne faut pas supprimer trop vite les `moved`

Retirer un moved trop tot est souvent une breaking change. Un utilisateur qui saute une version intermediaire n'aura plus l'information nécessaire pour relier l'ancienne adresse a la nouvelle.

Le bon réflexe est donc de conserver les moved tant que vous n'avez pas la certitude que tous les consommateurs ont applique la migration voulue.

4 - `removed` : sortir un objet de la configuration sans toujours le detruire

Le bloc removed sert a dire qu'un objet doit quitter la configuration. C'est utile si vous voulez oublier une ressource ou un module dans le state sans la destruction correspondante.

Exemple pour une ressource

removed {
  from = aws_instance.web

  lifecycle {
    destroy = false
  }
}

Avec destroy = false, OpenTofu retirera l'objet du state sans demander sa destruction dans le système distant.

Exemple pour un module

removed {
  from = module.legacy_network

  lifecycle {
    destroy = false
  }
}

Pour un module, l'idée est la même. Vous oubliez le module dans la configuration et dans le state, sans toucher aux objets gérés a distance.

Ce qu'il faut retenir sur `removed`

lifecycle n'est pas strictement obligatoire, mais il est fortement recommande ;
destroy = false sert a oublier sans detruire ;
destroy = true documente explicitement une suppression volontaire ;
les removed pointant vers des modules n'acceptent pas de provisioners ;
pour une ressource, un removed peut inclure un provisioner si la destruction est voulue.

5 - Scenario type de refactor propre

Voici un enchaînement sain sur une configuration existante :

Importer les objets qui existent hors state avec import ou tofu import.
Stabiliser la configuration avec un plan propre.
Refactorer ensuite les adresses avec moved.
Sortir enfin certains objets de la configuration avec removed si l'objectif est de les oublier sans les detruire.
Conserver les moved utiles aussi longtemps que le chemin d'upgrade doit rester compatible.

Ce sequence évite le piège classique qui consiste a faire un gros refactor structurel avant même d'avoir raccroche correctement les objets au state.

6 - Ne pas oublier la deprecation des variables et outputs

Les refactors ne concernent pas seulement les ressources. OpenTofu supporte aussi des messages de deprecation sur les variables et outputs d'un module, ce qui aide a accompagner les consommateurs vers une nouvelle interface sans tout casser d'un coup.

Cette approche ne remplace pas moved, mais elle complète une stratégie de migration progressive pour les modules très utilisés.

Dépannage

Symptôme	Cause probable	Solution
un renommage provoque une recréation	absence de `moved` ou mauvais adressage	ajouter un `moved` correct puis relire le plan
import block refuse de planifier	resource block absent ou insuffisant	définir la ressource cible avant l'import
plusieurs adresses gèrent le même objet	import fait deux fois vers des adresses différentes	choisir une seule adresse canonique et nettoyer le state
un objet sort du state alors qu'il devait être détruit	`removed` avec `destroy = false` utilise par erreur	corriger l'intention de destruction et relire le plan
un vieux consommateur casse a la mise a jour	`moved` retire trop tot	restaurer le move ou documenter une migration intermediaire

A retenir

import sert a reprendre un objet existant dans le state.
moved sert a conserver un objet tout en changeant son adresse logique.
removed sert a sortir un objet de la configuration, avec ou sans destruction selon lifecycle.destroy.
Les refactors propres se lisent d'abord dans le plan, pas au moment du apply surprise.
Garder l'historique des migrations dans le code aide les prochains mainteneurs autant que l'outillage lui-même.

Prochaines étapes

Migrer depuis Terraform Replacer ces refactors dans une bascule plus large de dépôt, de scripts et de CI.

Registry, CLI et OCI Comprendre ensuite comment l'installation des modules et providers influe sur ces refactors.

Import, moved et drift avec Terraform Comparer avec un guide Terraform concret si vous voulez revoir les fondamentaux opérationnels du sujet.

Variables dans init Voir pourquoi certains imports et refactors demandent aussi des valeurs disponibles des `tofu init`.