Terraform workspace : environnements et state séparé

À la fin de ce tutoriel, vous saurez choisir entre workspaces CLI, dossiers/repos séparés et Terraform Cloud / HCP Terraform, manipuler les commandes workspace (list, new, select, show, delete), utiliser terraform.workspace pour nommer les ressources, comprendre que chaque workspace possède un state séparé, connaître les limites (même config, pas de multi-compte magique), puis réaliser un lab léger dev / staging en Region ca-central-1 — Terraform ≥ 1.9, AWS provider ~> 5.0.

Niveau : Intermédiaire · Temps estimé : 30–40 min · Versions testées : Terraform 1.16.2 (série ≥ 1.9), AWS provider ~> 5.0 · Dernière vérification : 2026-09-10

Slug : terraform-workspace (aligné menu live) · Série : Terraform · Remplace / fusionne : #1684 (Terraform Workspace)

Statut : HOLD — draft only (ne pas publier sur WordPress / Rank Math)

Live absorbé (EN court, 2024) : concept multi-state + commandes list/new/select + exemple locals + aws_instance nommé ${terraform.workspace}-instance — conservé ci-dessous comme variante lab, rien n’est retiré du parcours SSM.

Prérequis

• Avoir suivi Modules registry (terraform-modules-registry) : init, lockfile, Region root
• Avoir suivi Variables (terraform-variables) et idéalement State backend S3 (terraform-state-backend-s3)
• Terraform ≥ 1.9, AWS CLI v2, profil de lab (aws sts get-caller-identity OK)
• Comprendre le cycle init → plan → apply → destroy (workflow P2)

Coût estimé : quasi 0 € (ressource légère type bucket S3 lab ou SSM Parameter). Destroy obligatoire après le lab. Aucun secret dans le HCL / tfvars.

Auth sans secrets. Utilisez AWS_PROFILE / SSO. Jamais d’access_key / secret_key dans le provider. Les workspaces ne remplacent pas une bonne gestion des credentials par compte.

Ce que nous allons construire

Lab terraform workspace (ca-central-1)
  ├── versions.tf / providers.tf   → TF ≥ 1.9, aws ~> 5.0, region ca-central-1
  ├── main.tf                      → ressource légère + terraform.workspace
  ├── workspace new/select         → dev puis staging (states séparés)
  ├── apply par workspace          → noms distincts (suffixe env)
  └── destroy ×2 + delete staging  → nettoyage propre

(Alt : « Terraform workspace : environnements CLI, state séparé et naming — ca-central-1 ».)

Ce guide enrichit le post WordPress #1684 (sans supprimer l’intention live). Focus : terraform workspace CLI, dossiers/repos vs TFC/HCP, lab dev/staging.

Étape 1 — Workspaces CLI vs dossiers/repos vs TFC/HCP

Trois approches courantes pour isoler des environnements :

Approche	Idée	State	Quand l’utiliser
Workspaces CLI	Même code, plusieurs états nommés (default, dev, staging)	Fichiers/backends distincts par workspace	Lab, petite équipe, même compte AWS
Dossiers / repos séparés	envs/dev, envs/prod ou un repo par env	Un state (ou backend) par dossier	Prod stricte, configs qui divergent
TFC / HCP Terraform	Workspaces managés (UI/API), runs cloud	State distant géré + politiques	Équipes, RBAC, VCS-driven, multi-env

Le terraform workspace CLI commute l’état sur une seule config — pas un env Kubernetes ni un compte AWS. En prod mature : souvent un dossier/pipeline par env + backend S3, ou workspaces HCP Terraform. Mot-clé : isolation de state, pas de magie multi-compte.

Étape 2 — Commandes : list, new, select, show, delete

Dans un répertoire déjà initialisé (terraform init) :

terraform workspace list     # affiche * sur le workspace courant
terraform workspace show     # nom du workspace actuel (souvent default)
terraform workspace new dev  # crée + sélectionne « dev »
terraform workspace select staging
terraform workspace delete staging   # seulement si vide / non courant

Commande	Effet
list	Liste ; * = actif
new <nom>	Crée le state et bascule dessus
select <nom>	Change de workspace
show	Nom courant (utile en CI)
delete <nom>	Après destroy ; impossible sur le courant

Le workspace default existe toujours — ne le supprimez pas. Backend S3 : états non-default souvent sous env:/<workspace>/… (voir State S3).

Étape 3 — terraform.workspace dans le HCL (naming)

La valeur interpolée terraform.workspace renvoie le nom du workspace actif (default, dev, staging…). Servez-vous-en pour suffixer noms et tags — pas pour cacher des secrets.

# versions.tf
terraform {
  required_version = ">= 1.9.0"
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.0"
    }
  }
}

# providers.tf
provider "aws" {
  region = "ca-central-1"
  # Auth : AWS_PROFILE / SSO — jamais de clés ici
}

# variables.tf
variable "project" {
  type        = string
  description = "Préfixe projet (unique dans le compte)."
}

