Commencer→
Retour au cours

infra / terraform

Import de ressources existantes

Leçon 101 exercice

Explication

Ce que vous allez apprendre

  • Comprendre pourquoi importer une ressource plutôt que la recréer
  • Utiliser terraform import puis vérifier la cohérence avec terraform plan
  • Préférer le bloc déclaratif import (Terraform 1.5+) à la commande CLI historique
  • Générer un squelette de configuration HCL automatiquement depuis une ressource existante
  • Anticiper les limites de l'import sur une infrastructure existante volumineuse

Dans quel contexte ?

Un bucket S3 a été créé manuellement dans la console AWS il y a plusieurs mois, avant même que l'équipe n'adopte Terraform (leçons précédentes). Il contient des données de production critiques qu'il est hors de question de recréer. L'équipe veut désormais que Terraform "prenne le relais" de la gestion de ce bucket, sans jamais y toucher physiquement.

D'abord, il faut comprendre ce que l'import fait réellement

Importer une ressource associe un ID réel du cloud à un bloc resource déjà écrit dans le code, en modifiant uniquement le STATE — jamais la ressource elle-même. Rien n'est recréé, rien n'est modifié dans le cloud : seule la "mémoire" de Terraform change pour refléter que cette ressource est désormais sous sa gestion.

C'est une nuance essentielle par rapport à un apply classique : l'import est une opération purement locale au state, sans le moindre appel de création ou de modification vers l'API cloud.

ÉtapeActionRisque si sautée
1. Écrire le bloc resourceDécrire la ressource dans le codeTerraform ne sait pas où associer l'import
2. Importer (CLI ou bloc import)Associer l'ID réel au blocSans ça, le state ignore la ressource
3. Vérifier avec terraform planConfirmer l'absence de diffUne config incomplète recréerait la ressource au prochain apply

Prérequis

Une bonne compréhension du state Terraform (voir la leçon dédiée) est indispensable : l'import ne fait rien d'autre que manipuler ce fichier, de façon plus sûre qu'un terraform state push manuel.

Une fois l'import effectué, une étape ne doit JAMAIS être sautée

Piège fréquent

Après un import, si terraform plan affiche un diff, cela signifie que le bloc resource écrit dans le code ne décrit pas EXACTEMENT la ressource réelle. Au prochain apply, Terraform tenterait de "corriger" cet écart — ce qui peut aller jusqu'à recréer la ressource dans le pire des cas. Un plan sans diff après import est la seule confirmation fiable que tout est cohérent.

Maintenant, une amélioration notable depuis Terraform 1.5 : le bloc import déclaratif

Plutôt que de lancer une commande CLI séparée (facile à oublier, à mal cibler), le bloc import s'écrit directement dans un fichier .tf et s'exécute comme une étape normale du plan/apply, avec une visibilité complète AVANT toute application — bien plus sûr que la commande historique.

Astuce

terraform plan -generate-config-out=generated.tf va encore plus loin : il génère automatiquement une proposition de bloc resource correspondant à la ressource importée, évitant de deviner manuellement chaque attribut. Ce fichier généré doit toujours être relu et ajusté avant d'être utilisé tel quel — il s'agit d'un point de départ, pas d'un résultat final fiable à 100%.

Le piège à connaître avant de continuer

Importer une infrastructure existante volumineuse, ressource par ressource, devient vite un travail considérable si fait entièrement à la main. Des outils tiers comme terraformer peuvent accélérer ce travail en masse, mais nécessitent toujours une relecture attentive du résultat généré.

Maintenant que l'import de ressources isolées est maîtrisé, la prochaine leçon aborde un sujet complémentaire : comment Terraform détermine l'ORDRE dans lequel il crée, modifie et détruit ses ressources.

Commandes & code

Import de ressources existantes

bash
# Cas courant : une ressource a été créée manuellement (console cloud) et doit être reprise par Terraform
# Objectif : faire correspondre le state Terraform à cette ressource, SANS la recréer
hcl
# Étape 1 : écrire le bloc resource correspondant (attributs minimaux, à affiner ensuite)
resource "aws_s3_bucket" "bucket_existant" {
  bucket = "mon-bucket-cree-manuellement"
}
bash
# Étape 2 : importer la ressource réelle dans le state (associe l'ID réel au bloc "resource")
terraform import aws_s3_bucket.bucket_existant mon-bucket-cree-manuellement

# Étape 3 : vérifier qu'il n'y a AUCUN diff entre la config écrite et l'état réel importé
terraform plan
# Si plan affiche des changements -> la config .tf doit être ajustée pour matcher l'existant EXACTEMENT
hcl
# --- Depuis Terraform 1.5+ : bloc "import" déclaratif (préféré à la commande import) ---
# import.tf
import {
  to = aws_s3_bucket.bucket_existant
  id = "mon-bucket-cree-manuellement"
}

resource "aws_s3_bucket" "bucket_existant" {
  bucket = "mon-bucket-cree-manuellement"
}
bash
# Le bloc "import" génère un plan visible AVANT application (plus sûr que la commande CLI)
terraform plan                          # montre "will be imported" pour la ressource concernée
terraform apply

# Générer automatiquement le squelette de configuration HCL depuis une ressource existante
terraform plan -generate-config-out=generated.tf
# Écrit une proposition de bloc "resource" dans generated.tf, à relire et ajuster avant de l'utiliser
bash
# Pièges fréquents de l'import :
# - Import du state seul : les attributs "hors state" (dépendances entre ressources) ne sont PAS déduits automatiquement
# - Toujours faire un "terraform plan" juste après import : tout diff signale une config .tf incomplète/incorrecte
# - Importer resource par resource peut être long sur une infra existante volumineuse -> outils tiers (ex: terraformer)

Résumé

  • terraform import (ou le bloc déclaratif import) associe une ressource réelle existante à un bloc resource du code.
  • Après import, un terraform plan sans diff confirme que la config HCL décrit fidèlement l'état réel.
  • -generate-config-out génère un squelette HCL automatiquement, à toujours relire avant utilisation.

Exercices pratiques

1 disponible
1

Mission : reprendre un bucket créé manuellement sans le recréer

Objectif : Importer une ressource existante dans le state et vérifier que la configuration écrite correspond exactement à la réalité du cloud.

Contexte

Un bucket S3 nommé mon-bucket-cree-manuellement existe en production depuis plusieurs mois, créé à la main dans la console AWS. L'équipe a écrit un bloc resource "aws_s3_bucket" "bucket_existant" minimal et vient d'importer ce bucket dans le state. terraform plan affiche pourtant encore un changement : l'ajout d'une configuration de versioning absente du code.

Résoudre l’exercice →