HCTA-004 — HashiCorp Cloud Platform (HCP Terraform)

HCTA-004 – HashiCorp Certified Terraform Associate

Historique du document

Document de référence

Sommaire

• A. Introduction
• B. Organisations
• C. Projets
• D. Workspaces
  • D.I. CLI-Driven, VCS-Driven (GitOps), API-Driven
  • D.II. Variables et Secrets
  • D.III. Variable Sets
  • D.IV. Run Triggers
• E. Version Control Systems (VCS)
• F. Sentinel Policy & OPA
• G. Variables, Secrets & Policy
• H. Bloc cloud {} & terraform login
• I. Explorer & Change Requests
• J. Bonnes pratiques

A. Introduction

HCP Terraform (anciennement Terraform Cloud) est la plateforme SaaS de HashiCorp permettant de centraliser l'exécution de Terraform, de gérer les workspaces, stocker le state à distance, implémenter des règles de gouvernance et permettre la collaboration entre équipes.

Principales fonctionnalités :

• State remote centralisé et versionné avec verrouillage automatique (locking)
• Interface graphique et API pour gérer l'infrastructure
• Déclenchement de plans Terraform à partir d'un push Git
• Gestion des rôles utilisateurs (RBAC)
• Support des variables sensibles, des secrets Vault et des policies Sentinel ou OPA
• Terraform Run Tasks pour intégration de workflows personnalisés (ex : sécurité, validation externe, SAST)

B. Organisations

Une organisation dans HCP Terraform est l'unité de plus haut niveau. Elle représente une entité logique comme une entreprise, un département ou un client. Toutes les ressources que vous gérez via HCP — workspaces, projets, modules, utilisateurs, politiques, intégrations — sont toujours rattachées à une organisation.

Rôle principal de l'organisation :

• Définir les limites de gouvernance, de sécurité et de gestion centralisée.
• Héberger un ou plusieurs projets, qui eux-mêmes regroupent des workspaces (environnements).
• Fournir un point d'entrée unique pour les équipes, avec gestion des accès et des configurations globales.

Structure hiérarchique :

Organisation (ex: HAMIDCOMPANY)
├── Projets
│   ├── Projet: infra-core
│   │   ├── Workspace: dev-vpc
│   │   └── Workspace: prd-vpc
│   └── Projet: app-stack
│       ├── Workspace: dev-api
│       └── Workspace: prd-api
├── Équipes (Teams)
│   ├── Equipe: Admins
│   ├── Equipe: DevOps
│   └── Equipe: Développeurs
├── Module Registry (privé)
└── Policies Sentinel

Création de l'organisation (exemple) :

• Nom de l'organisation : HAMIDCOMPANY
• Description : "Infrastructure pour tous les projets internes"
• Utilisateurs ajoutés : [email protected] (Owner), [email protected] (Member)
• Une fois créée, l'organisation est visible sur https://app.terraform.io/app/hamidcompany

Gestion des utilisateurs et équipes (RBAC)

Chaque organisation peut définir des équipes (teams) et leur associer des rôles (voici des exemples) :

Le RBAC est granulaire : tu peux gérer les droits par projet, workspace ou type d'action (plan, apply, read-only, etc.).

Registry de modules privés

Les modules doivent être publiés à partir d'un repo VCS (GitHub, GitLab, etc.), avec un tag v1.2.0 valide.

• Chaque organisation dispose de son propre registre privé de modules pour :
  • Centraliser les bonnes pratiques Terraform (naming, tagging, sécurité…)
  • Partager des modules internes avec contrôle de version

Cas d'usages concrets

Administration via API / CLI

L'organisation peut aussi être administrée via :

• API REST HCP : créer projets, gérer équipes, déclencher runs (déclaration en code)
• Terraform CLI (backend remote) : pour assigner un workspace à l'org

terraform {
  backend "remote" {
    organization = "hamidcompany"

    workspaces {
      name = "prd-db"
    }
  }
}

Sécurité et bonnes pratiques

• Activer l'authentification SSO (SAML) si votre plan HCP le permet
• Éviter d'accorder les droits "owner" sauf à quelques comptes stratégiques
• Toujours utiliser 2FA (authentification à deux facteurs)
• Nommer les organisations, projets et workspaces selon une convention claire :
  • org : hamidcompany
  • projet : network-infra
  • workspace : prd-vpc-euw1

C. Projets

Dans HCP Terraform, un projet est une couche organisationnelle intermédiaire entre l'organisation et les workspaces. Il permet de structurer, isoler, sécuriser et filtrer les environnements de travail.

Pourquoi utiliser des projets ?

Sans projets, tous tes workspaces sont au même niveau dans l'organisation, ce qui devient chaotique à partir d'une dizaine d'environnements. Les projets offrent :

