Les workspaces Terraform

Un workspace Terraform est une copie isolée du state au sein d’un même projet. Un seul jeu de fichiers .tf, mais plusieurs états logiques. Avec un backend local, chaque workspace finit par avoir son propre fichier de state. Avec un backend distant, les workspaces restent dans le même backend et partagent les mêmes credentials. Le workspace par défaut s’appelle default et existe dès le premier terraform init. Les workspaces supplémentaires se créent avec terraform workspace new.

Analogie

Un workspace, c’est comme un profil utilisateur sur un ordinateur. L’ordinateur est le même (le code Terraform), mais chaque profil a son propre bureau, ses propres fichiers et ses propres paramètres (le state).

Prérequis : avoir suivi les premières infrastructures et comprendre le state Terraform.

Ce que vous allez apprendre

• Créer un workspace avec terraform workspace new
• Basculer entre workspaces avec terraform workspace select
• Adapter les ressources au workspace actif avec terraform.workspace
• Comprendre l’isolation des states entre workspaces
• Supprimer un workspace avec terraform workspace delete

Qu’est-ce qu’un workspace ?

Par défaut, Terraform utilise un seul state stocké dans terraform.tfstate. Quand vous créez un workspace supplémentaire, Terraform crée un répertoire terraform.tfstate.d/ avec un sous-dossier par workspace, chacun contenant son propre state :

mon-projet/
├── main.tf
├── terraform.tfstate              # state du workspace "default"
└── terraform.tfstate.d/
    └── prod/
        └── terraform.tfstate      # state du workspace "prod"

Chaque workspace gère ses propres ressources. Déployer dans le workspace prod ne touche pas les ressources du workspace default, et inversement.

Backend local vs backend distant

L’arborescence terraform.tfstate.d/ montrée ici correspond au backend local. Avec un backend distant, Terraform n’écrit pas ce stockage local de la même manière : les workspaces restent séparés logiquement, mais dans le même backend et avec les mêmes credentials.

Workspace CLI ≠ workspace HCP Terraform

Le workspace décrit ici est une fonctionnalité CLI locale. Ne le confondez pas avec le workspace HCP Terraform (ex-Terraform Cloud), qui est une unité d’exécution hébergée avec droits, variables, historique et exécution distante. Les deux portent le même nom mais fonctionnent très différemment.

Commandes de base

Commande	Rôle
terraform workspace list	Lister les workspaces (* = actif)
terraform workspace show	Afficher le nom du workspace actif
terraform workspace new NOM	Créer un workspace et basculer dessus
terraform workspace select NOM	Basculer sur un workspace existant
terraform workspace delete NOM	Supprimer un workspace (doit être vide)

Glissez pour voir

Créer et utiliser un workspace

1. Vérifier le workspace actif

   Par défaut, vous êtes dans le workspace default :

   terraform workspace show

   default

2. Créer un nouveau workspace

   terraform workspace new prod

   Created and switched to workspace "prod"!
   
   You're now on a new, empty workspace. Workspaces isolate their state,
   so if you run "terraform plan" Terraform will not see any existing state
   for this configuration.

   Terraform crée le workspace et bascule automatiquement dessus. Le nouveau workspace a un state vide — même si des ressources existent dans default.

3. Lister les workspaces

   terraform workspace list

     default
   * prod

   L’étoile (*) indique le workspace actif.

4. Basculer entre workspaces

   terraform workspace select default

   Switched to workspace "default".

Adapter les ressources au workspace

La variable spéciale terraform.workspace contient le nom du workspace actif. Utilisez-la dans vos configurations pour créer des ressources différentes selon l’environnement :

resource "libvirt_network" "net" {
  name      = "ws-${terraform.workspace}-net"
  #           ↑ le nom inclut le workspace : "ws-default-net" ou "ws-prod-net"
  autostart = true

  forward = {
    mode = "nat"
  }

  ips = [{
    address = terraform.workspace == "prod" ? "10.10.50.1" : "10.10.51.1"
    #         ↑ condition : prod → réseau .50, sinon → réseau .51
    netmask = "255.255.255.0"
    dhcp = {
      ranges = [{
        start = terraform.workspace == "prod" ? "10.10.50.100" : "10.10.51.100"
        end   = terraform.workspace == "prod" ? "10.10.50.200" : "10.10.51.200"
      }]
    }
  }]
}

