Projects, équipes et organisation dans HCP Terraform

À mesure que votre nombre de workspaces grandit, retrouver celui dont vous avez besoin devient un défi. Les projects regroupent vos workspaces par contexte (équipe, produit, environnement), et les teams contrôlent qui peut faire quoi. Ce guide explique comment organiser HCP Terraform à l’échelle.

Ce que vous allez apprendre

À quoi servent les projects et comment ils structurent l’organisation
Comment créer un project et y affecter des workspaces
Le système de permissions : organisation, project, workspace
Les différents rôles d’équipe (owners, manage, read, write, admin)
Les limites du free tier sur les permissions avancées

Qu’est-ce qu’un project

Un project est un conteneur logique qui regroupe des workspaces liés :

Concept	Rôle	Exemple
Organization	Conteneur racine — regroupe tout	`stephrobert-terraform-labs`
Project	Regroupe des workspaces par contexte	`associate-004`, `professional`, `sandbox`
Workspace	Unité de travail (config + state + variables)	`associate-004-01-init`

Le Default Project

Quand vous créez un workspace sans spécifier de project, il atterrit dans le Default Project. Ce project existe automatiquement dans toute organisation et ne peut pas être supprimé.

Pour les labs, vous avez déjà créé trois projects dans le guide de présentation :

Project	Usage
`associate-004`	Labs liés à la certification Associate
`professional`	Labs liés à la certification Professional
`sandbox`	Expérimentations libres

Créer et gérer des projects

Créez un project

Dans l’interface web : Organization → Projects → New Project.

Donnez un nom explicite et une description. Les noms acceptent lettres, chiffres, tirets, underscores et espaces internes.
Déplacez des workspaces existants

Depuis la page d’un workspace : Settings → General → Project. Sélectionnez le project cible et enregistrez. Le workspace conserve son state, ses variables et son historique.

Pour déplacer un workspace, vous devez disposer de la permission d’organisation Manage all Projects, ou être admin à la fois sur le project source et sur le project de destination.

Créez un workspace directement dans un project

Avec le bloc cloud {}, le workspace est automatiquement créé dans le project spécifié :

terraform {
  cloud {
    organization = "stephrobert-terraform-labs"

    workspaces {
      project = "sandbox"
      name    = "sandbox-test-network"
    }
  }
}

Supprimez un project

Un project ne peut être supprimé que s’il ne contient plus de workspaces ni de Stacks. Déplacez ou supprimez-les d’abord. Le Default Project peut être renommé mais pas supprimé.

Le système de permissions

HCP Terraform applique les permissions à trois niveaux, du plus large au plus fin :

Niveau	Ce qu’il contrôle	Qui le configure
Organization	Membres, tokens API, registry, policy sets	Organization owners
Project	Accès aux workspaces du project	Organization owners + project admins
Workspace	Opérations sur un workspace précis	Admins du project ou du workspace

Les rôles d’équipe

Une team est un groupe d’utilisateurs qui partagent les mêmes droits. Les rôles prédéfinis diffèrent selon le niveau :

Rôles au niveau project :

Rôle	Ce qu’il permet
Project admin	Gérer les workspaces, les équipes et les réglages du project
Project maintain	Administration des workspaces du project, sans gérer le project lui-même
Project write	Créer des runs, modifier les variables des workspaces du project
Project read	Lecture seule : voir les runs, states, variables (masquées)

Rôles au niveau workspace :

Rôle	Ce qu’il permet
Workspace admin	Administration d’un workspace spécifique
Workspace write	Lancer des runs et modifier les variables
Workspace plan	Lancer des plans (sans apply)
Workspace read	Lecture seule sur un workspace

Comment se combinent les permissions

Les permissions sont additives. HCP Terraform accorde toujours à un utilisateur le niveau d’accès le plus élevé qu’il reçoit, quel que soit le scope où ce droit a été défini.

En pratique :