• Organisation logique par domaine fonctionnel ou applicatif
• Regroupement clair des workspaces par application ou environnement
• Filtrage facile dans l'interface graphique
• Contrôle d'accès granulaire (RBAC par projet)
• Séparation d'audit et de logs

Structure typique :

Organisation : hamidcompany
├── Projet : ecommerce-app
│   ├── Workspace : dev-network
│   ├── Workspace : dev-app
│   └── Workspace : dev-db
├── Projet : internal-tools
│   ├── Workspace : staging-auth
│   └── Workspace : staging-logging
└── Projet : security
    ├── Workspace : vault-setup
    └── Workspace : IAM-policies

Tu peux créer un projet :

• Via l'interface HCP (onglet "Projects" > "Create Project")
• Ou via API REST (utile pour automatiser), un exemple ci-dessous :

curl \
  --header "Authorization: Bearer $TOKEN" \
  --request POST \
  --data '{
    "data": {
      "type": "projects",
      "attributes": {
        "name": "internal-tools",
        "description": "Outils internes pour monitoring & auth"
      }
    }
  }' \
  https://app.terraform.io/api/v2/organizations/hamidcompany/projects

Gestion des droits (RBAC par projet)

Chaque projet peut avoir ses propres permissions d'équipe. Cela permet de cloisonner les responsabilités :

Utilise les projets pour empêcher les erreurs humaines. Un développeur n'a pas besoin de droits apply sur le projet security.

Déplacement d'un workspace dans un projet

Un workspace peut être déplacé d'un projet à un autre (via l'UI ou API), sans casser le lien au state.

Il est préférable d'effectuer ce changement en dehors des périodes critiques car il peut impacter les automatisations (CI/CD, webhooks).

Bonnes pratiques sur les projets

• Créer un projet par domaine fonctionnel ou équipe produit (ex : billing, user-auth, analytics)
• Préfixer les workspaces dans un projet de manière cohérente : billing-dev, billing-prd, billing-uat
• Utiliser la description de projet pour documenter l'objectif (c'est visible dans l'UI)
• Associer des policies Sentinel à un projet si certaines règles doivent s'appliquer globalement
• Configurer des notifications ciblées (Slack, email) par projet

Projets + autres fonctionnalités HCP

D. Workspaces

Un workspace dans HCP Terraform est une unité d'exécution isolée. Il correspond à un environnement complet de déploiement Terraform avec ses propres :

• Fichiers terraform.tfstate
• Variables et secrets
• Historique des exécutions (plan/apply)
• Journaux de logs
• Liens éventuels à un repo Git

C'est l'endroit où ton code Terraform est exécuté.

À quoi sert un workspace ?

• Assurer l'indépendance entre les environnements (dev, staging, prod)
• Conserver un state unique par composant (VPC, DB, ECS, etc.)
• Centraliser les logs, plans, runs et historiques
• Permettre la collaboration sans conflits grâce au locking
• Activer des notifications ciblées par composant

Structure typique :

Organisation : hamidcompany
└── Projet : ecommerce-app
    ├── Workspace : dev-network
    ├── Workspace : dev-db
    ├── Workspace : prd-network
    └── Workspace : prd-db

Bonnes pratiques sur les workspaces

• 1 workspace = 1 composant = 1 environnement
• Préfixe cohérent : app-dev, db-prod, vpc-staging
• Pas de multi-environnement dans un seul workspace (évite env = variable de switch)
• Éviter d'avoir des centaines de ressources dans un même workspace (favoriser la modularité)
• Toujours vérifier les logs et les diff du plan avant d'apply
• Documenter chaque workspace (objectif, contact responsable, branche liée)

Erreurs courantes à éviter

• Ne pas réutiliser un workspace en changeant le code pour un autre composant
• Ne pas supprimer un workspace sans télécharger d'abord le tfstate
• Ne jamais partager une variable sensible en clair dans un plan
• Ne pas oublier de verrouiller l'accès (RBAC) par équipe si plusieurs projets

D.I. CLI-Driven, VCS-Driven (GitOps), API-Driven

Modes de gestion d'un workspace :

1. CLI-driven (mode local)

• Tu utilises ton terminal local (terraform apply) avec HCP comme backend distant
• Idéal pour tester manuellement
• Nécessite un terraform login + bloc cloud {} (moderne) ou backend "remote" (legacy) dans le .tf — voir section H

2. VCS-driven (mode GitOps)

• HCP est lié directement à un dépôt Git
• À chaque push ou PR, un plan est automatiquement déclenché
• Idéal pour production + pipelines avec contrôle qualité

3. API-driven

