Module 4 — L’état

Durée indicative du cours : 2 h
Durée indicative de l’atelier : atelier du jour 2, rédigé avec ce module
Durée totale (cours + atelier) : le jour 2

Ce module couvre les objectifs 2d, 6a à 6d et 7a à 7c. Le state est ce qui permet à un collègue de reprendre l’environnement sans deviner ce que Terraform a déjà créé.

Pourquoi le state existe

La configuration dit random_id.suffixe et local_file.fiche_environnement. La réalité, elle, a un fichier précis et une valeur de suffixe déjà tirée. Le state relie les deux. Sans lui, le prochain apply ne saurait pas s’il faut créer, modifier ou laisser.

Le state enregistre aussi des attributs que la configuration ne répète pas, comme l’identifiant réel de l’objet. Il peut contenir des valeurs sensibles. On ne le commite pas dans un dépôt partagé quand plusieurs personnes travaillent, et on ne l’édite pas à la main.

Le backend local

Sans bloc backend, Terraform utilise le backend local. Le state est le fichier terraform.tfstate dans le dossier de travail. C’est le cas du jour 1.

Vous pouvez rendre ce choix explicite et changer le chemin.

terraform {
  backend "local" {
    path = "environnement.tfstate"
  }
}

Après ce changement, terraform init -migrate-state déplace le state vers le nouveau chemin. init seul initialise. -migrate-state sert quand un state existe déjà et que le backend change.

Le backend local convient à une personne seule, sur une machine. Deux applies en même temps sur le même fichier se marchent dessus.

Le verrou

Le verrou empêche deux opérations d’écrire le state en même temps. Un backend qui sait verrouiller refuse le second plan ou le second apply tant que le premier n’a pas fini. Le message parle d’acquisition du verrou.

Ce verrou n’est pas le lockfile des providers. .terraform.lock.hcl fige des versions de plugins. Le verrou de state protège une écriture.

Le backend local ne fournit pas un verrou d’équipe. Un backend distant le fournit quand son type le prend en charge. Forcer un verrou (-lock=false, ou une commande de déverrouillage) se fait seulement quand vous savez que personne n’écrit, par exemple après un crash. Le faire par habitude, c’est accepter deux écritures concurrentes.

Un backend distant

Le bloc backend place le state hors du dossier de travail. La forme est toujours la même. Le type et ses arguments changent.

terraform {
  backend "TYPE" {
    # arguments propres à ce type : adresse, conteneur, préfixe
  }
}

Vous lancez terraform init après avoir ajouté le bloc. S’il existe déjà un state local, terraform init -migrate-state le copie vers le nouveau backend. Les collègues pointent vers ce même backend. Ils partagent alors un carnet, et le verrou, si le type le permet.

Dans ce cours, la pratique commune du state distant est HCP Terraform, au module 8. Une série d’ateliers peut en plus configurer un backend sur sa propre cible. Le mécanisme à retenir ici est le bloc, la migration, et le verrou.

La dérive

La dérive, c’est un objet déjà présent dans le state, modifié en dehors de Terraform. Sur le fil, vous éditez fiche-environnement.txt à la main après un apply.

Le plan suivant lit la réalité. Il propose de réécrire le fichier pour le ramener au contenu de la configuration. Vous avez alors deux décisions.

• Revenir au code : vous appliquez. La fiche reprend le texte écrit dans .tf.
• Adopter le réel : vous changez la configuration pour qu’elle décrive le fichier tel qu’il est, puis le plan ne doit plus proposer de modification.

terraform plan -refresh-only met le state à jour avec ce que le provider lit, sans proposer de changer la cible. terraform apply -refresh-only enregistre cette mise à jour. Cela ne répare pas la cible. Cela aligne le carnet sur le réel.

Deux autres blocs servent quand c’est l’adresse dans la configuration qui change, pas l’objet réel.

• moved dit à Terraform qu’une ressource a changé de nom dans les fichiers. Le state suit, sans destruction.
• removed retire l’objet du state et le laisse en place dans la réalité. La configuration ne le gère plus.

moved {
  from = local_file.fiche_environnement
  to   = local_file.fiche
}

