Exécuter Terraform en automation

Une chaîne d'intégration n'a pas de clavier et ne lit pas la sortie colorée : elle décide sur des codes de retour. Écrire Terraform pour l'automation, c'est donc rendre chaque commande non interactive, et savoir exactement ce que son code veut dire.

Tout ce qui suit a été exécuté sur Terraform v1.15.4, codes et durées compris. Trois idées répandues n'y survivent pas, celle du fmt -check qui rendrait 1, celle du plan qui attendrait une variable manquante, et celle du plan sauvegardé qui figerait tout.

Ce que vous allez apprendre

• Les trois issues d'un plan, lues sur son seul code de retour
• Comment empêcher toute commande de se bloquer sur une invite
• Ce qu'un plan sauvegardé fige, et les options qui y deviennent décoratives
• Traiter un verrou d'état concurrent au lieu de le subir
• Pourquoi un plan sauvegardé ne doit jamais rejoindre le dépôt

Prérequis

• Terraform 1.11 ou plus récent (installer Terraform).
• Connaître le workflow de base (le workflow Terraform).

Les trois issues d'un plan

C'est la brique de toute porte de revue automatisée. Sans option, terraform plan rend 0 aussi bien quand il n'y a rien à faire que quand il y a des changements : impossible de décider. L'option -detailed-exitcode sépare les trois cas.

Code	Ce que cela veut dire
0	aucun changement, l'infrastructure est conforme
1	erreur : la configuration ne planifie pas
2	des changements sont en attente

Glissez pour voir

Mesuré, dans cet ordre : avant l'apply le plan rend 2, après l'apply il rend 0, et sur une configuration cassée il rend 1.

terraform plan -input=false -detailed-exitcode

