Mettre à jour sans casser

Pourquoi

Une infrastructure décrite en code est un logiciel, et un logiciel vieillit. Terraform publie une version mineure tous les quelques mois ; les fournisseurs publient presque chaque semaine ; les modules de la leçon 3 évoluent ; OpenTofu avance en parallèle avec ses propres fonctionnalités. Une équipe qui n'a rien mis à jour pendant un an se retrouve devant un mur : un fournisseur trop ancien ne sait plus parler à l'API de Scaleway, une faille de sécurité est corrigée dans une version que le code n'accepte pas, et le saut de dix versions d'un coup produit un plan illisible.

À l'inverse, une équipe qui met à jour sans méthode finit par appliquer un plan qui remplace la base de données, parce qu'un changement de comportement du fournisseur est passé inaperçu. La solution tient en trois principes : épingler pour que rien ne change sans qu'on l'ait décidé, mettre à jour souvent et par petits pas pour que chaque saut soit lisible, et prouver par un plan, d'abord en préproduction, que la mise à jour ne change pas l'infrastructure.

Cette leçon traite de cette discipline pour les quatre choses qui évoluent : l'outil (Terraform ou OpenTofu), les fournisseurs, les modules, et le choix de l'outil lui-même.

Les concepts

Quatre choses qui évoluent

Le troisième point de la ligne de l'état mérite d'être lu avec attention : un état n'a pas de numéro à épingler, mais il garde la trace de ce qui l'a écrit.

$ jq '{version, terraform_version, serial}' terraform.tfstate
{
  "version": 4,
  "terraform_version": "1.16.1",
  "serial": 1
}

La promesse de compatibilité de Terraform 1.x, écrite dans la documentation, est asymétrique : on peut passer d'une version 1.x à une version 1.x plus récente sans étape spéciale (« sans aucune étape de mise à jour particulière »), mais le retour en arrière n'est pas garanti, parce que les versions plus récentes « peuvent introduire de nouvelles fonctions que les versions antérieures ne comprennent pas, y compris de nouveaux formats de stockage de l'état ». Autrement dit : on ne met à jour qu'avec un moyen de revenir, qui est la sauvegarde de l'état, pas le binaire précédent. Les fournisseurs sont hors de cette promesse : leur mise à jour peut demander de modifier la configuration, même si Terraform reste en 1.x.

La contrainte de version de l'outil

Le bloc terraform déclare ce que la configuration accepte :

terraform {
  required_version = ">= 1.14, < 1.16"
}

La syntaxe est celle de toutes les contraintes de version : >=, <, ~> (« pessimiste » : ~> 1.14.0 autorise 1.14.x, ~> 1.14 autorise 1.x à partir de 1.14). Une exécution avec un binaire hors de la contrainte s'arrête avant de faire quoi que ce soit :

$ terraform init -no-color
...
   2:   required_version = ">= 1.14, < 1.16"

This configuration does not support Terraform version 1.16.1. To proceed,
either choose another supported Terraform version or update this version
constraint. Version constraints are normally set for good reason, so updating
the constraint may lead to other errors or unexpected behavior.

