Créer et piloter un workspace HCP Terraform

Un workspace HCP Terraform est l’unité de travail centrale de la plateforme : il contient votre configuration, votre state, vos variables et l’historique complet de vos runs. Ce guide vous accompagne dans la création de votre premier workspace CLI-driven et votre premier run distant.

Ce que vous allez apprendre

• Ce qu’est un workspace HCP Terraform et ce qu’il contient
• La différence fondamentale entre workspace CLI et workspace HCP
• Comment créer un workspace et lancer un run distant
• Les réglages essentiels : mode d’exécution, auto-apply, verrouillage
• Comment naviguer dans l’interface web pour suivre vos runs

Qu’est-ce qu’un workspace HCP Terraform

Analogie : le workspace est un bureau privé

Imaginez un open space. Chaque bureau (workspace) a ses propres dossiers (state), ses propres fournitures (variables), son propre carnet de notes (historique des runs) et son propre cadenas (verrouillage). Deux collègues ne peuvent pas modifier le même dossier en même temps — le cadenas l’empêche. HCP Terraform fonctionne pareil : chaque workspace isole une unité d’infrastructure.

Un workspace dans HCP Terraform regroupe :

Composant	Rôle
Configuration	Le code Terraform (envoyé par CLI, VCS ou API)
State	L’état de l’infrastructure réelle, versionné et chiffré
Variables	Les valeurs d’entrée (Terraform + environnement)
Historique des runs	Chaque plan et apply avec logs et résultat
Réglages	Mode d’exécution, auto-apply, verrouillage, notifications

Glissez pour voir

Chaque workspace gère une seule unité d’infrastructure — typiquement un environnement (dev, staging, prod) ou un composant isolé (réseau, base de données, application).

Workspace CLI ≠ workspace HCP Terraform

Cette distinction est une source fréquente de confusion, y compris dans les examens de certification.

Critère	Workspace CLI (terraform workspace)	Workspace HCP Terraform
Ce que c’est	Un dossier de state nommé dans le même projet	Une unité de travail complète dans la plateforme
State	Plusieurs states dans le même backend	Un state unique par workspace
Variables	Partagées (même terraform.tfvars)	Propres à chaque workspace
Historique	Aucun	Complet (logs, approbations, durée)
Permissions	Aucune	Par équipe, par projet
Usage recommandé	Tests rapides en local	Tout le reste (équipe, CI/CD, production)

Glissez pour voir

Ne confondez pas les deux

La commande terraform workspace select change de state local. Le bloc cloud { workspaces { name = "..." } } pointe vers un workspace HCP Terraform. Ce sont deux notions différentes qui partagent malheureusement le même nom. Avec l’intégration HCP Terraform, la CLI peut toutefois sélectionner des workspaces HCP distants associés au répertoire courant.

Créer un workspace et lancer un run distant

Prérequis

• Un compte HCP Terraform avec une organisation créée → Découvrir HCP Terraform
• Terraform CLI ≥ 1.6 installé (le bloc cloud { workspaces { project } } nécessite 1.6+)
• terraform login exécuté avec succès

Préparer la configuration

1. Créez un répertoire de travail

   mkdir -p ~/terraform-workspace-hcp && cd ~/terraform-workspace-hcp

2. Créez le fichier main.tf

   Cette configuration minimale crée une ressource terraform_data — disponible via un provider intégré, sans dépendance externe — suffisante pour valider le fonctionnement de l’exécution distante sans infrastructure réelle :

   terraform {
     required_version = ">= 1.6.0"
   
     cloud {
       organization = "stephrobert-terraform-labs"
   
       workspaces {
         project = "associate-004"
         name    = "associate-004-01-init"
       }
     }
   }
   
   resource "terraform_data" "hello" {
     input = "Premier run HCP Terraform"
   }
   
   output "confirmation" {
     value = terraform_data.hello.output
   }

   Le bloc cloud {} indique à Terraform CLI d’envoyer la configuration à HCP Terraform pour exécution distante. Le workspace associate-004-01-init est créé automatiquement s’il n’existe pas encore.

3. Initialisez le projet

   terraform init

   Terraform CLI détecte le bloc cloud {}, se connecte à HCP Terraform et configure le workspace distant. La sortie attendue :

   Initializing HCP Terraform...
   
   Initializing provider plugins...
   
   HCP Terraform has been successfully initialized!

