FR

Applications

Débuter avec Terraform

Découvrez Terraform sur Debian ou Ubuntu : fournisseurs, plan, apply, gestion de l'état et protection des secrets, avec un exemple générique.

6 min de lecture, mis à jour le 18 novembre 2026

Sur cette page

Vos valeurs

Renseignez-les une fois, les commandes du guide se mettent à jour.

Terraform décrit une infrastructure dans des fichiers texte, compare cette description à l’existant, puis applique uniquement les changements nécessaires. Il s’appuie sur des fournisseurs (providers), qui savent dialoguer avec un service donné.

Ce guide présente les bases avec un exemple qui fonctionne sans compte externe : Terraform génère un mot de passe aléatoire, un inventaire Ansible et un fichier de configuration local.

Terme Signification
Fournisseur Extension qui donne accès à un service ou à une ressource
Ressource Objet géré par Terraform
Variable Valeur d’entrée de la configuration
Sortie (output) Valeur exposée après l’application
Plan Liste des changements que Terraform propose
État (state) Fichier qui relie la configuration aux objets réels

Prérequis

  • Une machine sous Debian 12/13 ou Ubuntu 22.04/24.04 : votre poste ou un serveur d’administration
  • Un utilisateur disposant de sudo
  • Un accès HTTPS sortant vers apt.releases.hashicorp.com et registry.terraform.io

Terraform n’écoute sur aucun port et cet exemple ne demande d’ouvrir aucun port entrant.

Installer Terraform

Ajoutez le dépôt officiel de HashiCorp, puis installez le paquet :

Terminal
sudo apt update
sudo apt install -y wget gpg lsb-release
wget -O - https://apt.releases.hashicorp.com/gpg | sudo gpg --dearmor -o /usr/share/keyrings/hashicorp-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/hashicorp-archive-keyring.gpg] https://apt.releases.hashicorp.com $(grep -oP '(?<=UBUNTU_CODENAME=).*' /etc/os-release || lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/hashicorp.list
sudo apt update
sudo apt install -y terraform
terraform version

Créer le projet

Terminal
mkdir -p ~/terraform-demo
cd ~/terraform-demo

Déclarer Terraform et les fournisseurs

Créez versions.tf :

hcl
terraform {
  required_version = ">= 1.11"

  required_providers {
    local = {
      source  = "hashicorp/local"
      version = "~> 2.9"
    }
    random = {
      source  = "hashicorp/random"
      version = "~> 3.9"
    }
  }
}

Déclarer les variables

Créez variables.tf :

hcl
variable "ssh_user" {
  description = "Utilisateur SSH des serveurs"
  type        = string
}

variable "servers" {
  description = "Serveurs à inscrire dans l'inventaire (nom => adresse IP)"
  type        = map(string)

  validation {
    condition     = length(var.servers) > 0
    error_message = "Déclarez au moins un serveur."
  }
}

Donnez-leur une valeur dans terraform.tfvars, chargé automatiquement :

hcl
ssh_user = "VOTRE_USER"

servers = {
  web1 = "IP_SERVEUR"
}

Décrire les ressources

Créez un modèle d’inventaire inventory.tftpl :

Texte
[web]
%{ for name, ip in servers ~}
${name} ansible_host=${ip} ansible_user=${ssh_user}
%{ endfor ~}

Créez ensuite main.tf :

hcl
resource "random_password" "app_token" {
  length  = 32
  special = false
}

resource "local_file" "inventory" {
  filename        = "${path.module}/generated/inventory.ini"
  file_permission = "0644"

  content = templatefile("${path.module}/inventory.tftpl", {
    servers  = var.servers
    ssh_user = var.ssh_user
  })
}

resource "local_sensitive_file" "app_env" {
  filename        = "${path.module}/generated/app.env"
  file_permission = "0600"
  content         = "APP_TOKEN=${random_password.app_token.result}\n"
}

Et outputs.tf :

hcl
output "inventory_path" {
  description = "Chemin de l'inventaire généré"
  value       = local_file.inventory.filename
}

output "app_token" {
  description = "Jeton généré pour l'application"
  value       = random_password.app_token.result
  sensitive   = true
}

Exclure les fichiers locaux de Git

Créez .gitignore avant votre premier commit :

Texte
.terraform/
*.tfstate
*.tfstate.*
*.tfvars
*.tfplan
generated/

Versionnez en revanche .terraform.lock.hcl, qui fixe les versions exactes des fournisseurs.

Initialiser et valider

Terminal
terraform init
terraform fmt
terraform validate
Commande Effet
terraform init Télécharge les fournisseurs et prépare le dossier
terraform fmt Normalise la mise en forme
terraform validate Contrôle la cohérence de la configuration

Planifier et appliquer

Enregistrez le plan pour appliquer exactement ce que vous avez relu :

Terminal
terraform plan -out=demo.tfplan
terraform apply demo.tfplan

Dans un plan, + signale une création, ~ une modification, - une suppression et -/+ un remplacement. Lisez toujours ces lignes avant d’appliquer, surtout les suppressions et les remplacements.

Vérifiez le résultat :

Terminal
terraform output
terraform output -raw inventory_path; echo
cat generated/inventory.ini
ls -l generated/
terraform plan

Le fichier app.env doit avoir les droits -rw-------, la sortie app_token doit apparaître comme <sensitive>, et le dernier plan doit annoncer No changes.

Modifier l’infrastructure

Ajoutez un serveur dans terraform.tfvars :

hcl
servers = {
  web1 = "IP_SERVEUR"
  web2 = "IP_SECOND_SERVEUR"
}
Terminal
terraform plan -out=demo.tfplan
terraform apply demo.tfplan

