Remote runs et modes d'exécution dans HCP Terraform

Un run dans HCP Terraform englobe le cycle complet d’exécution : téléversement du code, plan, approbation éventuelle, puis apply. Ce guide détaille les trois façons de déclencher un run, les speculative plans et les modes de planification disponibles.

Ce que vous allez apprendre

• Ce qu’est un run et les étapes de son cycle de vie
• Les trois workflows d’exécution : CLI-driven, VCS-driven, API-driven
• Comment fonctionnent les speculative plans sur les pull requests
• Les modes de planification : normal, destroy, refresh-only
• Comment suivre et gérer vos runs dans l’interface web

Anatomie d’un run

Analogie : le run est une chaîne de montage

Dans une usine, un produit passe par plusieurs postes dans un ordre précis : réception des matières premières, assemblage, contrôle qualité, expédition. Un run HCP Terraform, c’est la même chose : réception du code → plan → contrôle (policy check) → approbation → apply. Si le contrôle qualité échoue, le produit ne part pas en expédition.

Chaque run passe par une séquence d’étapes. Voici le parcours minimal d’un run standard :

Étape	Ce qui se passe	Peut échouer ?
Pending	Le run est en file d’attente	Non
Plan	Terraform calcule les changements	Oui (erreur de config)
Policy check	Les politiques Sentinel/OPA sont évaluées	Oui (violation)
Apply	Les changements sont appliqués à l’infrastructure	Oui (erreur provider)
Applied	Le state est mis à jour, le run est terminé	Non

Glissez pour voir

Si une étape échoue, le run s’arrête — aucun changement n’est appliqué à l’infrastructure.

Étapes optionnelles selon la configuration

Selon la configuration du workspace, d’autres étapes peuvent s’ajouter : Fetching (téléchargement du code depuis un dépôt VCS), Cost Estimation (estimation du coût des changements), et les phases Pre-plan / Post-plan / Pre-apply / Post-apply si des run tasks sont configurées. Un speculative plan s’arrête toujours après la phase Plan — il ne passe jamais en Apply.

File d’attente

En règle générale, les runs standard sont sérialisés par workspace : HCP Terraform traite les runs dans l’ordre où ils sont mis en file d’attente. Cette sérialisation évite les conflits de state.

Exception importante : les speculative plans et les saved plans ignorent cette file d’attente pendant leur phase de planification. Ils peuvent donc démarrer même si un autre run est déjà en cours, car ils ne modifient ni les ressources ni le state.

Les trois workflows d’exécution

CLI-driven : le point de départ

C’est le workflow que vous avez utilisé dans le guide précédent. Vous tapez terraform plan ou terraform apply depuis votre terminal, mais l’exécution se produit sur les VM d’HCP Terraform.

Comment ça fonctionne :

1. Terraform CLI empaquète votre code et l’envoie à HCP Terraform
2. La plateforme exécute le plan à distance
3. Le résultat s’affiche dans votre terminal
4. Vous confirmez l’apply depuis votre terminal (mode manual apply)

# Le plan s'exécute à distance, le résultat s'affiche localement
terraform plan

# L'apply s'exécute à distance après votre confirmation
terraform apply

Quand l’utiliser : développement, itération rapide, apprentissage. C’est le workflow le plus intuitif car il ressemble à l’exécution locale classique.

VCS-driven : recommandé pour les environnements partagés

Le workflow VCS-driven connecte un dépôt Git (GitHub, GitLab, Bitbucket, Azure DevOps) à un workspace. Chaque push ou merge déclenche automatiquement un run.

Comment ça fonctionne :

1. Vous poussez du code sur la branche surveillée
2. HCP Terraform détecte le changement et démarre un plan
3. En mode manual apply, un membre de l’équipe valide dans l’interface web
4. L’apply s’exécute

Le speculative plan sur les pull requests : quand vous ouvrez une PR, HCP Terraform exécute un plan en lecture seule — le speculative plan. Ce plan :

• montre les changements prévus sans les appliquer,
• ne bloque pas la file d’attente du workspace,
• publie un check ou un lien vers le plan dans l’interface de la PR/MR.

Le speculative plan est votre filet de sécurité

Avant de merger une PR qui modifie l’infrastructure, le speculative plan vous montre exactement ce qui va changer. C’est l’équivalent d’un terraform plan automatique sur chaque PR — sans aucune action manuelle.

Quand l’utiliser : production, environnements partagés, review d’infrastructure via PR.

Configuration VCS

Pour connecter un dépôt, allez dans Settings → Version Control du workspace et suivez l’assistant de connexion. Le dépôt doit contenir votre configuration Terraform à la racine (ou dans un sous-répertoire configurable).

API-driven : l’automatisation

Le workflow API-driven utilise l’API REST d’HCP Terraform pour déclencher des runs par programmation.

Comment ça fonctionne :

1. Un script ou un pipeline CI/CD appelle l’API pour créer une configuration version (upload du code)
2. L’API démarre un run
3. Le script interroge l’API pour suivre le statut
4. Le script confirme l’apply via l’API

Quand l’utiliser : pipelines CI/CD personnalisés (GitHub Actions, GitLab CI), automatisation avancée, orchestration multi-workspace.

Comparaison des trois workflows