# main.tf — naming basé sur terraform.workspace
resource "aws_ssm_parameter" "lab_marker" {
  name  = "/${var.project}/${terraform.workspace}/lab-marker"
  type  = "String"
  value = "workspace=${terraform.workspace}"

  tags = {
    ManagedBy   = "terraform"
    Lab         = "terraform-workspaces"
    Environment = terraform.workspace
    Region      = "ca-central-1"
  }
}

# outputs.tf
output "workspace_name" {
  description = "Workspace Terraform actif."
  value       = terraform.workspace
}

output "parameter_name" {
  description = "Chemin SSM Parameter (unique par workspace)."
  value       = aws_ssm_parameter.lab_marker.name
}

Points SEO / bonnes pratiques :

• Préférez "/app/${terraform.workspace}/…" plutôt que des noms globaux identiques.
• Combinez avec var.project pour éviter les collisions entre labs.
• Évitez de brancher toute la logique métier sur default : créez explicitement dev / staging.

Variante live absorbée — EC2 + locals

Le post #1684 montrait locals { instance_name = "${terraform.workspace}-instance" } + aws_instance tagué Name = local.instance_name. Même idée que le SSM ci-dessus ; en lab préférez SSM (quasi 0 €). Si EC2 : AMI via data source (pas d’AMI figée), t3.micro, Region ca-central-1, destroy obligatoire.

Étape 4 — State séparé par workspace

Chaque terraform workspace a son propre state (local : terraform.tfstate.d/<nom>/ ; distant : préfixe/clé isolé).

1. plan dans dev ne voit pas staging.
2. Un mauvais select crée/détruit l’autre env.
3. Même HCL ; changent terraform.workspace / tfvars.

même main.tf
   ├── workspace « dev »     → state A → /projet/dev/lab-marker
   └── workspace « staging » → state B → /projet/staging/lab-marker

Force = réutilisation ; risque = erreur de sélection.

Étape 5 — Limites (même config, pas magie multi-compte)

Les workspaces CLI ne font pas :

Attente	Réalité
Compte AWS distinct par env	Non — mêmes credentials sauf config avancée
HCL différent par env	Non — même code ; divergez via variables
Isolation sécu forte	Faible si un profil peut tout détruire
Remplacer TFC/HCP	Non (pas de RBAC runs cloud)

Évitez les workspaces CLI seuls si prod/lab ne doivent jamais partager backend/droits, si les configs divergent fort, ou en multi-compte (assume role + pipelines). Règle P2 : levier d’état pour même config / même compte ; prod critique → dossiers + State S3 (ou HCP).

Étape 6 — Lab léger ca-central-1 (dev / staging + destroy)

Ressource légère : aws_ssm_parameter (gratuit à l’échelle lab). Variante S3 possible si vous préférez un bucket force_destroy — ici SSM pour rester minimal.

mkdir -p ~/terraform-workspaces-lab && cd ~/terraform-workspaces-lab
# collez versions.tf, providers.tf, variables.tf, main.tf, outputs.tf (étape 3)

export AWS_PROFILE=lab
export AWS_REGION=ca-central-1
PROJECT="votreprenom20260910"

terraform init
terraform fmt
terraform validate

# --- Environnement DEV ---
terraform workspace new dev
terraform workspace show    # → dev
terraform plan  -var="project=${PROJECT}"
terraform apply -auto-approve -var="project=${PROJECT}"
terraform output

# --- Environnement STAGING (autre state) ---
terraform workspace new staging
terraform plan  -var="project=${PROJECT}"
terraform apply -auto-approve -var="project=${PROJECT}"

terraform workspace list
# * staging
#   dev
#   default

# Vérification CLI (chemins distincts)
aws ssm get-parameter --name "/${PROJECT}/dev/lab-marker" --region ca-central-1
aws ssm get-parameter --name "/${PROJECT}/staging/lab-marker" --region ca-central-1

Nettoyage dans chaque workspace avant de supprimer le workspace :

# Toujours destroy AVANT delete
terraform workspace select staging
terraform destroy -auto-approve -var="project=${PROJECT}"

terraform workspace select dev
terraform destroy -auto-approve -var="project=${PROJECT}"

terraform workspace select default
terraform workspace delete staging
terraform workspace delete dev

cd ~
rm -rf ~/terraform-workspaces-lab

Confirmez l’absence des paramètres SSM. Si vous aviez utilisé un bucket, vérifiez aussi S3 en ca-central-1.

Étape 7 — Checklist

1. Choisir CLI workspaces, dossiers/repos ou TFC/HCP selon maturité.
2. Maîtriser list / new / select / show / delete.
3. terraform.workspace pour naming/tags — jamais pour les secrets.
4. Un state par workspace — show avant tout apply.
5. Pas de multi-compte magique via un simple workspace.
6. Lab dev/staging en ca-central-1, puis destroy ×2.
7. Backend S3 : préfixe env:/ (tuto State S3).

Nettoyage