Error: Missing name for resource

  on casse.tf line 1, in resource "local_file":
   1: resource "local_file" {

All resource blocks must have 2 labels (type, name).

Tester `-eq 1` ne détecte rien

Un pipeline qui traite « échec » comme « code différent de 0 » confondra une erreur avec des changements en attente. Et celui qui teste -eq 1 ratera les deux. Les trois valeurs se traitent séparément.

Ne jamais se bloquer sur une invite

Une commande qui attend une saisie dans une CI ne s'arrête pas : elle occupe un agent jusqu'au délai maximum du job. L'option -input=false l'interdit, et transforme l'attente en échec immédiat.

Mesuré, sur une variable racine sans valeur :

terraform plan -input=false

Error: No value for required variable

The root module input variable "obligatoire" is not set, and has no default
value. Use a -var or -var-file command line argument to provide a value for
this variable.

Code 1, en 0,0 seconde. La commande n'attend pas : elle échoue tout de suite, ce qui est exactement le comportement voulu.

Deux réglages complémentaires

La variable d'environnement TF_IN_AUTOMATION, à n'importe quelle valeur non vide, retire des sorties les suggestions de commandes suivantes, qui n'ont pas de sens hors d'un terminal. Et -no-color supprime les séquences d'échappement qui polluent les journaux.

La chaîne complète, étape par étape

1. Contrôler le format, sur toute l'arborescence :

   terraform fmt -check -recursive

   Le code de retour est 3 en cas d'écart, pas 1. Mesuré sur un fichier mal indenté, la commande liste le fichier fautif et sort en 3.

2. Initialiser sans interaction :

   terraform init -input=false

3. Valider, en sortie machine :

   terraform validate -json

4. Planifier dans un fichier, et décider :

   terraform plan -out=tfplan -input=false -detailed-exitcode

5. Appliquer le fichier de plan, jamais une nouvelle planification :

   terraform apply -input=false tfplan

   Appliquer le fichier garantit que ce qui est déployé est bien ce qui a été revu. Un apply qui replanifie pourrait faire autre chose, si l'état a bougé entre-temps.

Ce qu'un plan sauvegardé fige, et ce qu'il ne fige pas

C'est le point le plus contre-intuitif de cette page. Un plan sauvegardé fige les valeurs de variables et les actions prévues. Il ne protège pas de tout.

Une tentative de changer une variable est bien refusée :

terraform apply -input=false -var environnement=autre tfplan

Error: Can't change variable when applying a saved plan

The variable environnement cannot be set using the -var and -var-file options
when applying a saved plan file, because a saved plan includes the variable
values that were set when it was created.

Code 1. Jusque-là, tout va bien. En revanche, les modes de planification passés à cet apply sont acceptés et ignorés, en silence. Mesuré, chaque option sur un plan frais de création :

Option passée à l'apply d'un plan sauvegardé	Résultat mesuré
-var	erreur, code 1
-destroy	accepté, et les ressources sont créées
-refresh=false	accepté, sans effet
-target=...	accepté, sans effet : tout est créé
-parallelism=1	accepté

Glissez pour voir

Un apply `-destroy` sur un plan de création crée

C'est le résultat qui surprend le plus, et il est mesuré : lancer terraform apply -destroy tfplan sur un plan de création rend 0 après avoir créé les deux ressources. Le mode de planification appartient au fichier, pas à la ligne de commande, et Terraform ne signale rien. Un script qui croit détruire construit donc, sans le moindre avertissement.

Traiter le verrou, au lieu de le subir

Deux exécutions concurrentes sur le même état, c'est le quotidien d'une CI qui déclenche sur plusieurs branches. Terraform pose un verrou pendant l'opération, et le comportement par défaut est brutal.

Mesuré, un plan lancé pendant qu'un apply détient le verrou :

Error: Error acquiring the state lock

Error message: resource temporarily unavailable

Code 1, en 0,0 seconde : aucune attente. Avec un délai, la même commande patiente puis aboutit :

terraform plan -input=false -lock-timeout=60s

Acquiring state lock. This may take a few moments...

Code 0, après 15 secondes, soit le temps que l'apply concurrent se termine. Un -lock-timeout adapté à la durée de vos applies transforme donc un échec de pipeline en simple attente.

Les pièges mesurés

Le plan sauvegardé contient vos secrets en clair

Le fichier produit par -out= a l'air opaque : un grep binaire n'y trouve rien, puisqu'il est compressé. Cela ne protège rien du tout. Une relecture en JSON en sort la valeur, et à quatre endroits distincts :

terraform show -json tfplan | jq '.variables'

Mesuré, une variable marquée sensitive apparaît en clair dans :

.variables.mot_de_passe.value
.planned_values.root_module.resources[0].values.content
.resource_changes[0].change.after.content
.configuration.root_module.variables.mot_de_passe.default

Un plan sauvegardé est donc un artefact sensible. Il ne se committe jamais, et son nom par défaut, tfplan, n'a pas d'extension : un .gitignore qui ne connaît que *.tfplan ne l'attrape pas.

tfplan
*.tfplan

fmt -check ne rend pas 1

Le code est 3. Un pipeline qui teste -eq 1 laisse donc passer un dépôt mal formaté, et celui qui oublie -recursive ne regarde qu'un seul répertoire. Ces deux détails suffisent à rendre un contrôle de format entièrement décoratif.

Un apply qui replanifie n'applique pas ce qui a été revu

Sans fichier de plan, terraform apply replanifie au moment de l'exécution. Entre la revue et l'application, l'état a pu bouger. C'est précisément ce que le couple plan -out puis apply <fichier> évite, et c'est la raison pour laquelle une porte de revue sérieuse applique un fichier.

Dépannage

Symptôme	Cause probable	Correction
le job reste bloqué sans rien afficher	une commande attend une saisie	ajouter -input=false partout
le pipeline est vert avec des changements en attente	code lu sans -detailed-exitcode	traiter 0, 1 et 2 séparément
un contrôle de format toujours vert	fmt -check sans -recursive, ou code testé -eq 1	ajouter l'option, et tester le code 3
Error acquiring the state lock	une exécution concurrente détient le verrou	-lock-timeout calé sur la durée de vos applies
Can't change variable when applying a saved plan	-var passé à l'apply d'un fichier de plan	fixer les variables au moment du plan -out
un apply -destroy a créé des ressources	le mode appartient au fichier de plan	enregistrer un plan de destruction avec plan -destroy -out=
Saved plan is stale	l'état a changé depuis l'enregistrement	replanifier, puis appliquer le nouveau fichier
un secret apparaît dans un artefact de CI	le plan sauvegardé a été publié	ne jamais le committer ni l'exposer en artefact

Glissez pour voir

Mettre en pratique

Le lab une chaîne non interactive fait bâtir les cinq étapes et consigner les codes relevés dans des fichiers de preuves. Les tests ne lisent aucune sortie humaine : ils rejouent eux-mêmes fmt -check, validate -json, les trois valeurs de -detailed-exitcode, l'apply concurrent sous verrou et les options du plan sauvegardé, puis comparent à vos relevés. L'apply doit durer assez longtemps pour qu'un verrou soit observable. Il se joue hors ligne.

À retenir

• -detailed-exitcode sépare les trois issues : 0 rien, 1 erreur, 2 changements.
• -input=false transforme une attente d'invite en échec immédiat, en 0,0 seconde.
• fmt -check rend 3, jamais 1, et ne voit qu'un répertoire sans -recursive.
• Une porte de revue applique un fichier de plan, pas une nouvelle planification.
• Un plan sauvegardé fige les variables : -var à l'apply est refusé.
• Mais -destroy, -refresh=false et -target y sont acceptés et ignorés : un apply -destroy sur un plan de création crée.
• Par défaut, un verrou concurrent fait échouer la commande immédiatement ; -lock-timeout la fait patienter.
• Un plan sauvegardé contient les secrets en clair, lisibles par show -json, à quatre endroits.
• Son nom par défaut n'a pas d'extension : le .gitignore doit nommer tfplan.
• TF_IN_AUTOMATION et -no-color allègent des sorties qui n'ont pas de terminal pour les lire.

FAQ : questions fréquentes

Les questions ci-dessous portent sur ce qui casse une chaîne : le code de retour mal lu, la commande qui attend, et le plan sauvegardé qu'on croit inaltérable.

Que renvoie terraform plan -detailed-exitcode ?

Trois valeurs distinctes : 0 quand aucun changement n'est nécessaire, 1 en cas d'erreur, et 2 quand des changements sont en attente. Sans cette option, le plan rend 0 dans les deux premiers cas, ce qui interdit toute décision automatique.

Comment empêcher Terraform d'attendre une saisie en CI ?

En passant -input=false à toutes les commandes. Mesuré, un plan sans valeur pour une variable requise échoue alors en code 1 immédiatement, au lieu d'attendre une saisie qui n'arrivera jamais dans un job automatisé.

Pourquoi appliquer un fichier de plan plutôt que relancer terraform apply ?

Parce qu'un apply sans fichier replanifie au moment de l'exécution. Entre la revue et l'application, l'état a pu changer, et ce qui est déployé n'est alors plus ce qui a été revu. Appliquer le fichier garantit l'inverse.

Un plan sauvegardé fige-t-il vraiment ce qui sera appliqué ?

Partiellement. Il fige les valeurs de variables, et une tentative de les changer par -var est refusée. En revanche les modes de planification comme -destroy, -refresh=false ou -target sont acceptés puis ignorés en silence.

Comment gérer deux exécutions Terraform concurrentes ?

Avec -lock-timeout. Par défaut, une commande lancée pendant qu'une autre détient le verrou d'état échoue immédiatement en code 1. Avec un délai suffisant, elle patiente puis aboutit normalement en code 0.

Un fichier de plan Terraform contient-il des secrets ?

Oui, en clair. Le fichier paraît opaque car il est compressé, mais terraform show -json en extrait les valeurs sensibles, y compris une variable marquée sensitive, à plusieurs emplacements du document JSON.

Quel code de retour renvoie terraform fmt -check ?

Le code 3 lorsqu'au moins un fichier doit être reformaté, et 0 sinon. Un pipeline qui teste une valeur égale à 1 laisse donc passer un dépôt mal formaté sans jamais le signaler.

Quelles commandes composent une chaîne Terraform non interactive ?

Cinq étapes : fmt -check -recursive pour le format, init -input=false, validate -json, plan -out avec -detailed-exitcode pour décider, puis apply du fichier de plan produit. Chacune s'exécute sans saisie.

Pour aller plus loin

• Tester un module : la suite de tests qu'une chaîne d'intégration peut jouer.
• Versionner ses modules : figer les versions que la chaîne installera.
• Exécuter Terraform en automation : la référence officielle : le workflow non interactif recommandé.
• La commande plan : la référence officielle : -detailed-exitcode, -out et -lock-timeout.

×

📖 Voir la documentation →