4. Lancez votre premier plan

   terraform plan

   La commande envoie votre code à HCP Terraform qui exécute le plan sur ses propres machines. Le résultat s’affiche dans votre terminal, mais le calcul s’est fait à distance :

   Running plan in HCP Terraform...
   
   Terraform v1.x.x
   ...
   Plan: 1 to add, 0 to change, 0 to destroy.
   
   Changes to Outputs:
     + confirmation = "Premier run HCP Terraform"

5. Appliquez les changements

   terraform apply

   En mode manual apply (défaut), HCP Terraform attend votre confirmation dans le terminal avant d’appliquer. Tapez yes pour confirmer.

   Do you want to perform these actions in workspace "associate-004-01-init"?
     Terraform will perform the actions described above.
     Only 'yes' will be accepted to approve.
   
     Enter a value: yes
   
   Apply complete! Resources: 1 added, 0 changed, 0 destroyed.
   
   Outputs:
   
   confirmation = "Premier run HCP Terraform"

6. Vérifiez dans l’interface web

   Rendez-vous sur app.terraform.io → votre organisation → project associate-004 → workspace associate-004-01-init.

   Vous y trouvez :

   • L’historique des runs avec le plan et l’apply que vous venez d’exécuter
   • Le state avec la terraform_data créée
   • Les variables (vides pour l’instant)

Le workspace se crée automatiquement

Avec le workflow CLI-driven, HCP Terraform peut créer automatiquement le project et le workspace au terraform init si le nom spécifié dans le bloc cloud {} n’existe pas encore. Vérifiez ensuite dans l’interface les réglages, les variables et la version Terraform du workspace avant de lancer vos premiers runs.

Les réglages essentiels d’un workspace

Une fois le workspace créé, vous pouvez ajuster ses réglages depuis l’interface web (Settings dans le workspace).

Mode d’exécution

Le mode d’exécution détermine où le plan et l’apply sont calculés :

Mode	Comportement	Cas d’usage
Project Default	Hérite du réglage défini au niveau du project	Réglage par défaut dans l’UI
Remote	Plan et apply exécutés sur les VM HCP Terraform	Usage standard, recommandé
Local	Plan et apply exécutés sur votre poste, state stocké à distance	Débogage, accès à des ressources locales
Agent	Plan et apply exécutés par un agent auto-hébergé	Infra privée non accessible depuis Internet

Glissez pour voir

Pour les labs d’apprentissage, le mode Remote est toujours le bon choix.

Le mode Local : state distant, mais pas de variables distantes

En mode Local, votre poste exécute le plan mais le state reste sur HCP Terraform. Terraform CLI télécharge le state en mémoire pour le calcul, puis renvoie le state mis à jour à la plateforme. Vous n’avez jamais de fichier terraform.tfstate local.

Attention : en mode Local, HCP Terraform n’évalue pas les workspace variables ni les variable sets. Seules les variables d’environnement de votre poste et vos fichiers .tfvars locaux sont utilisés.

Auto-apply vs manual apply

Réglage	Comportement
Manual apply (défaut)	Le plan est calculé, puis vous devez confirmer l’apply
Auto-apply	L’apply démarre automatiquement après un plan réussi

Glissez pour voir

Dans un run CLI-driven, terraform apply affiche une demande de confirmation dans le terminal. Pour auto-appliquer depuis la CLI, utilisez terraform apply -auto-approve. Le réglage Auto-apply du workspace concerne surtout les runs lancés via l’interface, l’API ou le VCS.

Pour l’apprentissage, gardez manual apply — cela vous oblige à relire le plan avant d’appliquer.

Verrouillage du workspace

HCP Terraform verrouille automatiquement le workspace pendant un run pour empêcher les modifications concurrentes. Ce verrouillage est transparent : si un collègue lance un terraform apply pendant que vous êtes en train d’en exécuter un, son run reste en Pending tant que le verrou n’est pas levé.

Un verrou bloque les applies et la plupart des plans, mais pas tous : les plan-only runs peuvent encore être autorisés, car ils n’affectent ni les ressources ni le state.

Vous pouvez aussi verrouiller manuellement un workspace depuis l’interface pour empêcher tout run — utile pendant une maintenance ou un incident.

Fichier .terraformignore

