Intégrer Terraform dans une stack existante

Ta stack tourne depuis deux ans sans Terraform. Voilà comment l'importer sans casser une seule ressource : inventaire, state distant, blocs import et convergence vers un plan vide.

Intégrer Terraform dans une stack existante

Ta stack tourne depuis deux ans. Un security group ouvert à 0.0.0.0/0 a été créé à la main un vendredi soir, personne ne se souvient par qui, et ton terraform plan affiche fièrement : No changes. Your infrastructure matches the configuration.

Ce plan ne dit pas que ton infrastructure est saine. Il dit que Terraform ne la voit pas.

Le vrai boulot quand tu arrives après coup n'est pas d'écrire du HCL. C'est de faire accepter à Terraform une réalité qu'il n'a pas créée, sans détruire une seule ressource au passage.

Pourquoi ton premier plan est un mensonge

Terraform ne compare pas ta config au cloud. Il compare ta config à un fichier d'état, le terraform.tfstate, qui ne contient que ce qu'il a lui-même créé ou importé.

Résultat : sur une stack existante, l'état est vide et Terraform conclut que rien n'existe. Si tu lances un apply avec une config complète, il va tenter de recréer par-dessus des ressources déjà là — et là, deux issues seulement : un conflit de nom qui échoue, ou une ressource doublon facturée deux fois.

Le state reste la seule source de vérité pour Terraform, c'est documenté noir sur blanc dans la référence officielle sur le state. Tant qu'une ressource n'y figure pas, elle n'existe pas pour ton code.

Trois façons d'entrer, une seule qui tient

ApprocheQuand ça marcheCe que ça coûte
Big bang : tout réécrire en HCL et recréerEnvironnement de test jetableInterdit en prod : downtime, perte de données, IP qui changent
terraform import ressource par ressourceMoins de 20 ressources, périmètre netUne commande par ressource, config écrite à la main, aucune trace dans le code
Blocs import versionnés (Terraform ≥ 1.5)Toute stack sérieuseUn peu de nettoyage sur le code généré

Je ne fais plus autrement que la troisième. La raison n'est pas la vitesse, c'est la traçabilité : un bloc import vit dans le dépôt, se relit en revue, et se rejoue sur un second compte. Un terraform import tapé dans un terminal ne laisse aucune trace.

Étape 1 — inventorier ce que Terraform ignore

Avant de toucher au code, tu listes. Pas à la main dans la console : en script, avec un identifiant stable par ressource.

aws ec2 describe-instances \
  --filters "Name=instance-state-name,Values=running" \
  --query 'Reservations[].Instances[].[InstanceId,Tags[?Key==`Name`]|[0].Value,InstanceType]' \
  --output table

Sur un compte AWS réel, cette commande sort la vingtaine d'instances qui font tourner ta prod. Tu obtiens trois colonnes : l'ID que Terraform veut, le nom que ton équipe utilise, le type qui doit apparaître dans le HCL.

Le piège classique, ce sont les ressources créées par un controller. Un aws_lb_target_group_attachment généré par l'AWS Load Balancer Controller, ou les règles ajoutées par un opérateur Kubernetes, changent sans arrêt.

Si tu les importes, ton plan sera rouge tous les matins. Note-les dans une colonne « à ne pas importer » et garde-les en data sources.

Un tag commun aide énormément ici. Si ta stack a déjà un ManagedBy ou un Project, filtre dessus : --filters "Name=tag:Project,Values=acme-prod" te donne exactement le périmètre à traiter, et rien d'autre.

Étape 2 — poser les blocs import

Un bloc import déclare le lien entre une adresse Terraform et un identifiant réel, comme le décrit la référence des blocs import. La syntaxe est plate, volontairement.

import {
  to = aws_instance.web
  id = "i-0abc123def4567890"
}

import {
  to = aws_security_group.api
  id = "sg-0f1e2d3c4b5a69788"
}

Tu ne devines pas la config : tu la fais générer. Avec un fichier de sortie inexistant, Terraform écrit le HCL correspondant pendant le plan.

terraform plan -generate-config-out=imported.tf

Le fichier imported.tf contient les ressources avec leurs attributs réels, lus depuis l'API. C'est du brut de fonderie : valeurs en dur, zéro variable, zéro count.

Nettoyer le code généré, sinon tu regretteras

Trois passes suffisent dans 90 % des cas.

  1. Sortir les valeurs en variables — instance_type = "t3.small" devient var.instance_type.
  2. Regrouper par module — un fichier par domaine (network.tf, compute.tf), pas un fichier de 900 lignes.
  3. Ajouter les tags — les blocs générés n'héritent pas de ta convention default_tags du provider. Vérifie que le plan ne propose pas de les retirer.

Ce point 3 est celui qui casse des choses. Si ton provider déclare default_tags et que la ressource importée n'a pas ces tags, Terraform veut les ajouter — ce qui est sans danger. L'inverse, un tag qui existe dans le cloud et pas dans le code, produit une suppression de tag silencieuse en cas de ignore_changes mal placé.

Étape 3 — converger sans rien casser

L'objectif intermédiaire n'est pas un code propre. C'est un plan vide après import. Un terraform plan qui retourne No changes signifie que le code décrit l'existant à l'identique.

Pour y arriver sans risque, deux garde-fous dans la config.

resource "aws_db_instance" "main" {
  identifier = "acme-prod-db"
  # … attributs générés

  lifecycle {
    prevent_destroy = true
    ignore_changes  = [password, snapshot_identifier]
  }
}

