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 majorite des depots, le code HCL, les providers, les modules et meme le state restent compatibles. Le vrai travail ne consiste donc pas a “convertir” les fichiers, mais a securiser la bascule : sauvegarder le state, verifier 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 depend vraiment de Terraform, preparer une migration reversible, faire votre premier tofu init, verifier ce qui change dans la CI et identifier les zones qui demandent plus d’attention, comme les backends, les registres prives ou l’ecosysteme HCP Terraform.

Ce que vous allez apprendre

preparer une migration prudente et reversible ;
repere les points de friction avant le premier tofu init ;
executer un plan de controle avant toute bascule irreversible ;
mettre a jour scripts, Makefile, CI/CD et habitudes d’equipe ;
distinguer ce qui reste compatible de ce qui demande une verification specifique.

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

OpenTofu vise une forte compatibilite avec Terraform. Cela signifie que dans beaucoup de depots, vous n’avez pas a changer le HCL, ni a recreer 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 verifications 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 operationnelle qu’il faut auditer methodiquement.

Ce qui ne change generalement pas

Dans un depot classique, les elements suivants restent tres 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 equipe sait deja travailler avec Terraform, la migration consiste souvent a remplacer un binaire, a rejouer l’initialisation et a relire les ecarts specifiques d’OpenTofu avant de profiter de ses fonctions propres.

Prerequis

Avant de migrer, vous devez avoir :

un depot Terraform versionne dans Git ;
un acces 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 equipe n’execute jamais les plans en local.

Verifiez votre version OpenTofu :

tofu --version

Etape 1 - Auditer le depot avant toute bascule

Le premier objectif est de trouver tout ce qui depend 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 verifier dans `required_version`

Certaines equipes pinnaient Terraform de facon tres stricte. Une contrainte trop etroite peut bloquer la migration meme si le reste du code est compatible.

Exemple a relire avec attention :

terraform {
  required_version = "~> 1.5.7"
}

Une telle contrainte raconte une histoire precise : le depot attend une branche Terraform particuliere. Avant de basculer, il faut decider si vous voulez :

conserver une contrainte stricte, mais adaptee a la branche OpenTofu cible ;
ou l’assouplir apres revue.

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

Etape 2 - Sauvegarder ce qui doit l’etre vraiment

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

Sauvegardez le code avec un commit ou une branche dediee.
Sauvegardez le state depuis le backend ou via votre procedure habituelle.
Conservez le lockfile actuel si votre depot versionne .terraform.lock.hcl.
Notez le dernier plan Terraform sain si vous en avez un recent.

Cette etape n’est pas du theatre. Le state reste la memoire de l’infrastructure. La migration est souvent simple, mais si vous devez comparer un comportement ou revenir en arriere, ces sauvegardes vous feront gagner du temps.

Etape 3 - Installer OpenTofu et basculer les automatismes locaux

Une fois le depot 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 depot 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 equivalent OpenTofu dans les scripts operationnels.

Etape 4 - Rejouer l’initialisation proprement

Le premier vrai test se fait avec tofu init. C’est lui qui revele les problemes 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 etre necessaire d’indiquer explicitement l’intention :

tofu init -reconfigure

ou :

tofu init -migrate-state

Verification

Une initialisation saine doit :

detecter le backend attendu ;
installer les modules ;
resoudre les providers ;
mettre a jour ou relire .terraform.lock.hcl sans erreur inattendue.

Etape 5 - Faire un premier plan de controle

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 resolu ;
un provider different de celui attendu ;
une contrainte de version trop stricte ;
des variables non passees 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’execution

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

Points a verifier 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 etre traite comme un artefact sensible.

Les cas qui demandent une verification specifique

La plupart des depots migrent sans re-ecriture. En revanche, ces cas meritent une revue dediee :

Cas	Pourquoi il faut verifier
Backends sensibles	une mauvaise reinitialisation peut faire diverger la configuration locale et le backend
Registries ou miroirs prives	la configuration peut dependre de `.terraformrc` ou d’un mirror specifique
CI completement non interactive	`tofu init` doit recevoir toutes ses variables des le depart
HCP Terraform / ecosysteme HashiCorp	l’integration ne se traite pas comme une simple substitution de binaire
Depots multi-modules tres anciens	le lockfile, les moves historiques et les scripts maison meriteront plus de lecture

Diagnostic rapide apres migration

Symptome	Cause probable	Action conseillee
`tofu init` echoue sur la version	contrainte `required_version` trop stricte	relire et ajuster la contrainte cible
`tofu plan` propose de recreer des ressources	backend, provider ou variables mal resolus	verifier `init`, lockfile et valeurs d’entree
la CI continue de lancer Terraform	image, action ou script non migre	rechercher `terraform` dans les jobs et wrappers
les modules ne se resolvent 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 depart n’est pas apply, mais un audit du depot et un plan de controle 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 apres tofu init, vous avez le meilleur signal que la migration est saine.

Prochaines etapes

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 apres la migration initiale.