Variables, secrets et variable sets dans HCP Terraform

Quand vous travaillez en équipe, gérer des variables dans des fichiers .tfvars locaux devient vite ingérable : chaque poste a sa propre version, les secrets traînent sur les disques, et rien n’est partageable. HCP Terraform centralise les variables et les secrets dans la plateforme, avec masquage, partage et permissions, et permet de distribuer des valeurs communes entre workspaces via les variable sets.

Ce que vous allez apprendre

• Les deux types de variables dans HCP Terraform : Terraform et environnement
• Comment créer et gérer des variables dans un workspace
• Comment marquer une variable comme sensible (masquée)
• Comment créer un variable set et le partager entre workspaces
• L’ordre de précédence des variables (qui gagne quand il y a conflit)

Deux types de variables

Analogie : les variables de cuisine

Les variables Terraform, ce sont les ingrédients de votre recette — le nom du serveur, la taille mémoire, la région. Les variables d’environnement, ce sont les réglages du four — la température, le mode de cuisson. Les deux sont nécessaires, mais ils agissent à des niveaux différents.

HCP Terraform distingue deux catégories de variables :

Type	Ce qu’il configure	Équivalent local
Terraform variable	Les valeurs de vos variable {} HCL	terraform.tfvars ou -var
Environment variable	L’environnement d’exécution (credentials, proxy, debug)	export TF_VAR_... ou export AWS_...

Glissez pour voir

Variables Terraform

Ces variables alimentent les blocs variable {} de votre configuration. Par exemple, si votre code déclare :

variable "instance_type" {
  type    = string
  default = "t3.micro"
}

Vous pouvez définir la valeur t3.small dans le workspace HCP Terraform sans toucher au code. La variable du workspace écrase la valeur default.

Variables d’environnement

Ces variables configurent l’environnement dans lequel Terraform s’exécute. Les plus courantes :

Variable	Usage
AWS_ACCESS_KEY_ID	Credentials AWS
AWS_SECRET_ACCESS_KEY	Credentials AWS (sensible)
AWS_DEFAULT_REGION	Région AWS par défaut
TF_LOG	Niveau de log Terraform (DEBUG, TRACE…)
GOOGLE_CREDENTIALS	Credentials GCP (sensible)

Glissez pour voir

Préférez les dynamic credentials

Plutôt que de stocker des clés cloud (AWS, GCP, Azure) en variables d’environnement, utilisez les dynamic provider credentials qui génèrent des tokens temporaires via OIDC. Voir le guide Credentials et partage.

Créer des variables dans un workspace

1. Ouvrez les réglages du workspace

   Dans l’interface web : Workspace → Variables.

2. Ajoutez une variable Terraform

   Cliquez + Add variable → choisissez Terraform variable :

   Champ	Exemple
   Key	instance_type
   Value	t3.small
   Category	Terraform variable
   Sensitive	Non
   HCL	Non (sauf si la valeur est une liste ou une map)

   Glissez pour voir

3. Ajoutez une variable sensible

   Pour un secret (clé API, mot de passe), cochez Sensitive. Une fois enregistrée, la variable devient write-only : sa valeur n’est plus affichée dans l’interface ni lisible via l’API.

   Champ	Exemple
   Key	db_password
   Value	s3cure-P@ssw0rd!
   Sensitive	✅ Oui

   Glissez pour voir

   Cela réduit fortement l’exposition, mais ne garantit pas à lui seul qu’une valeur ne finira jamais dans les logs ou le state si la configuration l’utilise dans un output non masqué ou dans un argument de ressource visible.

4. Vérifiez lors du prochain run

   Lancez un terraform plan — les variables du workspace sont injectées automatiquement dans l’exécution distante.

HCL checkbox

Quand une variable Terraform a une valeur complexe (liste, map, object), cochez la case HCL pour que la valeur soit interprétée comme du HCL et non comme une chaîne de caractères. Exemple : ["a", "b", "c"] avec la case HCL cochée sera interprété comme une liste.

Variable sets : partager entre workspaces

Un variable set est un ensemble de variables que vous pouvez attacher à un ou plusieurs workspaces — ou même à toute votre organisation.

Analogie : le trousseau de clés partagé

Au lieu de donner une copie de chaque clé à chaque collègue (dupliquer les variables dans chaque workspace), vous déposez un trousseau dans un coffre commun (le variable set). Quiconque a accès au coffre utilise les mêmes clés.

Cas d’usage typiques

Variable set	Contenu	Scope
aws-credentials-dev	AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY	Tous les workspaces dev
common-tags	project_name, environment, team	Organisation entière
network-config	vpc_id, subnet_ids	Workspaces d’un même project

Glissez pour voir

Créer un variable set

1. Naviguez dans les réglages de l’organisation

   Organization → Settings → Variable sets → Create variable set.

2. Configurez le scope

   Le scope disponible dépend du propriétaire du variable set :

   Propriétaire	Options de scope
   Organization	Tous les workspaces, des projects spécifiques, ou des workspaces spécifiques
   Project	Le project entier, ou des workspaces spécifiques dans ce project

   Glissez pour voir

3. Ajoutez les variables

   Les variables d’un set se configurent exactement comme celles d’un workspace (Terraform ou environnement, sensible ou non, HCL ou non).

4. Enregistrez

   Les variables du set sont immédiatement disponibles dans les workspaces ciblés — aucun redémarrage de run nécessaire.

Attacher et détacher un variable set