• Tu déclenches les runs via l'API REST HCP
• Utile pour des pipelines CI/CD personnalisés (GitLab CI, GitHub Actions, etc.)
• Tu peux uploader un plan, vérifier sa validité, puis l'appliquer

Exemple de configuration d'un workspace :

D.II. Variables et Secrets

Un workspace peut contenir :

• Terraform Variables (TF_VAR_) → visibles dans le plan
• Environment Variables → utiles pour les credentials
• Sensitive Variables → masquées dans l'interface (mais visibles dans le tfstate)

Bonnes pratiques :

• Toujours marquer les secrets comme sensitive
• Préférer l'utilisation de Vault HCP ou des variables d'environnement

On a aussi un historique d'exécution : qui, quoi, où, etc. Avec intégrations d'alertes : Slack, webhooks, email, run tasks (scan sécu avant apply).

D.III. Variable Sets

Les Variable Sets permettent de définir des variables (et secrets) une seule fois et de les appliquer à plusieurs workspaces ou projets. Fini les copier-coller de credentials AWS dans 30 workspaces.

Portée d'un Variable Set :

Cas d'usage typiques :

• Credentials cloud partagés : AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY une seule fois, propagés.
• Variables d'organisation : TF_VAR_org_name = "hamidcompany" global.
• Variables d'environnement par projet : TF_VAR_env = "prd" sur tous les workspaces du projet prod.

💡 Une variable définie au niveau workspace écrase celle d'un Variable Set (workspace > project > global).

D.IV. Run Triggers

Un Run Trigger permet de déclencher automatiquement un plan sur un workspace B quand un apply réussit sur un workspace A. Utile pour chaîner des déploiements interdépendants.

Exemple typique :

workspace: network-prd    →  apply réussit
        ↓ (Run Trigger)
workspace: compute-prd    →  plan déclenché automatiquement
        ↓ (Run Trigger)
workspace: app-prd        →  plan déclenché automatiquement

Configuration :

• Dans le workspace B (cible), section Settings > Run Triggers → ajouter le workspace A (source).
• Un workspace peut avoir jusqu'à 20 sources de Run Triggers.
• Le trigger ne fait que lancer un plan — l'apply reste sous le contrôle normal du workspace (auto-apply ou manual approval).

Pièges :

• Cycles interdits (A → B → A est bloqué).
• Si les workspaces source/cible n'utilisent pas de Run Triggers correctement, on peut avoir des plans "vides" inutiles (B ne dépend pas vraiment de A).

E. Version Control Systems (VCS)

Dans HCP Terraform, un workspace peut être lié directement à un dépôt Git (GitHub, GitLab, Bitbucket, Azure DevOps) pour déclencher des exécutions automatiquement lorsqu'un changement est détecté dans le code. Ce mode de fonctionnement s'appelle VCS-driven execution et permet de mettre en place un workflow GitOps sécurisé et auditable.

Plateformes supportées nativement :

• GitHub (public et GitHub Enterprise)
• GitLab (cloud et self-managed)
• Bitbucket Cloud (pas Bitbucket Server)
• Azure DevOps Services
• Autres via l'API (ex : Gitea, CodeCommit en mode API-driven)

Fonctionnement d'un workspace VCS-driven :

1. Tu connectes un repo Git à ton workspace
2. Tu choisis une branche à surveiller (ex : main, develop)
3. À chaque push, HCP Terraform :
   • Exécute un terraform plan automatiquement
   • Affiche le diff dans l'interface
   • Applique le plan (si auto-apply activé) ou attend une validation manuelle

Auto-Apply ou Manual-Approval ?

Bonnes pratiques : activer l'auto-apply uniquement sur des branches protégées (avec PR obligatoire + code review).

Pièges fréquents à éviter