Pour un projet applicatif, on met un plancher (>= 1.14, la version dont on a besoin pour une fonctionnalité) et un plafond serré (< 2.0 si l'on suit la ligne 1.x). Pour un module partagé, on ne met qu'un plancher : le plafond serait imposé à tous ses utilisateurs.

Le fichier de verrou

Pour les fournisseurs, la contrainte (~> 3.7) dit ce qui est acceptable ; le fichier .terraform.lock.hcl dit ce qui a été choisi : la version exacte, les contraintes considérées et des sommes de contrôle (h1: calculées sur le contenu du paquet, zh: sur l'archive officielle). terraform init installe la version verrouillée et vérifie la somme de contrôle : c'est le principe de la « confiance au premier usage ». Le fichier se commite. Sans lui, deux exécutions, un jour d'écart, peuvent utiliser deux versions de fournisseur.

La mise à jour est un geste volontaire : terraform init -upgrade choisit la plus récente version compatible avec les contraintes et réécrit le fichier.

En pratique

Les démonstrations utilisent le fournisseur random (sans coût) avec Terraform 1.16.1.

Un fournisseur verrouillé qui refuse de bouger

Une configuration contraint le fournisseur à la série 3.7 :

terraform {
  required_version = ">= 1.14, < 2.0"
  required_providers {
    random = { source = "hashicorp/random", version = "~> 3.7.0" }
  }
}

Après terraform init, le fichier de verrou fixe la version :

$ grep -A3 'provider "' .terraform.lock.hcl
provider "registry.terraform.io/hashicorp/random" {
  version     = "3.7.2"
  constraints = "~> 3.7.0"
  hashes = [

Un mois plus tard, on relâche la contrainte à ~> 3.9. Un simple init refuse : le verrou prime sur la contrainte.

$ terraform init -no-color
- Reusing previous version of hashicorp/random from the dependency lock file

Error: Failed to query available provider packages

Could not retrieve the list of available versions for provider
hashicorp/random: locked provider registry.terraform.io/hashicorp/random
3.7.2 does not match configured version constraint ~> 3.9; must use terraform
init -upgrade to allow selection of new versions

Le message est la procédure : c'est -upgrade qui autorise le changement.

$ terraform init -upgrade -no-color
- Installing hashicorp/random v3.9.1...
- Installed hashicorp/random v3.9.1 (signed by HashiCorp)
Terraform has made some changes to the provider dependency selections recorded
in the .terraform.lock.hcl file. Review those changes and commit them to your
version control system if they represent changes you intended to make.

Le résultat est une différence dans le fichier de verrou, à relire dans la demande de fusion comme le reste.

Les sommes de contrôle de toutes les plateformes

Le verrou ne contient par défaut que les sommes de la plateforme où l'on a lancé init. Si le poste est un Linux et la CI un autre système, init y ajoute des sommes ou échoue. On pré-remplit pour les plateformes utilisées :

$ terraform providers lock -platform=linux_amd64 -platform=darwin_arm64 -platform=windows_amd64 -no-color
...
Success! Terraform has updated the lock file.
$ grep -c '"zh:\|"h1:' .terraform.lock.hcl
16

Cette commande évite que le verrou se remplisse au fil de l'eau, une machine après l'autre, en polluant l'historique Git. Les versions récentes d'OpenTofu (1.12 et plus) ajoutent d'elles-mêmes un jeu complet de sommes pour toutes les plateformes depuis le registre, ce qui rend la commande souvent inutile.

Lire avant de monter

Avant un -upgrade, on lit les notes de version du fournisseur (page « Releases » du dépôt, ou CHANGELOG). Les rubriques qui comptent :

• BREAKING CHANGES (ou « UPGRADE NOTES ») : un argument renommé, un comportement par défaut modifié, une ressource déplacée. Cherchez les noms des ressources que vous utilisez.
• DEPRECATIONS : à traiter avant qu'elles deviennent des erreurs à la version majeure suivante. Terraform et OpenTofu affichent désormais des avertissements pour les attributs obsolètes déclarés dans le schéma du fournisseur.
• BUG FIXES : parfois un bugfix change ce qu'un plan propose (un attribut qu'on ne détectait pas est maintenant comparé).

Pour un changement de série (2.x vers 3.x), le fournisseur publie en général un guide de mise à jour. Pour un pas mineur, la lecture du journal suffit, avec le plan comme preuve.

Changements de schéma et état

Quand un fournisseur change le schéma d'une ressource (un champ devient un bloc, un attribut change de type), il fournit une fonction de mise à niveau de l'état. Terraform l'appelle automatiquement au moment de lire l'état, et la valeur transformée est écrite à la prochaine opération qui écrit l'état. Trois conséquences :

• un simple plan après la mise à jour peut afficher des modifications qui viennent de la migration (valeurs par défaut devenues explicites) : à lire, pas à appliquer à l'aveugle ;
• l'état écrit par le fournisseur récent ne se relit plus avec l'ancien : le retour en arrière demande de restaurer la sauvegarde de l'état avec l'ancien verrou ;
• les migrations d'un nom de ressource à un autre passent par un bloc moved entre types, quand le fournisseur le permet (leçon 8).

Un plan de contrôle est la preuve : après la mise à jour du fournisseur, terraform plan doit être vide. S'il ne l'est pas, on lit chaque ligne pour savoir si le changement est voulu, avant tout apply.

Mettre à jour les modules

Les modules suivent la même discipline, avec les moyens de la leçon 3 : un module publié a un numéro de version sémantique, la source l'épingle (version = "~> 1.4" pour le registre, ?ref=v1.4.0 pour Git). La mise à jour d'un module est une modification de cette contrainte, un terraform init -upgrade (ou un init simple pour une source Git avec une nouvelle étiquette) et un plan. Si le module a changé le nom d'une ressource interne, son auteur a fourni un bloc moved, qui permet un plan vide ; s'il ne l'a pas fait, c'est un défaut du module, et le plan proposera de détruire et recréer : on s'arrête et on le signale.

Automatiser : Renovate et Dependabot

Surveiller à la main les versions de trois fournisseurs, dix modules et du binaire est pénible, et ce qu'on ne surveille pas ne se met pas à jour. Deux outils ouvrent des demandes de fusion automatiquement :

• Renovate a un gestionnaire terraform qui lit les fichiers **/*.tf et **/*.tofu et détecte les modules, les fournisseurs (blocs required_providers), la contrainte required_version, et même les images de conteneurs et les charts Helm déclarés dans les ressources. Il sait aussi maintenir le fichier .terraform.lock.hcl. Des gestionnaires voisins lisent .terraform-version et les fichiers de Terragrunt. D'après sa documentation, Renovate consulte le registre de Terraform par défaut et ne peut pas deviner si l'on veut celui d'OpenTofu : on le précise dans une règle de paquet.
• Dependabot, intégré à GitHub, déclare deux écosystèmes distincts dans dependabot.yml, terraform et opentofu, et propose des mises à jour de version (j'ai vérifié leur présence dans la référence des options ; vérifiez dans la documentation actuelle ce qu'ils couvrent pour votre dépôt, en particulier le fichier de verrou). Un exemple minimal :

version: 2
updates:
  - package-ecosystem: "terraform"
    directory: "/"
    schedule:
      interval: "weekly"

Avec un forge qui n'est pas GitHub (une instance GitLab ou Forgejo auto-hébergée, fréquente chez des clients souverains), Renovate est le choix naturel : il fonctionne avec plusieurs plateformes.

Ces outils ne remplacent pas le plan : chaque demande de fusion ouverte doit passer par la CI de la leçon 12 du premier cours (plan, politiques de la leçon 6, tests de la leçon 5), et c'est le plan qui décide de la fusion. Réglez-les pour grouper les mises à jour de faible risque et séparer les changements de série.

Gérer les versions du binaire

Pour que le poste et la CI utilisent la même version, on utilise un gestionnaire de versions. Le plus répandu est tfenv (Terraform, via un fichier .terraform-version) ; des outils plus récents (tenv, ou un gestionnaire généraliste comme mise ou asdf) gèrent aussi OpenTofu et Terragrunt. Dans tous les cas, la CI lit le même fichier que les postes : une version unique dans le dépôt, vérifiée par required_version. Pensez à la licence : les versions de Terraform à partir de la 1.6 sont publiées sous la licence BUSL de HashiCorp, celles jusqu'à la 1.5 sous MPL, et OpenTofu est sous MPL 2.0. Cela compte dans certains contrats clients.

Passer de Terraform à OpenTofu, et revenir

Le choix de l'outil n'est pas définitif, et c'est une raison de plus de garder des configurations portables. Le guide officiel d'OpenTofu décrit la migration comme sûre et réversible, en quatre étapes :

1. Sauvegarder le code et l'état (copie du fichier d'état local, versions du bucket distant).
2. Installer OpenTofu et lancer tofu init : il télécharge les fournisseurs depuis son registre (registry.opentofu.org), initialise le backend, et réécrit le verrou avec ces adresses.
3. Vérifier avec tofu plan : le résultat attendu est « aucun changement », ou le même plan que Terraform.
4. Appliquer un changement mineur (tofu apply) pour que l'état soit réécrit au format d'OpenTofu.

Le guide propose des pages dédiées par version de Terraform de départ (une pour 1.5 ou moins, une pour 1.6, une pour 1.7, etc.) : les écarts dépendent de la version de départ, lisez celle qui correspond à la vôtre.

Les points d'incompatibilité à vérifier avant :

• les fonctionnalités propres à Terraform : le bloc store de terraform_data (1.16), les Stacks, Terraform policy, les fonctions de HCP Terraform ;
• les fonctionnalités propres à OpenTofu : le chiffrement de l'état, lifecycle { enabled }, les variables const, les variables dans le backend : une fois utilisées, elles rendent le code illisible par Terraform ;
• le verrou : la bascule d'outil change les adresses de registre, donc les sommes de contrôle ;
• le backend et les états : les deux outils lisent le même format d'état au départ. Une configuration migrée vers OpenTofu peut lire par terraform_remote_state l'état de configurations restées sous Terraform, ce qui permet une migration par couche ; l'inverse n'est pas garanti.

Le retour de OpenTofu vers Terraform est possible tant que l'état n'a pas été écrit avec une fonctionnalité qu'un seul des deux comprend (chiffrement, par exemple), que le code n'en utilise pas, et que la version de Terraform visée n'est pas plus ancienne que celle qui correspond au format de l'état (on n'a, rappelons-le, aucune garantie de lecture d'un état plus récent). Dans le doute, répétez le retour sur une copie de l'état, dans un répertoire sans backend distant, avec plan pour juger. Le guide indique la marche de retour : arrêter OpenTofu, restaurer les sauvegardes, et vérifier avec Terraform qu'il n'y a pas de changement inattendu.

La leçon 7 a montré que le chiffrement de l'état est une porte à sens unique. Le décider, c'est aussi décider de rester sous OpenTofu.

Sous le capot

La résolution d'un fournisseur. À init, Terraform croise les contraintes de tous les modules de la configuration pour un même fournisseur : l'intersection doit être non vide. Il consulte le fichier de verrou : si une version y est inscrite et satisfait l'intersection, il la prend ; sinon il échoue (le message vu plus haut) ou, avec -upgrade, choisit la plus récente de l'intersection. D'où la règle pour les modules partagés : une contrainte de fournisseur large (>= 3.0), pas un plafond.

Pourquoi les sommes de contrôle. Le verrou protège contre le remplacement d'un paquet par un autre sous le même numéro de version (un registre compromis, un miroir mal tenu). Une somme qui ne correspond pas fait échouer l'installation : ne la « corrigez » pas sans comprendre. Si le fournisseur a été republié légitimement, la procédure est de relire le journal, puis de relancer -upgrade.

L'état et les versions. À chaque écriture, Terraform inscrit son numéro de version dans l'état (terraform_version) et incrémente le serial. Un état écrit par une version ne se relit pas forcément avec une plus ancienne, c'est le sens de l'asymétrie de la promesse de compatibilité. C'est pourquoi toute la mise à jour progressive qui suit commence par l'environnement qui peut se permettre une erreur.

Pièges courants

Un plafond trop serré sur un module partagé. required_version = "~> 1.14.0" dans un module interdit à tous ses utilisateurs de monter en 1.15 : la mise à jour du binaire doit alors attendre tous les modules. Un plancher seul.

Commiter sans le fichier de verrou. Le .gitignore copié d'un autre projet exclut parfois .terraform.lock.hcl. Sans lui, la CI et les postes divergent.

init -upgrade partout, tout le temps. C'est une opération de mise à jour, pas un init normal. Une CI qui l'exécute à chaque fois monte les versions sans qu'on le décide.

Appliquer un plan après une mise à jour sans le relire. La migration d'état peut produire des modifications d'attributs par défaut. Les valider sur la préproduction d'abord.

Plusieurs versions de l'outil dans la même équipe. L'un a 1.14 et l'autre 1.16 : le second réécrit l'état avec un format que le premier ne comprendra plus. required_version et un gestionnaire de versions l'empêchent.

Sauter plusieurs séries d'un coup. Un fournisseur qui passe de la 2.30 à la 2.84 en une demande de fusion cumule des dizaines de changements. Montez par paliers de série (2.40, 2.50...) quand le fossé est grand, un plan vide à chaque palier.

Une migration vers OpenTofu faite en même temps qu'une mise à jour de version. Deux changements, un seul plan : impossible de dire lequel a causé un écart. Une chose à la fois.

Sécurité

• Les mises à jour sont aussi des correctifs. Les notes de version de Terraform et d'OpenTofu listent régulièrement des corrections de sécurité (par exemple, les notes d'OpenTofu 1.12 et 1.11 mentionnent des corrections sur le traitement de réponses malveillantes d'un registre ou d'un backend). Un binaire ancien est une exposition : fixez un délai maximal de retard (une version mineure) et surveillez les avis.
• Le fournisseur est du code exécuté avec vos identifiants. Une mise à jour de fournisseur est une mise à jour de dépendance de la chaîne d'approvisionnement : relue, avec le fichier de verrou, comme un changement de code.
• Épinglez aussi l'image de la CI et la source des binaires. Un téléchargement latest du binaire dans la CI contourne tout ce qui précède.
• Les miroirs et registres internes. Si les clients exigent que rien ne soit téléchargé depuis l'extérieur, un miroir de fournisseurs interne se configure dans le fichier de configuration de la CLI ; la politique de sommes de contrôle reste celle du verrou.
• Les demandes de fusion automatiques ne s'approuvent pas toutes seules. Réservez la fusion automatique aux mises à jour de faible risque qui passent plan vide et politiques ; le reste est relu.

En production

Un plan de mise à jour progressive. La séquence qui a fait ses preuves, pour le dépôt signalements-iac :

1. Lire les notes de version de la cible (fournisseur, binaire, module). Noter ce qui touche vos ressources.
2. Branche : modifier la contrainte, lancer init -upgrade, commiter le verrou. La CI exécute validate, les tests, les politiques.
3. Plan en lecture seule contre la production, avec la nouvelle version : un plan n'écrit pas l'état, il donne donc une première réponse sans risque pour l'état. Il doit être vide, ou ne contenir que des changements compris.
4. Préproduction : sauvegarde de l'état, apply, plan de contrôle vide. Laisser vivre quelques jours.
5. Production : sauvegarde, fenêtre annoncée, apply (de préférence le plan déjà enregistré et relu), plan de contrôle vide.
6. Cas par couches : si l'infrastructure est découpée (leçon 8), monter d'abord les couches les moins critiques, ou celles dont la rupture se voit tout de suite (l'application avant les données).
7. Retour arrière : restaurer la version précédente du verrou et de l'état (si l'apply a eu lieu). Il est prévu avant de commencer.

Un rythme. Mettre à jour souvent et peu : une fenêtre mensuelle pour les fournisseurs, une par trimestre pour le binaire, tout de suite pour les correctifs de sécurité. Un retard de dix versions coûte beaucoup plus qu'un retard de deux.

Qui possède la mise à jour. Dans une équipe plateforme, quelqu'un a la responsabilité du « calendrier de versions » : c'est lui qui répond à la question « quelle version pour quel environnement ». Sans propriétaire, la mise à jour n'a lieu qu'en cas d'incident.

Mesurer la dette. Un rapport hebdomadaire (Renovate le fait avec son tableau de bord de dépendances) qui liste les mises à jour en attente rend le retard visible. Une dette invisible n'est pas remboursée.

Exercices

Exercice 1 : lire le verrou

Un collègue a changé version = "~> 2.84" en "~> 2.90" dans required_providers et lancé terraform init : l'erreur indique que le fournisseur verrouillé en 2.84 ne correspond pas. Que faites-vous, dans quel ordre, et que mettez-vous dans la demande de fusion ?

Exercice 2 : migrer un module partagé

Votre module reseau déclare required_version = "~> 1.14.0". L'équipe veut passer en Terraform 1.16. Décrivez le problème et la correction, et dites si un bloc moved est nécessaire.

Exercice 3 : décider d'une migration

Un client demande si Signalements peut passer à OpenTofu. Le dépôt utilise Terraform 1.16, terraform_data avec store pour un secret, et des variables éphémères. Quelles vérifications faites-vous, et dans quel ordre ?

Exercice 4 : le plan non vide

Après init -upgrade d'un fournisseur, terraform plan en préproduction affiche une modification sur la base : ~ backup_schedule_frequency = 24 -> null. Quelles hypothèses et quelle conduite ?

Récapitulatif

• On épingle pour ne rien subir : required_version pour le binaire (plancher seul dans un module partagé), required_providers pour la contrainte, .terraform.lock.hcl commité pour la version exacte et les sommes de contrôle.
• Le verrou prime sur la contrainte : seul terraform init -upgrade le fait bouger ; terraform providers lock -platform=... complète les sommes pour toutes les plateformes.
• La compatibilité de Terraform 1.x est asymétrique : monter est sans étape spéciale, redescendre n'est pas garanti. La sauvegarde de l'état est le vrai retour arrière.
• On lit les notes de version, et un plan vide après la mise à jour est la preuve ; un plan non vide se lit ligne à ligne avant tout apply.
• Renovate (gestionnaire terraform, verrou compris) et Dependabot (écosystèmes terraform et opentofu) ouvrent les demandes de fusion ; le plan et les politiques décident de la fusion.
• Migrer vers OpenTofu : sauvegarde, tofu init, plan sans changement, apply mineur. Le retour est possible tant qu'aucune fonctionnalité propre à un outil n'a été utilisée. Une chose à la fois.
• Le plan de mise à jour : lire, branche, plan en lecture seule contre la production, préproduction, production, avec un retour arrière prévu avant de commencer.

Pour aller plus loin

• La page des promesses de compatibilité de Terraform 1.x, la page du fichier de verrou et celle des contraintes de version.
• Les notes de version de Terraform et d'OpenTofu, et le guide de migration d'OpenTofu avec ses pages par version de départ.
• La documentation de Renovate (gestionnaire terraform, règles de paquets, tableau de bord) et les options de Dependabot.
• La leçon 3 sur les versions de modules, la leçon 6 pour rejouer les politiques à chaque mise à jour, et la leçon 9 pour monter la version de l'outil d'orchestration en même temps.
• Le projet du cours (relu par un pair) reprend ce plan de mise à jour sur le dépôt signalements-iac.