Depuis la page du variable set, vous pouvez ajouter ou retirer des workspaces et des projects à tout moment. Les changements prennent effet au prochain run.

Ordre de précédence des variables

Quand la même variable est définie à plusieurs endroits, HCP Terraform applique un ordre de priorité strict. Voici l’ordre complet, du plus prioritaire au moins prioritaire :

Priorité	Source
1 (haute)	Variable set priority owned by organization
2	Variable set priority owned by project
3	Arguments CLI : -var et -var-file
4	Variables locales TF_VAR_* (transmises en CLI-driven)
5	Variable du workspace
6	Variable set normal owned by project
7	Variable set normal owned by organization
8	Fichiers *.auto.tfvars et terraform.tfvars
9 (basse)	default dans le bloc variable {} HCL

Glissez pour voir

Conflits entre variable sets de même portée

Quand deux variable sets de même portée et même priorité définissent la même variable, HCP Terraform tranche par ordre lexical du nom du variable set (A avant Z). Pour éviter les conflits, ne définissez une variable donnée que dans un seul set par niveau de scope.

Exemple concret

Imaginons une variable environment définie à trois endroits :

Source	Valeur	Priorité
Variable set org (normal)	"default"	7
Variable set project associate-004 (normal)	"staging"	6
Variable du workspace associate-004-01-init	"production"	5

Glissez pour voir

Résultat : la valeur utilisée est "production" (priorité 5 > 6 > 7).

Règle simple à retenir

Les priority sets écrasent tout. Ensuite la CLI (-var) l’emporte sur le workspace, qui l’emporte sur les sets normaux. À chaque niveau, un set owned by project est plus spécifique qu’un set owned by organization.

Tous les fichiers .tfvars ne se comportent pas pareil

En exécution distante, HCP Terraform charge les fichiers terraform.tfvars et *.auto.tfvars présents dans la configuration envoyée. En revanche, les autres fichiers .tfvars ne sont pas chargés automatiquement : utilisez -var-file si vous voulez les appliquer à un run précis.

Les variables définies dans le workspace, dans les variable sets, ou fournies à la ligne de commande gardent la priorité sur les valeurs issues de ces fichiers.

Credentials provider en remote run

Dans un run CLI-driven remote, les variables d’environnement de votre shell local préfixées TF_VAR_ sont transmises comme variables d’entrée. En revanche, les variables nécessaires au provider (comme AWS_ACCESS_KEY_ID) ne sont pas reprises depuis votre shell. Elles doivent être définies dans le workspace ou via un variable set.

Local execution mode : pas de variables distantes

Pour les workspaces configurés en Local execution mode, HCP Terraform n’évalue pas les workspace variables ni les variable sets. L’exécution utilise uniquement les variables de votre poste local (.tfvars, variables d’environnement). Seul le state est stocké à distance.

Bonnes pratiques

Organisation des variables

Bonne pratique	Pourquoi
Un variable set par préoccupation	Séparer credentials, tags, config réseau
Scope le plus petit possible	Ne pas appliquer des credentials dev à la prod
Marquer sensible toute credential	Masquage irréversible dans l’interface et les logs
Utiliser les sets priority avec parcimonie	Réservés aux contraintes d’organisation (tags obligatoires, région imposée)
Documenter les variable sets	Ajouter une description claire lors de la création

Glissez pour voir

Gestion des secrets

À faire	À éviter
Marquer Sensitive les credentials	Laisser des clés en clair dans l’interface
Utiliser les dynamic credentials	Stocker des clés cloud longue durée
Rotater les secrets régulièrement	Un seul jeu de credentials pour tous les environnements
Séparer les credentials par environnement	Un variable set aws-creds unique pour dev + prod

Glissez pour voir

Dépannage

Symptôme	Cause probable	Solution
Error: No value for required variable	Variable non définie dans le workspace ni dans un variable set	Ajoutez la variable dans le workspace ou un set
La variable du workspace est ignorée	Un variable set priority écrase la valeur	Vérifiez les sets marqués priority
Le .tfvars local ne fonctionne pas	Fichier non nommé terraform.tfvars ou *.auto.tfvars	Renommez le fichier ou utilisez -var-file
Error: Variables may not be used here	Confusion entre variable Terraform et variable d’environnement	Vérifiez la catégorie (Terraform vs Environment)
La valeur complexe est mal interprétée	La case HCL n’est pas cochée	Cochez HCL pour les listes, maps et objects
Un secret apparaît dans les logs	Variable non marquée Sensitive	Recréez la variable avec Sensitive coché (irréversible)

Glissez pour voir

À retenir

• HCP Terraform gère deux types de variables : Terraform (vos variable {}) et environnement (credentials, config d’exécution).
• Les variables marquées Sensitive deviennent write-only (non lisibles dans l’UI ni via l’API), mais une valeur peut encore apparaître dans les logs ou le state si la configuration l’expose.
• Les variable sets permettent de partager des variables entre workspaces sans duplication — scopez-les par workspace, project ou organisation.
• L’ordre de précédence : priority sets > CLI (-var) > workspace > sets normaux > .auto.tfvars / terraform.tfvars > default HCL.
• En remote, terraform.tfvars et *.auto.tfvars sont chargés, mais les autres fichiers .tfvars nécessitent -var-file.
• Préférez les dynamic credentials aux clés cloud statiques.

Prochaines étapes

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

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.

×

📖 Voir la documentation →