prevent_destroy transforme toute tentative de destruction en erreur bloquante. Sur une base de données, c'est non négociable. ignore_changes absorbe les attributs que tu ne contrôles pas : mot de passe posé par un opérateur, snapshot, ou métadonnée mise à jour par un outil tiers.

Si une ressource doit sortir du state sans être détruite, tu as le bloc removed, disponible depuis Terraform 1.7.

removed {
  from = aws_instance.legacy_batch

  lifecycle {
    destroy = false
  }
}

C'est la version versionnée et relisible de terraform state rm. Garde la commande pour les urgences en direct, utilise le bloc dans le dépôt.

Le backend avant tout le reste

Importer dans un state local sur le poste d'un dev, c'est perdre le travail au premier rm -rf ou au premier départ. Le backend distant passe avant la première ligne de HCL.

terraform {
  required_version = ">= 1.10"

  backend "s3" {
    bucket       = "acme-tfstate"
    key          = "prod/network/terraform.tfstate"
    region       = "eu-west-3"
    use_lockfile = true
  }
}

use_lockfile remplace la vieille table DynamoDB de verrouillage par un verrou natif S3. Disponible depuis Terraform 1.10, et c'est le mécanisme que je recommande aujourd'hui : une brique de moins à maintenir, une facture de moins.

Un state par périmètre. Réseau, compute, data : trois states séparés, trois blast radius. Importer 200 ressources dans un seul state, c'est garantir qu'un plan prendra huit minutes et qu'une erreur de casse emportera tout.

Les cas où je refuse d'importer

Tout n'a pas vocation à entrer dans Terraform. Trois familles restent dehors chez moi, par choix assumé.

Les bases managées par un opérateur. Une base PostgreSQL provisionnée par CloudNativePG ou un cluster géré par un opérateur évolue selon son propre cycle. Tu la déclares en data source : tu la lis, tu ne la pilotes pas.

Les ressources applicatives. Un bucket créé par le code métier au runtime n'a pas sa place dans le state. Tu le déclares en data, ou tu le laisses hors périmètre.

Ce qui change toutes les heures. Autoscaling, règles de pare-feu dynamiques, entrées DNS mises à jour par un controller : les importer produit un état divergent permanent. Sur Kubernetes, c'est exactement le même arbitrage que pour les Ingress que tu déclares dans tes projets — soit le manifeste est la source de vérité, soit Terraform l'est, jamais les deux.

Ce que ça change dans ta CI

Une fois le state aligné, la vraie valeur arrive : la détection de dérive. Un plan en CI, avec le bon code de sortie, te dit si quelqu'un a touché à la main.

terraform plan -detailed-exitcode -out=tfplan
# 0 = aucun changement, 1 = erreur, 2 = changements détectés

Ton job échoue sur 1, ouvre une alerte sur 2. Le plan devient une sonde de configuration, au même titre qu'un tableau de bord : c'est le complément naturel d'une supervision Grafana appliquée au réel. Les métriques te disent que ça répond, le plan te dit que ça correspond à ce qui est écrit.

Si tu hésites entre Terraform et son fork OpenTofu, sache que les blocs import existent des deux côtés avec la même syntaxe. Le choix se joue sur la gouvernance de la licence, pas sur la migration d'une stack existante.

Combien de temps ça prend vraiment

Sur une stack de 60 ressources réparties en trois domaines, avec un état des lieux propre, compte deux jours de travail réel. La répartition observée sur mes derniers chantiers :

PhaseTempsCe qui bloque
Inventaire et découpage en states3 hRessources sans tag, périmètre flou
Import et génération de config4 hAttributs calculés par le provider
Nettoyage du HCL6 hValeurs en dur, duplication de modules
Convergence vers un plan vide4 hignore_changes à arbitrer un par un

La phase la plus longue n'est pas technique. C'est l'arbitrage : chaque attribut divergent te demande de choisir entre « le cloud a raison, je l'ignore » et « le code a raison, je corrige ». Personne ne peut le faire à ta place sans connaître l'historique de la stack.

FAQ

Peut-on importer plusieurs centaines de ressources d'un coup ?

Oui, avec un bloc import par ressource dans un fichier dédié. Le plan traite la liste entière en une passe. Au-delà de 200 blocs, découpe par domaine et par state : la lisibilité du dépôt compte plus que le nombre d'apply.

Que se passe-t-il si ma config ne correspond pas à la ressource réelle ?

Le plan propose des changements, parfois destructifs. C'est normal et c'est l'étape utile : tu alignes le code sur la réalité, attribut par attribut, jusqu'à obtenir No changes. Ne lance jamais un apply sur un plan qui propose un replace d'une ressource stateful.

Terraform importe-t-il aussi les dépendances ?

Non. Un aws_instance importé ne tire pas son security group. Chaque ressource référencée doit avoir son propre bloc import, sinon le plan échoue sur une référence introuvable dans le state.

Faut-il supprimer le code généré automatiquement ?

Non, mais il faut le traiter comme un brouillon. Le fichier -generate-config-out sert à ne pas recopier les attributs à la main. Sa relecture, variable par variable, fait partie du travail.

Et si l'équipe continue de créer des ressources à la main ?

Alors l'import ne sert à rien. Terraform ne tient que si le dépôt devient la seule porte d'entrée. Tant que quelqu'un garde ses droits d'admin console, tu importeras les mêmes ressources tous les trimestres.