Migrer de Terraform vers OpenTofu sans casser votre workflow

Migrer de Terraform vers OpenTofu est souvent beaucoup plus simple que re-ecrire une infrastructure. Dans la majorité des dépôts, le code HCL, les providers, les modules et même le state restent compatibles. Le vrai travail ne consiste donc pas a "convertir" les fichiers, mais a sécuriser la bascule : sauvegarder le state, vérifier les contraintes de version, remplacer la CLI dans les scripts, rejouer init et comparer un premier plan propre avant de toucher a la production.

Cette page vous guide dans cet ordre logique. Vous allez auditer ce qui dépend vraiment de Terraform, préparer une migration réversible, faire votre premier tofu init, vérifier ce qui change dans la CI et identifier les zones qui demandent plus d'attention, comme les backends, les registres privés ou l'écosystème HCP Terraform.

Ce que vous allez apprendre

préparer une migration prudente et réversible ;
repere les points de friction avant le premier tofu init ;
exécuter un plan de contrôle avant toute bascule irréversible ;
mettre a jour scripts, Makefile, CI/CD et habitudes d'equipe ;
distinguer ce qui reste compatible de ce qui demande une verification spécifique.

Pourquoi cette migration est plus simple qu'elle n'en a l'air

OpenTofu vise une forte compatibilité avec Terraform. Cela signifie que dans beaucoup de dépôts, vous n'avez pas a changer le HCL, ni a recréer vos ressources, ni a rearchitecturer vos modules. La migration ressemble donc moins a un "projet de refonte" qu'a une bascule d'outillage.

Le point de vigilance est ailleurs : tout ce qui vit autour du code. Vos pipelines, vos wrappers shell, vos vérifications de version, votre cache de plugins, vos miroirs de providers, vos habitudes de lockfile et vos integrations externes peuvent contenir des references implicites a terraform. C'est cette couche opérationnelle qu'il faut auditer methodiquement.

Ce qui ne change généralement pas

Dans un dépôt classique, les éléments suivants restent très souvent exploitables tels quels :

les fichiers .tf ;
la structure des modules ;
les ressources et data sources des providers courants ;
les variables, locals, outputs et fonctions HCL ;
le principe de state partage ;
le workflow general init -> plan -> apply -> destroy.

Autrement dit, si votre équipe sait déjà travailler avec Terraform, la migration consiste souvent a remplacer un binaire, a rejouer l'initialisation et a relire les écarts spécifiques d'OpenTofu avant de profiter de ses fonctions propres.

Prérequis

Avant de migrer, vous devez avoir :

un dépôt Terraform versionne dans Git ;
un accès au backend de state et a ses sauvegardes ;
une connaissance minimale du guide Terraform vs OpenTofu ;
OpenTofu installe sur votre poste ou dans votre runner ;
un plan clair pour la CI si votre équipe n'execute jamais les plans en local.

Vérifiez votre version OpenTofu :

tofu --version

Etape 1 - Auditer le dépôt avant toute bascule

Le premier objectif est de trouver tout ce qui dépend explicitement de terraform.

git grep -n "terraform"

Regardez surtout ces zones :

les scripts shell et les Makefile ;
les workflows GitHub Actions ou GitLab CI ;
les documents d'exploitation internes ;
les jobs qui publient ou lisent des plans ;
les images Docker contenant la CLI ;
les contraintes required_version dans les blocs terraform.

Ce qu'il faut vérifier dans `required_version`

Certaines équipes pinnaient Terraform de façon très stricte. Une contrainte trop etroite peut bloquer la migration même si le reste du code est compatible.

Exemple a relire avec attention :

terraform {
  required_version = "~> 1.5.7"
}

Une telle contrainte raconte une histoire précise : le dépôt attend une branche Terraform particulière. Avant de basculer, il faut décider si vous voulez :

conserver une contrainte stricte, mais adaptée a la branche OpenTofu cible ;
ou l'assouplir après revue.

Le point important est de ne pas laisser une contrainte ancienne bloquer tofu init alors que le code lui-même est compatible.

Etape 2 - Sauvegarder ce qui doit l'être vraiment

Avant le premier test, faites une vraie sauvegarde de travail :

Sauvegardez le code avec un commit ou une branche dédiée.
Sauvegardez le state depuis le backend ou via votre procédure habituelle.
Conservez le lockfile actuel si votre dépôt versionne .terraform.lock.hcl.
Notez le dernier plan Terraform sain si vous en avez un récent.

Cette etape n'est pas du theatre. Le state reste la mémoire de l'infrastructure. La migration est souvent simple, mais si vous devez comparer un comportement ou revenir en arrière, ces sauvegardes vous feront gagner du temps.

Etape 3 - Installer OpenTofu et basculer les automatismes locaux

Une fois le dépôt audite, remplacez les appels explicites a terraform par tofu dans vos scripts de travail.