removed {
  from = local_file.ancienne_fiche

  lifecycle {
    destroy = false
  }
}

destroy = false dans removed laisse l’objet exister. destroy = true le détruit au moment où il sort du state.

Importer

L’import concerne un objet qui existe déjà et qui n’est pas dans le state. Terraform ne le gère pas tant qu’on ne l’attache pas.

Vous écrivez d’abord le bloc resource qui décrit l’objet. Ensuite vous l’importez. La forme actuelle est un bloc import.

import {
  to = local_file.fiche_deja_la
  id = "fiche-environnement.txt"
}

resource "local_file" "fiche_deja_la" {
  filename = "${path.module}/fiche-environnement.txt"
  content  = "nom=lab-equipe\n"
}

terraform plan montre alors l’import. Après l’apply, un nouveau plan doit être vide, ou ne montrer que les écarts que vous avez compris entre le bloc et le réel.

La commande terraform import ADRESSE ID fait le même rattachement sans bloc. Le bloc import se relit et se rejoue. C’est la forme à préférer dans le dépôt.

terraform state rm ADRESSE retire l’objet du state sans le détruire. Vous vous en servez pour un découpage ou une reprise. Ce n’est pas un destroy.

Inspecter et journaliser

terraform state list affiche les adresses gérées. terraform state show ADRESSE affiche les attributs enregistrés pour l’une d’elles. terraform state pull écrit le state distant sur la sortie standard, en lecture.

terraform state mv ANCIENNE NOUVELLE déplace une adresse dans le state, par exemple après un renommage fait sans bloc moved. Le bloc moved reste la forme à préférer dans les fichiers, parce qu’il se relit. state mv agit tout de suite sur le carnet.

terraform state push remplace le state distant par un fichier local. Vous ne l’utilisez que pour une restauration que vous avez relue. Une erreur ici écrase le carnet de l’équipe.

Workspaces de la CLI

terraform workspace crée plusieurs states pour la même configuration, dans le backend courant. terraform workspace new lab-b puis terraform workspace select lab-b bascule de carnet. terraform.workspace donne le nom en cours dans une expression.

Ce workspace-là est un state nommé. Ce n’est pas un dossier, et ce n’est pas un workspace HCP Terraform. Le module 8 reprend cette différence au moment du run distant.

terraform console évalue une expression dans ce state. Utile pour lire un attribut avant de le citer dans une configuration.

Les journaux détaillés s’activent avec une variable d’environnement, le temps d’un diagnostic.

$env:TF_LOG = "DEBUG"
$env:TF_LOG_PATH = "terraform-debug.log"
terraform plan

TRACE est encore plus bavard que DEBUG. ERROR ne garde que les erreurs. Vous retirez ces variables ensuite. Le fichier de log peut contenir des valeurs sensibles. Vous ne le commettez pas.

Ce que l’examen veut pour ce module

Objectif	Vous devez pouvoir l’expliquer
2d	Le state relie la configuration aux objets réels. Il est la mémoire de Terraform
6a	Le backend local stocke terraform.tfstate dans le dossier de travail
6b	Le verrou empêche deux écritures simultanées. Il est distinct du lockfile des providers
6c	Le bloc backend place le state ailleurs. init -migrate-state déplace un state existant
6d	La dérive se lit dans un plan. refresh-only aligne le state. moved et removed changent le carnet sans confondre avec un destroy
7a	L’import attache un objet déjà créé. On écrit le HCL, puis on importe, puis on relit le plan
7b	state list, state show et state mv inspectent ou déplacent une adresse. state rm retire du state sans détruire. Un workspace CLI est un autre state pour le même code
7c	TF_LOG et TF_LOG_PATH activent un journal détaillé pour un diagnostic

Points à retenir

• Configuration, state et réalité restent trois choses distinctes.
• Le lockfile fige les providers. Le verrou protège le state.
• Une dérive se décide : revenir au code, ou adopter le réel.
• Importer, ce n’est pas rafraîchir. Rafraîchir, ce n’est pas réparer la cible.

Suite

Poursuivre avec le module 5 — Le langage de configuration.