Critère	CLI-driven	VCS-driven	API-driven
Déclencheur	terraform plan/apply	Push / merge Git	Appel HTTP
Speculative plans	Oui (terraform plan)	Oui (PR automatique)	Oui (API)
Approbation	Dans le terminal	Dans l’interface web	Via API
Cas d’usage	Développement	Équipes, production	CI/CD
Complexité	Faible	Moyenne	Élevée
Disponible en gratuit	✅	✅	✅

Glissez pour voir

Modes et options de run

Quand vous déclenchez un run, vous pouvez choisir un mode de planification qui modifie le comportement du plan :

Mode	Commande CLI	Ce qu’il fait
Normal (défaut)	terraform plan	Compare la configuration au state et propose les changements
Destroy	terraform plan -destroy	Propose la suppression de toutes les ressources
Refresh-only	terraform plan -refresh-only	Met à jour le state sans modifier l’infrastructure

Glissez pour voir

Le mode normal

C’est le mode par défaut. Terraform compare votre code HCL au state et calcule un plan de création, modification ou suppression de ressources.

terraform plan
# Plan: 2 to add, 1 to change, 0 to destroy.

Le mode destroy

Ce mode propose la suppression de toutes les ressources gérées par le workspace. Utile pour nettoyer un lab ou un environnement temporaire.

terraform plan -destroy
# Plan: 0 to add, 0 to change, 3 to destroy.

Vous pouvez aussi déclencher un destroy depuis l’interface web : Settings → Destruction and Deletion → Queue destroy plan.

Le mode refresh-only

Ce mode synchronise le state avec l’état réel de l’infrastructure sans proposer de changements. Il détecte le drift — les modifications faites en dehors de Terraform (console cloud, script, intervention manuelle).

terraform plan -refresh-only
terraform apply -refresh-only

Dans l’interface web, cette action est exposée sous Actions → Start new run → Refresh state.

Si Terraform détecte un écart entre le state et la réalité, il vous propose de mettre à jour le state pour refléter l’état actuel.

Refresh-only ne corrige pas le drift

Le mode refresh-only met à jour le state pour refléter la réalité, mais il ne remet pas l’infrastructure en conformité avec votre code. Pour corriger un drift, lancez un terraform plan normal après le refresh : Terraform proposera alors de remettre l’infrastructure en conformité avec la configuration.

Suivre un run dans l’interface

L’interface web d’HCP Terraform affiche le détail de chaque run :

Zone	Ce qu’elle montre
Run list	Historique chronologique de tous les runs du workspace
Plan output	Le résultat du plan (ressources ajoutées, modifiées, supprimées)
Policy check	Résultat des vérifications Sentinel / OPA (si configurées)
Apply output	Les logs de l’apply (succès, erreurs, durée)
State versions	L’historique des versions du state (restauration possible par un admin)

Glissez pour voir

Chaque run affiche son statut en temps réel : Pending → Planning → Planned → Applying → Applied (ou Errored / Discarded / Canceled).

Annuler ou rejeter un run

• Discard : rejette un run en attente d’approbation (le plan a été calculé mais vous ne voulez pas appliquer)
• Cancel : annule un run en cours (le plan ou l’apply est interrompu)
• Force Cancel : annule un run bloqué qui ne répond plus

Saved plans (Terraform ≥ 1.6)

Depuis Terraform 1.6, vous pouvez créer un saved plan — un plan calculé et stocké que vous pouvez appliquer plus tard sans recalculer :

terraform plan -out=tfplan
terraform apply tfplan

En mode CLI-driven avec HCP Terraform, le saved plan est stocké sur la plateforme. L’apply reprend exactement le plan sauvegardé, sans recalcul. Cela garantit que ce que vous avez relu est exactement ce qui sera appliqué.

Limites des saved plans

Avec HCP Terraform, les saved plans via la CLI nécessitent Terraform 1.6+. Un saved plan distant ne peut être appliqué que dans le même workspace qui l’a généré. S’il devient obsolète après une modification du state (par un autre apply, par exemple), HCP Terraform le rejette automatiquement.

Dépannage

Symptôme	Cause probable	Solution
Le run reste en pending longtemps	Un run précédent est encore en cours	Attendez ou annulez le run bloquant
Error: Failed to request discovery document	Problème réseau vers app.terraform.io	Vérifiez votre connectivité et vos proxies
Le speculative plan ne s’affiche pas dans la PR	Connexion VCS mal configurée	Vérifiez Settings → Version Control
Error: Saved plan is stale	Le state a changé depuis le plan	Relancez un terraform plan pour obtenir un plan à jour
L’apply échoue mais le plan était bon	Changement concurrent dans l’infrastructure	Relancez le plan pour détecter le drift
Le run affiche Policy check: hard-mandatory failed	Le plan viole une politique de conformité	Corrigez la configuration pour respecter la politique

Glissez pour voir

À retenir

• Un run est le cycle complet : plan → policy check → apply. Les runs standard sont sérialisés par workspace ; les speculative plans et saved plans ignorent cette file d’attente.
• CLI-driven pour le développement, VCS-driven pour les environnements partagés, API-driven pour l’automatisation CI/CD. Les trois sont disponibles en édition gratuite.
• Les speculative plans sur les PR montrent les changements sans les appliquer — c’est votre filet de sécurité avant le merge.
• Trois modes de planification : normal (changements), destroy (suppression), refresh-only (synchronisation du state).
• Le mode refresh-only détecte le drift mais ne le corrige pas — il faut un plan normal ensuite.
• Les saved plans garantissent que l’apply correspond exactement au plan que vous avez relu.

Prochaines étapes

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.

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

×

📖 Voir la documentation →