Quand Terraform CLI envoie votre configuration à HCP Terraform en mode CLI-driven, il transfère tous les fichiers du répertoire courant. Pour exclure les fichiers inutiles, créez un .terraformignore à la racine :

.git/
*.md
docs/
tests/

Ce fichier fonctionne comme un .gitignore — il réduit la taille du téléversement et accélère les runs.

Workspace CLI-driven et workspace VCS

Ce guide couvre un workspace CLI-driven. Si un workspace est lié à un dépôt VCS, la CLI ne peut plus lancer de remote apply : le dépôt devient la source de vérité et les applies passent par le flux VCS (push, merge).

Gérer le cycle de vie d’un workspace

Lister les workspaces

Depuis l’interface web, naviguez dans votre organisation pour voir tous les workspaces. Le filtre par project permet de retrouver rapidement un workspace.

Supprimer un workspace

Quand un lab est terminé, nettoyez :

1. Détruisez les ressources gérées

   terraform destroy

   Confirmez avec yes. Cette commande supprime les ressources dans l’infrastructure cible mais conserve le workspace.

2. Supprimez le workspace (optionnel)

   Dans l’interface web : Settings → Destruction and Deletion → Delete Workspace.

   Par défaut, un administrateur de workspace ne peut supprimer qu’un workspace déverrouillé qui ne gère plus d’infrastructure. Un organization owner peut toutefois forcer la suppression (force delete), ce qui coupe le lien avec le state sans détruire les ressources restantes. Le terraform destroy préalable reste la bonne pratique.

Migrer depuis un backend existant

Si vous avez une configuration existante avec un backend "s3" ou un backend "local" et que vous voulez migrer vers HCP Terraform :

1. Remplacez le bloc backend par un bloc cloud {} dans votre fichier de configuration.

2. Relancez l’initialisation avec migration :

   terraform init -migrate-state

   Terraform CLI vous propose de copier le state existant vers le nouveau workspace HCP Terraform. Confirmez pour transférer l’état.

Sauvegardez votre state avant migration

Avant de lancer terraform init -migrate-state, faites une copie de sauvegarde de votre state actuel. Si votre backend est S3, vérifiez que le versioning est activé. Si c’est un backend local, copiez le fichier terraform.tfstate.

Dépannage

Symptôme	Cause probable	Solution
Error: No credentials found for app.terraform.io	terraform login non exécuté ou token expiré	Relancez terraform login
Error: workspace not found	Organisation ou project mal orthographié dans le bloc cloud {}	Vérifiez les noms dans l’interface web
Le run reste en pending	Workspace verrouillé par un run précédent	Attendez la fin du run ou déverrouillez manuellement
Error: cloud and backend are mutually exclusive	Bloc backend et bloc cloud présents simultanément	Supprimez le bloc backend, gardez cloud {}
Le plan affiche des changements inattendus	Variables définies dans le workspace qui écrasent vos .tfvars locaux	Vérifiez les variables dans Settings → Variables
Le téléversement est lent	Trop de fichiers envoyés à HCP Terraform	Ajoutez un .terraformignore pour exclure les fichiers inutiles

Glissez pour voir

À retenir

• Un workspace HCP Terraform regroupe configuration, state, variables et historique des runs — c’est bien plus qu’un simple state nommé.
• Ne confondez pas terraform workspace (CLI, state local) et un workspace HCP Terraform (unité de travail complète sur la plateforme). La CLI peut toutefois interagir avec les workspaces HCP distants.
• Le bloc cloud {} dans votre configuration connecte Terraform CLI à un workspace distant. En exécution distante, un bloc backend {} explicite n’est plus nécessaire.
• Le workspace se crée automatiquement au premier terraform init en mode CLI-driven.
• Le mode d’exécution par défaut est Remote : le plan et l’apply sont calculés sur les VM d’HCP Terraform, pas sur votre poste.
• Manual apply est le défaut — gardez-le pour l’apprentissage.
• Utilisez .terraformignore pour accélérer les téléversements.

Prochaines étapes

Remote runs et modes d'exécution CLI-driven, VCS-driven, speculative plans et modes de planification.

Variables, secrets et variable sets Centralisez vos variables et partagez-les entre workspaces.

Projects, équipes et organisation Regroupez vos workspaces et gérez les permissions.

×

📖 Voir la documentation →