Un Organization owner est admin de tous les projects et workspaces.
Un rôle project s’applique à tous les workspaces du project.
Un rôle workspace affine l’accès à un workspace particulier.
Un droit plus permissif accordé à un autre niveau l’emporte toujours.
Les permissions ne remontent jamais : un rôle workspace ne donne pas de droits sur le project.

Organiser à l’échelle

Conventions de nommage

Adoptez une convention lisible dès le départ :

Pattern	Exemple	Quand l’utiliser
`<produit>-<env>`	`frontend-prod`	Petite organisation, peu de produits
`<équipe>-<produit>-<env>`	`platform-networking-staging`	Organisation moyenne
`<business-unit>-<produit>-<env>`	`finance-trading-prod`	Grande organisation

Stratégies de découpage en projects

Stratégie	Avantage	Inconvénient
Par produit	Vision claire par livrable	Multiplie les projects
Par équipe	Permissions naturelles	Un produit peut impliquer plusieurs équipes
Par environnement	Isolation stricte dev/prod	Disperse les workspaces d’un même produit
Hybride produit + env	Le plus courant et le plus lisible	Plus de projects à gérer

Pour les labs d’apprentissage, le découpage par contexte (certification, sandbox) est suffisant. En entreprise, le découpage hybride produit + environnement est le plus fréquent.

Variable sets et projects

Les variable sets peuvent être scopés par project — ce qui signifie que toutes les variables d’un set sont disponibles dans tous les workspaces du project :

Variable set	Scope	Contenu
`common-tags`	Organization (global)	Tags obligatoires : `team`, `cost-center`
`aws-dev-credentials`	Project `frontend-dev`	Credentials AWS pour l’environnement dev
`network-config-prod`	Project `networking-prod`	VPC ID, subnets, security groups

Cette approche évite de dupliquer les mêmes variables dans chaque workspace.

Tokens API et automatisation

Pour les pipelines CI/CD et l’automatisation, HCP Terraform propose des tokens à différents niveaux :

Type de token	Portée	Usage recommandé
User token	Permissions de l’utilisateur	Développement, CLI, automatisations personnelles
Team token	Permissions des workspaces accessibles à la team	Pipeline CI/CD d’une équipe
Organization token	Ressources et réglages d’organisation	Bootstrap, administration

Important : un organization token ne peut pas démarrer de run ni créer de configuration version. Pour cela, utilisez un user token ou un team token.

Dépannage

Symptôme	Cause probable	Solution
`Error: Unauthorized` lors d’un run	L’utilisateur n’a pas les permissions write sur le workspace	Vérifiez le rôle de la team
Impossible de déplacer un workspace	Permissions insuffisantes sur le project cible	Demandez les droits au project admin
Le Default Project contient trop de workspaces	Workspaces créés sans spécifier de project	Déplacez-les vers des projects dédiés
Les permissions project ne fonctionnent pas	Édition gratuite	Les permissions granulaires nécessitent Essentials+
Un membre voit tous les workspaces	En free tier, tous les membres sont owners	Normal en free tier — upgrade pour restreindre

À retenir

Les projects structurent vos workspaces par contexte (produit, équipe, environnement). Sans eux, tout finit dans le Default Project.
Les permissions sont additives : HCP Terraform accorde le niveau le plus élevé reçu, quel que soit le scope.
En édition gratuite, l’organisation fonctionne avec la team owners uniquement (5 membres max). Les permissions granulaires par project nécessitent Essentials+.
Les rôles project (Read, Write, Maintain, Admin) et workspace (Read, Plan, Write, Admin) sont distincts.
Adoptez une convention de nommage dès le départ — elle devient difficile à changer ensuite.
Les variable sets scopés par project évitent la duplication de variables entre workspaces du même contexte.
Utilisez des team tokens (pas des user tokens) pour les pipelines CI/CD.

Prochaines étapes

Dynamic credentials, tfe_outputs et run triggers Credentials temporaires, partage d'état et chaînage de runs.

Policy as Code et governance Sentinel, OPA, policy sets et niveaux d'application.

Variables, secrets et variable sets Centraliser les variables et les partager entre workspaces.