resource "libvirt_volume" "disk" {
  name     = "ws-${terraform.workspace}-disk.qcow2"
  pool     = "default"
  capacity = terraform.workspace == "prod" ? 8 * 1024 * 1024 * 1024 : 4 * 1024 * 1024 * 1024
  #          ↑ prod → 8 Go, sinon → 4 Go

  backing_store = {
    path = "/chemin/vers/ubuntu-24.04-cloudimg.img"
    format = { type = "qcow2" }
  }

  target = {
    format = { type = "qcow2" }
  }
}

Résultat dans le workspace default

terraform workspace select default
terraform apply -auto-approve

Apply complete! Resources: 2 added, 0 changed, 0 destroyed.

Outputs:

disk_capacity_gb = 4
disk_name = "ws-default-disk.qcow2"
network_name = "ws-default-net"
workspace_name = "default"

Résultat dans le workspace prod

terraform workspace select prod
terraform apply -auto-approve

Apply complete! Resources: 2 added, 0 changed, 0 destroyed.

Outputs:

disk_capacity_gb = 8
disk_name = "ws-prod-disk.qcow2"
network_name = "ws-prod-net"
workspace_name = "prod"

Le même code produit des ressources avec des noms, des adresses réseau et des capacités différentes selon le workspace.

Vérification : les ressources coexistent

Les deux ensembles de ressources existent simultanément dans l’infrastructure :

virsh net-list --all | grep ws-

 ws-default-net   active   yes         yes
 ws-prod-net      active   yes         yes

virsh vol-list default | grep ws-

 ws-default-disk.qcow2   /var/lib/libvirt/images/ws-default-disk.qcow2
 ws-prod-disk.qcow2      /var/lib/libvirt/images/ws-prod-disk.qcow2

Chaque workspace possède ses propres ressources gérées indépendamment.

Isolation de ressources, pas isolation de permissions

Cet exemple est adapté à un lab local ou à des tests. En backend distant, default et prod partagent toujours le même backend, la même configuration de verrouillage et les mêmes droits d’accès. Les workspaces isolent les ressources gérées, pas les permissions.

Supprimer un workspace

Avant de supprimer un workspace, il faut détruire ses ressources et basculer sur un autre workspace :

1. Basculer sur le workspace à supprimer

   terraform workspace select prod

2. Détruire les ressources

   terraform destroy -auto-approve

3. Basculer sur un autre workspace

   terraform workspace select default

4. Supprimer le workspace vide

   terraform workspace delete prod

   Deleted workspace "prod"!

Le workspace default ne peut pas être supprimé

Le workspace default existe toujours. Vous ne pouvez ni le supprimer, ni le renommer. C’est le workspace de base de tout projet Terraform.

Dépannage

Symptôme	Cause probable	Solution
Workspace "default" is your active workspace	Tentative de supprimer le workspace actif	Basculer sur un autre workspace d’abord
Workspace is not empty	Le workspace contient encore des ressources	terraform destroy avant de supprimer, ou -force pour passer outre (dangereux)
Ressources dupliquées dans l’infra	Oubli de basculer de workspace avant apply	Vérifier avec terraform workspace show avant chaque opération
terraform.workspace retourne default	Vous êtes dans le workspace par défaut	Créer un workspace avec workspace new ou basculer avec select

Glissez pour voir

Ne supprimez jamais un workspace avec -force en production

L’option -force supprime le workspace même s’il contient des ressources. Terraform perd alors la trace de ces ressources — elles continuent d’exister dans l’infrastructure mais ne sont plus gérées. Utilisez toujours terraform destroy avant workspace delete.

À retenir

• Un workspace est une copie isolée du state — pratique pour des variantes de ressources avec le même code
• Le workspace default existe toujours et ne peut pas être supprimé
• terraform.workspace retourne le nom du workspace actif — utilisez-le pour adapter les noms et les paramètres
• En backend local, les states sont stockés dans terraform.tfstate.d/<nom>/terraform.tfstate (sauf default qui reste à la racine)
• En backend distant, les workspaces partagent toujours le même backend et les mêmes credentials
• Détruire les ressources avant de supprimer un workspace — sinon elles deviennent orphelines
• Les workspaces sont adaptés aux tests et aux variations légères, pas à l’isolation forte d’environnements critiques

Prochaines étapes

Quand utiliser les workspaces Les cas d'usage légitimes des workspaces et les patterns qui fonctionnent.

Décider avec les workspaces Savoir quand les workspaces sont adaptés, et quand passer à une autre stratégie.

Variables par environnement Fichiers .tfvars par environnement pour paramétrer sans modifier le code.

×

📖 Voir la documentation →