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.
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.cometregistry.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 :
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 versionCréer le projet
mkdir -p ~/terraform-demo
cd ~/terraform-demoDéclarer Terraform et les fournisseurs
Créez versions.tf :
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 :
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 :
ssh_user = "VOTRE_USER"
servers = {
web1 = "IP_SERVEUR"
}Décrire les ressources
Créez un modèle d’inventaire inventory.tftpl :
[web]
%{ for name, ip in servers ~}
${name} ansible_host=${ip} ansible_user=${ssh_user}
%{ endfor ~}Créez ensuite main.tf :
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 :
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 :
.terraform/
*.tfstate
*.tfstate.*
*.tfvars
*.tfplan
generated/Versionnez en revanche .terraform.lock.hcl, qui fixe les versions exactes des fournisseurs.
Initialiser et valider
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 :
terraform plan -out=demo.tfplan
terraform apply demo.tfplanDans 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 :
terraform output
terraform output -raw inventory_path; echo
cat generated/inventory.ini
ls -l generated/
terraform planLe 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 :
servers = {
web1 = "IP_SERVEUR"
web2 = "IP_SECOND_SERVEUR"
}terraform plan -out=demo.tfplan
terraform apply demo.tfplanLe 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 :
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 :
chmod 600 terraform.tfstate terraform.tfstate.backup demo.tfplan 2>/dev/null || trueGérer les secrets
Ne placez pas de secret dans les fichiers .tf. Passez-le plutôt par une variable d’environnement TF_VAR_ :
variable "api_token" {
description = "Jeton de l'API utilisée par le fournisseur"
type = string
sensitive = true
}read -rs TF_VAR_api_token
export TF_VAR_api_token
terraform plan -out=demo.tfplan
unset TF_VAR_api_tokenSi 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.
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 :
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 :
terraform init -migrate-stateUtiliser 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 :
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 :
sudo apt update
sudo apt install --only-upgrade terraform
terraform init -upgrade
terraform planRelisez 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 :
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 :
terraform plan -destroy -out=destroy.tfplan
terraform apply destroy.tfplanDans 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 :
terraform init -upgradeBackend 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é :
terraform force-unlock ID_DU_VERROUSaved 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 :
curl -I https://registry.terraform.io/.well-known/terraform.jsonNo 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.