Exemple de bascule simple :

sed -i 's/terraform /tofu /g' scripts/plan.sh

Ne faites pas cette substitution a l'aveugle sur tout le dépôt sans relire. Les references documentaires, les comparatifs ou les pages historiques n'ont pas toutes vocation a changer.

Le plus utile est d'identifier les commandes effectives :

terraform init
terraform plan
terraform apply
terraform output
terraform fmt
terraform validate
terraform import

Puis de les remplacer par leur équivalent OpenTofu dans les scripts opérationnels.

Etape 4 - Rejouer l'initialisation proprement

Le premier vrai test se fait avec tofu init. C'est lui qui revele les problèmes de backend, de providers, de modules et de lockfile.

tofu init

Si votre configuration utilise des variables dans un backend, dans des sources de modules ou dans un bloc encryption, fournissez-les des init :

tofu init -var-file=environments/dev.tfvars

Si vous modifiez la configuration du backend au passage, il peut être nécessaire d'indiquer explicitement l'intention :

tofu init -reconfigure

ou :

tofu init -migrate-state

Verification

Une initialisation saine doit :

détecter le backend attendu ;
installer les modules ;
résoudre les providers ;
mettre a jour ou relire .terraform.lock.hcl sans erreur inattendue.

Etape 5 - Faire un premier plan de contrôle

Une migration propre commence presque toujours par un plan qui ne doit pas annoncer de destruction surprise.

tofu plan

Lisez ce plan comme un plan d'audit, pas comme une simple formalite. Cherchez surtout :

des recreations inattendues ;
un backend mal résolu ;
un provider different de celui attendu ;
une contrainte de version trop stricte ;
des variables non passées a init ou a plan.

Si le plan est stable, vous avez la meilleure preuve que la bascule est en bonne voie. Si le plan n'est pas stable, ne forcez pas apply. Corrigez d'abord la cause.

Etape 6 - Mettre a jour la CI et les environnements d'exécution

Une fois le poste local valide, basculez les runners et les pipelines.

Points a vérifier dans la CI/CD :

image Docker ou binaire installe ;
cache de plugins ;
wrapper maison qui appelle encore terraform ;
jobs qui stockent un plan en artefact ;
checks de version dans les scripts ;
jobs fmt, validate, plan et apply.

Exemple d'enchainement minimal :

tofu fmt -check
tofu validate
tofu plan -out=tfplan

Si vous stockez un plan, souvenez-vous qu'il capture aussi le contexte de backend et qu'il doit être traite comme un artefact sensible.

Les cas qui demandent une verification spécifique

La plupart des dépôts migrent sans re-ecriture. En revanche, ces cas méritent une revue dédiée :

Cas	Pourquoi il faut vérifier
Backends sensibles	une mauvaise reinitialisation peut faire diverger la configuration locale et le backend
Registries ou miroirs privés	la configuration peut dépendre de `.terraformrc` ou d'un mirror spécifique
CI complètement non interactive	`tofu init` doit recevoir toutes ses variables des le départ
HCP Terraform / écosystème HashiCorp	l'intégration ne se traite pas comme une simple substitution de binaire
Dépôts multi-modules très anciens	le lockfile, les moves historiques et les scripts maison meriteront plus de lecture

Diagnostic rapide après migration

Symptôme	Cause probable	Action conseillée
`tofu init` echoue sur la version	contrainte `required_version` trop stricte	relire et ajuster la contrainte cible
`tofu plan` propose de recréer des ressources	backend, provider ou variables mal resolus	vérifier `init`, lockfile et valeurs d'entrée
la CI continue de lancer Terraform	image, action ou script non migre	rechercher `terraform` dans les jobs et wrappers
les modules ne se résolvent plus	source de module, mirror ou credentials a revoir	relire la configuration registry et CLI
un plan sauvegarde n'est plus exploitable	contexte de backend different entre plan et apply	regenerer le plan avec la configuration finale

A retenir

Migrer vers OpenTofu consiste souvent a basculer un workflow, pas a re-ecrire le HCL.
Le point de départ n'est pas apply, mais un audit du dépôt et un plan de contrôle propre.
Sauvegardez le state, le code et le lockfile avant toute bascule.
Les scripts, les runners et les integrations autour de la CLI sont les vraies zones a surveiller.
Si tofu plan est propre après tofu init, vous avez le meilleur signal que la migration est saine.

Prochaines étapes

Comparer Terraform et OpenTofu Revenir au cadrage global si vous devez encore justifier le choix de l'outil.

Chiffrer state et plans Passer ensuite a la fonction native la plus differenciante d'OpenTofu.

Variables dans init Comprendre les implications de `tofu init` quand vos backends et modules utilisent vars et locals.

Registry, CLI et OCI Industrialiser les installations de providers et modules après la migration initiale.