Le plan annonce le remplacement du seul fichier d’inventaire (1 to add, 1 to destroy) : le jeton reste identique. Le fichier généré peut ensuite servir à un playbook, comme dans le guide Automatiser ses serveurs avec Ansible.

Comprendre l’état

Après apply, Terraform enregistre dans terraform.tfstate ce qu’il gère. Consultez-le avec les commandes prévues, sans le modifier à la main :

Terminal
terraform state list
terraform state show local_file.inventory
Commande Usage
terraform state list Lister les ressources suivies
terraform state show ADRESSE Afficher une ressource
terraform state mv SOURCE DESTINATION Renommer une ressource sans la recréer
terraform state rm ADRESSE Cesser de suivre une ressource, sans la supprimer
terraform import ADRESSE ID Rattacher un objet existant, si le fournisseur le permet

Limitez au minimum les droits des fichiers locaux :

Terminal
chmod 600 terraform.tfstate terraform.tfstate.backup demo.tfplan 2>/dev/null || true

Gérer les secrets

Ne placez pas de secret dans les fichiers .tf. Passez-le plutôt par une variable d’environnement TF_VAR_ :

hcl
variable "api_token" {
  description = "Jeton de l'API utilisée par le fournisseur"
  type        = string
  sensitive   = true
}
Terminal
read -rs TF_VAR_api_token
export TF_VAR_api_token
terraform plan -out=demo.tfplan
unset TF_VAR_api_token

Si la valeur ne sert qu’à configurer un fournisseur ou à alimenter un argument en écriture seule (write-only), déclarez-la comme éphémère : Terraform ne l’enregistre alors ni dans l’état ni dans le plan.

hcl
variable "api_token" {
  description = "Jeton de l'API utilisée par le fournisseur"
  type        = string
  sensitive   = true
  ephemeral   = true
}

Une variable éphémère doit être fournie de nouveau lors de terraform apply, et elle ne peut pas être utilisée dans n’importe quel argument. Pour un coffre-fort de secrets, consultez le guide Installer HashiCorp Vault.

Stocker l’état à distance

Dès que plusieurs personnes ou machines utilisent le projet, placez l’état dans un stockage distant, chiffré, privé et avec verrouillage. Voici un exemple générique avec le backend s3 à ajouter dans le bloc terraform :

hcl
terraform {
  backend "s3" {
    bucket       = "mon-etat-terraform"
    key          = "demo/terraform.tfstate"
    region       = "eu-west-1"
    encrypt      = true
    use_lockfile = true
  }
}

Fournissez les identifiants par l’environnement, jamais dans ce bloc, puis migrez l’état existant :

Terminal
terraform init -migrate-state

Utiliser un autre fournisseur

La logique reste la même pour tout service disposant d’un fournisseur. Cherchez-le dans le registre Terraform, lisez sa documentation et vérifiez qui le maintient. La forme générale est la suivante. editeur/service et les arguments sont fictifs :

hcl
terraform {
  required_providers {
    service = {
      source  = "editeur/service"
      version = "~> 1.0"
    }
  }
}

provider "service" {
  api_token = var.api_token
}

Donnez au jeton d’API les droits strictement nécessaires, et commencez sur un projet de test : un apply agit réellement sur les ressources du compte.

Mettre à jour

Terraform se met à jour avec APT. Les fournisseurs se mettent à jour dans les limites de version :

Terminal
sudo apt update
sudo apt install --only-upgrade terraform
terraform init -upgrade
terraform plan

Relisez le plan, puis versionnez le fichier .terraform.lock.hcl s’il a changé.

Sauvegarder

Conservez la configuration et .terraform.lock.hcl dans un dépôt Git privé. Pour l’état, activez le versionnage du stockage distant. Avec un état local, créez une copie protégée :

Terminal
install -m 600 /dev/null "$HOME/terraform-demo-$(date +%F).tfstate"
terraform state pull > "$HOME/terraform-demo-$(date +%F).tfstate"

Cette copie contient des secrets : stockez-la chiffrée et hors du serveur. Si l’état est perdu, Terraform ne sait plus quels objets il gère.

Détruire les ressources

Prévisualisez la suppression, puis appliquez-la :

Terminal
terraform plan -destroy -out=destroy.tfplan
terraform apply destroy.tfplan

Dans cet exemple, seuls les fichiers locaux et le jeton sont supprimés. Avec un vrai fournisseur, cette opération peut effacer des services et leurs données.

En cas de problème

Inconsistent dependency lock file

Les fournisseurs demandés ne correspondent pas au fichier de verrouillage. Après avoir vérifié le changement :

Terminal
terraform init -upgrade

Backend initialization required

La configuration du backend a changé. Relancez terraform init, ou terraform init -migrate-state pour déplacer l’état.

Error acquiring the state lock

Une autre exécution détient le verrou, ou une exécution s’est interrompue. Vérifiez d’abord qu’aucune commande n’est en cours. Ensuite seulement, utilisez l’identifiant affiché :

Terminal
terraform force-unlock ID_DU_VERROU

Saved plan is stale

L’état a changé depuis la création du plan. Générez un nouveau plan, relisez-le, puis appliquez-le.

Failed to query available provider packages

Vérifiez le nom du fournisseur, la contrainte version et l’accès à registry.terraform.io :

Terminal
curl -I https://registry.terraform.io/.well-known/terraform.json

No value for required variable

Renseignez la variable dans terraform.tfvars, avec -var, ou avec TF_VAR_nom.

Le plan veut remplacer une ressource

Cherchez la mention forces replacement dans le plan. Si vous avez seulement renommé une ressource, utilisez terraform state mv ou un bloc moved plutôt que d’accepter sa recréation.

Références