Rejouez le bloc destroy/delete de l’étape 6 (staging puis dev, puis select default), puis rm -rf ~/terraform-workspaces-lab. Vérifiez l’absence des paramètres SSM en ca-central-1.

Erreurs fréquentes

Symptôme	Cause	Correction
Ressources « fantômes » / plan inattendu	Mauvais workspace (select)	terraform workspace show avant plan/apply
Workspace already exists	new sur un nom déjà créé	select au lieu de new
Impossible de delete	Workspace courant ou state non vide	select default, destroy d’abord, puis delete
Collision de noms AWS	Naming sans terraform.workspace	Suffixer chemins / buckets avec le workspace
Prod détruite depuis un laptop	Même backend + droits larges + workspace oublié	Séparer backends/comptes ; CI gated ; TFC/HCP
Confusion default vs dev	Apply oublié sur default	Créer explicitement les envs ; éviter de travailler dans default
State local divergents entre collègues	Pas de backend distant	Passer à State S3 + verrouillage

Quiz (3 questions)

1. Que partage-t-on entre deux terraform workspace CLI ?

• A. Le même fichier de state
• B. La même configuration HCL, mais des states séparés
• C. Automatiquement deux comptes AWS

2. À quoi sert surtout terraform.workspace dans le HCL ?

• A. Stocker les access keys
• B. Nommer ressources / tags selon l’environnement actif
• C. Remplacer required_providers

3. Avant terraform workspace delete staging, que faites-vous ?

• A. Rien — delete détruit les ressources AWS
• B. Destroy dans staging, puis basculer ailleurs, puis delete
• C. Supprimer uniquement le dossier .terraform

Réponses : 1‑B · 2‑B · 3‑B

Pourquoi / quand utiliser les workspaces CLI

Les workspaces isolent des states pour une même configuration (souvent dev / staging). Pratique pour un lab léger ou une démo. Ce n’est pas une isolation multi-compte magique : même code, mêmes providers, risques de mélange si vous n’êtes pas discipliné.

Workspaces vs dossiers vs Terraform Cloud

Approche	Isoler	Quand
Workspaces CLI	State séparé, même dossier	Variantes proches, même compte/Region
Dossiers / repos	Config + state séparés	Écarts forts (prod ≠ dev), droits différents
TFC / HCP Terraform	Gouvernance remote	Équipes, politiques, UI runs

Ne forcez pas les workspaces CLI si prod doit vivre dans un autre compte AWS.

Pièges workspaces

• Oublier terraform workspace select avant un apply : vous touchez default par erreur.
• Croire que terraform.workspace change à lui seul la Region ou le compte.
• Supprimer un workspace sans avoir détruit ses resources : state distant orphelin / ressources fantômes.
• Nommer les resources sans préfixe workspace : collisions de noms globaux (S3).
• Enchaîner les workspaces sans destroy en fin de lab ca-central-1.

Bonnes pratiques de naming

Incorporez terraform.workspace dans les noms et tags (Environment = terraform.workspace). Vérifiez le plan : chaque workspace doit créer ses adresses sans écraser l’autre.

FAQ workspaces

default peut-il être renommé ? Il existe toujours ; créez dev / staging plutôt que de surcharger default si possible.

Workspaces + backend S3 ? Oui : Terraform sépare les préfixes/chemins de state par workspace selon le backend.

Puis-je avoir des variables différentes par workspace ? Oui via terraform.workspace dans des conditionals ou des maps locals ; ou des tfvars distincts sélectionnés par la CI.

TF ≥ 1.9 exigé ? Oui pour rester aligné avec la série ; auth toujours sans secrets dans le HCL.

Quand migrer vers des dossiers séparés ? Dès que les divergences de config ou d’IAM dépassent quelques conditionals.

Pour aller plus loin

• Doc : Workspaces CLI, terraform.workspace, HCP Terraform workspaces
• Sur ce site : Modules registry, State S3, Variables ; suite Provisioners

Maillage série Terraform (P2)

← Précédent	Modules registry (terraform-modules-registry)
→ Suivant	Provisioners (terraform-provisioners)
Aussi	State S3 (terraform-state-backend-s3) · Variables (terraform-variables)
Carte	Overview · … · Modules registry · Workspaces · Provisioners · …

Cas réel — le même state « default » pour staging et prod

Sans workspace (ou mieux : sans backends séparés), un -var env=prod sur le state de staging est une question de minutes. Les workspaces isolent le state, pas la qualité du module. Un workspace n’excuse pas les noms globaux (S3) ni les secrets en clair.

Piège : terraform workspace select prod oublié, apply sur default. Le plan a l’air petit, les ressources prod ne sont pas celles que vous croyez. Affichez terraform workspace show dans le prompt shell. En série P2, un workspace lab suffit ; la prod mérite un backend dédié.

À retenir : workspace = isolation de state, pas une baguette multi-compte. Combinez-le avec des backends et des comptes AWS distincts dès que l’enjeu dépasse le lab.

Retour parcours Terraform — hub de la série et leçons sœurs.