• Lier le workspace à une branche instable ou utilisée pour des tests
• Utiliser auto-apply sur main sans code review obligatoire
• Oublier d'activer la protection de branche (dans GitHub par ex.)
• Modifier le code Terraform sans déclenchement Git (bypass de l'historique)

Bonnes pratiques VCS + Terraform

• 1 branche = 1 environnement stable (dev, staging, prod)
• Toujours activer la review de PR avant merge (avec tests)
• Limiter l'usage de main aux apply automatiques contrôlés
• Utiliser un tag Git pour geler une version d'un module interne
• Diviser les répertoires par composant/env dans un mono-repo (si besoin)
• Déclencher manuellement les apply si la situation est sensible (prod)

F. Sentinel Policy & OPA

HCP Terraform supporte deux frameworks de policy-as-code pour appliquer de la gouvernance avant un apply :

1. Sentinel — le framework propriétaire HashiCorp, intégré nativement. Il permet de définir des règles qui bloquent ou autorisent un plan avant son apply.

2. Open Policy Agent (OPA) — le standard open source CNCF, supporté depuis HCP Terraform. Permet d'utiliser le langage Rego pour écrire les politiques.

Niveaux d'enforcement (identiques pour Sentinel et OPA) :

Quand préférer OPA à Sentinel ?

• Tu as déjà OPA en place ailleurs (Kubernetes via Gatekeeper, API Gateway, etc.) → cohérence.
• Tu veux du standard ouvert / éviter le lock-in HashiCorp.
• Tu veux mutualiser des policies entre Terraform et d'autres outils.

Quand Sentinel suffit / est mieux ?

• 100% HashiCorp stack (Terraform + Vault + Consul) → Sentinel s'intègre nativement aux trois.
• Tu veux des fonctions avancées spécifiques au tfplan (objets tfplan, tfconfig, tfstate exposés nativement).

G. Variables, Secrets & Policy

Variables

• Définies dans l'UI ou via API
• Types : terraform variables, environnement (TF_VAR_), sensitive

Secrets

• Variables marquées comme sensitive = chiffrées
• Intégration avec Vault possible

Sentinel

• Policy-as-code pour bloquer certains plans

Exemple de policy Sentinel :

import "tfplan"

main = rule {
  all tfplan.resource_changes as rc {
    rc.type != "aws_db_instance" or rc.change.actions not contains "create"
  }
}

H. Bloc cloud {} & terraform login

Bloc cloud {} (moderne) vs backend "remote" (legacy)

Depuis Terraform 1.1+, HashiCorp recommande d'utiliser le bloc cloud {} plutôt que backend "remote" pour connecter une configuration à HCP Terraform. Les deux fonctionnent encore, mais cloud {} est plus simple et permet quelques fonctionnalités modernes (sélection de workspace par tags notamment).

# ✅ Moderne — recommandé
terraform {
  cloud {
    organization = "hamidcompany"

    workspaces {
      name = "prd-vpc"
      # ou via tags pour matcher plusieurs workspaces :
      # tags = ["prd", "network"]
    }
  }
}

# ⚠️ Legacy — fonctionne encore mais déconseillé pour les nouvelles configs
terraform {
  backend "remote" {
    organization = "hamidcompany"

    workspaces {
      name = "prd-vpc"
    }
  }
}

terraform login

Avant d'utiliser HCP Terraform en mode CLI-driven, il faut s'authentifier. La commande terraform login ouvre un navigateur, génère un API token et le stocke localement dans ~/.terraform.d/credentials.tfrc.json.

$ terraform login
Terraform will request an API token for app.terraform.io using your browser.
...
Token for app.terraform.io:
  Created: ...

Welcome to HCP Terraform!

• terraform logout pour révoquer / nettoyer.
• En CI/CD, on n'utilise pas terraform login : on injecte directement le token via la variable d'environnement TF_TOKEN_app_terraform_io.

I. Explorer & Change Requests

Explorer

Vue centralisée dans HCP Terraform qui permet de chercher et analyser toutes les ressources gérées à travers tous les workspaces de l'organisation, sans devoir ouvrir chaque workspace un par un.

Cas d'usage :

• "Quels workspaces utilisent encore Terraform 1.5 ?"
• "Combien de buckets S3 sont dans la région eu-west-1 ?"
• "Quels workspaces référencent ce module à la version < 2.0 ?"

L'Explorer s'appuie sur le state remote consolidé, et propose des filtres + un éditeur de requête.

Change Requests

Workflow de revue et approbation des changements proposés sur un workspace, intégré à HCP Terraform. Une Change Request encapsule un plan, le présente aux reviewers désignés, et permet l'approbation/refus avec commentaires avant que l'apply ne soit déclenché.

Pourquoi ?

• Séparation des rôles : l'auteur du changement n'est pas forcément celui qui approuve.
• Audit trail intégré (qui a approuvé quoi, quand, avec quel commentaire).
• Politique d'organisation : on peut exiger N approbateurs avant apply en production.

J. Bonnes pratiques

• Isoler les workspaces par environnement : évite les erreurs
• Pas de secrets dans le code : utiliser Vault, variables sensibles, ou mieux ephemeral + write_only
• Activez l'approbation manuelle en production
• Taguez les workspaces : pour filtres, logs, audit
• Utilisez des policies Sentinel ou OPA : éviter les erreurs critiques
• Suivez l'historique des states : revert possible
• Versionnez les modules internes dans le registry privé
• Utilisez l'API pour automatiser (CI/CD)
• Préférez le bloc cloud {} au backend "remote" pour les nouvelles configs
• Mutualisez les credentials via Variable Sets plutôt que de les dupliquer par workspace
• Chaînez les workspaces dépendants avec Run Triggers pour fiabiliser l'ordre de déploiement