Que vérifie réellement terraform validate ?

terraform validate est une sous-commande intégrée de Terraform qui effectue une analyse statique de vos fichiers de configuration. Elle lit chaque fichier .tf et .tfvars du répertoire de travail courant (et récursivement les modules locaux), les analyse et vérifie si la configuration est cohérente en interne et structurellement valide.

De l'analyse statique, pas de l'exécution

La caractéristique clé de terraform validate est qu'il est entièrement statique. Aucune connexion réseau n'est établie, aucune API de provider n'est appelée et aucun fichier d'état n'est lu. Le contrôle se fait entièrement en mémoire, sur la machine qui exécute la commande. Il est donc sûr à exécuter dans n'importe quel environnement, y compris les runners de CI sans identifiants cloud, et il se termine en moins de deux secondes sur la plupart des configurations réelles.

C'est l'inverse de terraform plan, qui effectue tous ces contrôles statiques puis se connecte aux API des providers pour calculer un diff par rapport à l'infrastructure réelle. Validate est le premier filtre léger ; plan est le filtre complet avant application. Exécuter les deux à la suite offre la couverture la plus large avant de s'engager sur un changement d'infrastructure.

Les trois modes de fonctionnement

• Mode par défaut : s'exécute après terraform init ; vérifie la syntaxe, le schéma par rapport aux plugins de provider téléchargés et les références entre fichiers
• Sans init : si aucun répertoire .terraform n'existe, validate s'exécute quand même mais ignore les contrôles de schéma du provider et ne signale que les erreurs d'analyse HCL et les problèmes de référence qu'il peut résoudre sans métadonnées de provider
• Mode JSON (-json) : produit un objet JSON structuré avec un booléen valid, un entier error_count et un tableau diagnostics adapté à l'analyse en CI et aux intégrations d'éditeur

Comprendre les trois catégories couvertes par terraform validate permet de savoir exactement ce que garantit une validation réussie, et où cette garantie s'arrête.

1. La correction de la syntaxe HCL

La première passe analyse chaque fichier .tf à la recherche d'une syntaxe HCL2 valide. Elle détecte les accolades non fermées, les signes égal manquants dans les affectations d'attributs, les définitions de blocs invalides, un mauvais usage de la syntaxe heredoc et toute autre construction qui n'est pas du HCL valide. Un fichier qui échoue à ce contrôle ne peut pas être lu du tout par Terraform : plan et apply échoueraient aussi. Validate signale ces erreurs immédiatement avec le chemin du fichier et le numéro de ligne.

2. La conformité au schéma du provider

Après l'analyse, validate vérifie chaque bloc de ressource, bloc de source de données et configuration de provider par rapport au schéma défini par le plugin de provider concerné. Les schémas précisent quels arguments sont valides, lesquels sont requis ou facultatifs et quel type chaque argument attend (string, number, bool, list, map, object). Validate détecte un argument qui n'existe pas pour un type de ressource, un argument du mauvais type (par exemple une chaîne là où un nombre est requis) et un argument obligatoire totalement absent.

3. La validité des références internes

La troisième catégorie est la vérification des références croisées dans la configuration. Les configurations Terraform référencent régulièrement d'autres ressources, variables, locals, sorties de modules et sources de données par leur nom. Validate vérifie que chaque référence (par exemple var.region, local.common_tags, aws_vpc.main.id, module.networking.subnet_ids) pointe vers quelque chose de réellement déclaré dans la configuration. Une variable non déclarée, une faute de frappe dans une référence de ressource ou une sortie de module manquante seront toutes détectées ici.

Les limites de terraform validate sont aussi importantes que ce qu'il couvre. Beaucoup de développeurs les découvrent après qu'une configuration validée échoue au moment de l'application. Chacune de ces catégories nécessite terraform plan, des tests d'intégration ou des outils de politique comme tflint ou Checkov.

Les valeurs réelles des arguments de ressources

Validate vérifie qu'un argument existe et a le bon type, mais il ne peut pas vérifier si la valeur est valide dans le monde réel. Une ressource aws_instance peut avoir un argument ami de type chaîne (correct en type), mais validate n'a aucun moyen de savoir si cet AMI ID précis existe dans votre compte ou votre région AWS. Un AMI invalide, un ID de groupe de sécurité inexistant ou un nom de zone de disponibilité incorrect passeront validate et n'échoueront qu'au plan ou à l'apply.

Fichier d'état et infrastructure existante

Validate ne lit jamais votre fichier d'état Terraform. Il ne peut pas détecter qu'une ressource que vous définissez entre en conflit avec une ressource existante, qu'une ressource a été supprimée hors de Terraform (dérive de l'état) ou qu'un changement prévu enfreint une contrainte évaluable uniquement par rapport à l'infrastructure réelle actuelle. Tout cela relève des phases de plan et d'apply.

Expressions dynamiques dépendant de sources de données

Les expressions count, for_each et conditionnelles sont du HCL valide et validate les analyse sans problème. Mais si leurs valeurs dépendent d'une source de données (par exemple for_each = toset(data.aws_availability_zones.available.names)), l'expression ne peut pas être entièrement évaluée au moment de la validation, car la source de données n'a pas été interrogée. Validate confirme que la syntaxe de l'expression est correcte ; il ne peut pas confirmer le résultat à l'exécution.

Authentification et permissions du provider

Validate n'effectue aucun appel API. Il ne détectera pas que vos identifiants AWS sont expirés, que votre compte de service n'a pas les permissions IAM requises ou que la configuration de votre provider pointe vers la mauvaise région ou le mauvais projet. Toutes les erreurs d'authentification n'apparaissent qu'au plan ou à l'apply, quand le client du provider est réellement initialisé et que des appels sont effectués.

Politique de sécurité et règles de conformité

Validate n'a aucune notion de politique de sécurité. Un bucket S3 configuré comme public, une instance EC2 sans chiffrement ou un groupe de sécurité avec une entrée 0.0.0.0/0 sur le port 22 passeront validate sans aucun avertissement. Les contrôles de sécurité et de conformité exigent des outils de politique dédiés comme Checkov, tfsec ou HashiCorp Sentinel.

La principale source de confusion autour de terraform validate est sa différence avec terraform plan. Ils se recouvrent largement mais opèrent à des niveaux différents, et les deux sont nécessaires pour un workflow complet avant application.

terraform validate vérifie si une configuration est syntaxiquement valide et cohérente en interne, indépendamment des variables fournies ou de l'état existant.

Où ils se recouvrent

Les deux commandes analysent vos fichiers HCL et recherchent des erreurs de syntaxe. Les deux vérifient les schémas de provider lorsque les plugins sont disponibles. Les deux valident les références internes. Une erreur de configuration détectée par terraform validate serait aussi détectée par terraform plan : validate est simplement plus rapide et n'exige ni identifiants cloud ni backend d'état.

Où plan va plus loin

terraform plan initialise les clients de provider, s'authentifie auprès des API cloud, lit l'état actuel et interroge les sources de données. Cela lui permet de voir ce que validate ne peut pas : une valeur d'argument rejetée par l'API du provider, une requête de source de données aux résultats inattendus, des erreurs de quota ou de limitation de débit, et des conflits entre la configuration proposée et l'infrastructure existante suivie dans l'état.

Exécuter terraform validate est simple, mais les étapes qui l'entourent comptent pour en tirer le meilleur parti.

# Validation de base
terraform validate

# Sortie JSON pour l'analyse en CI
terraform validate -json

# Exemple de structure de sortie JSON
{
  "valid": false,
  "error_count": 2,
  "diagnostics": [
    {
      "severity": "error",
      "summary": "Unsupported argument",
      "detail": "An argument named 'regoin' is not expected here. Did you mean 'region'?",
      "range": {
        "filename": "main.tf",
        "start": { "line": 8, "column": 3 }
      }
    }
  ]
}

terraform validate est parfaitement adapté aux pipelines de CI : il n'exige aucun identifiant cloud, s'exécute en quelques secondes et détecte la plupart des erreurs d'écriture avant qu'elles ne consomment une exécution de plan ou n'arrivent en revue de code. Le schéma standard est de l'exécuter à chaque pull request qui modifie des fichiers .tf.

Exemple GitHub Actions

Le workflow ci-dessous installe Terraform, lance init avec -backend=false pour éviter d'avoir besoin d'identifiants de state, puis lance validate. Si validate échoue, le workflow se termine avec un code non nul et bloque la fusion de la pull request.

name: Terraform Validate

on:
  pull_request:
    paths:
      - '**.tf'
      - '**.tfvars'

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: hashicorp/setup-terraform@v3
        with:
          terraform_version: '1.8.0'

      - name: Terraform Init (no backend)
        run: terraform init -backend=false

      - name: Terraform Validate
        run: terraform validate -json | tee validate-output.json
        # Exit code 1 on any error - fails the workflow automatically

Combiner validate avec tflint

tflint est un linter qui détecte les problèmes que terraform validate laisse passer : contrôles de règles propres au provider (comme des types d'instances AWS invalides), déclarations inutilisées et règles de politique personnalisées. Exécuter tflint après validate dans le même job de CI offre une couverture d'analyse statique plus large. tflint dispose de plugins de règles propres à AWS, Azure et GCP qui vérifient les valeurs d'arguments par rapport à des options valides connues, détectant des erreurs que le contrôle générique de schéma de validate ne peut pas voir.

• terraform fmt -check : vérifie que le code respecte les conventions de style Terraform (échoue si un fichier doit être reformaté)
• terraform validate : vérifie la syntaxe, la conformité au schéma et les références internes
• tflint : règles propres au provider, détection des variables inutilisées, application de politiques personnalisées
• Checkov ou tfsec : analyse des politiques de sécurité et de conformité
• terraform plan : validation à l'exécution dans un environnement de staging avec de vrais identifiants

terraform validate est une fondation, pas un plafond. Un workflow Terraform mature empile plusieurs techniques de validation pour détecter différentes classes d'erreurs au bon moment du cycle de développement.

Formatez avant de valider

Exécutez terraform fmt avant validate dans tous les workflows, locaux comme en CI. Le formatage HCL canonique n'est pas qu'une question de style : il évite les cas limites où un espacement ou un placement de commentaire incohérent masque de vraies erreurs dans la sortie d'analyse. Le formateur HCL d'Aback Tools offre la même normalisation dans votre navigateur sans avoir Terraform installé - utile pour des revues rapides ou pour éditer sur des machines où vous ne pouvez pas lancer terraform fmt.

Toujours init avant validate en CI

Exécuter validate sans init ne donne qu'une analyse partielle : analyse HCL et vérification des références, mais pas de validation du schéma du provider. Ignorer les contrôles de schéma signifie que vous pouvez fusionner une configuration qui utilise un nom d'argument mal orthographié ou passe le mauvais type à un attribut de ressource. Les quelques secondes que init -backend=false ajoute au job de CI valent la couverture obtenue.

Utilisez -json pour une sortie structurée en CI

La sortie lisible par défaut de validate est claire pour le débogage local, mais la sortie JSON est bien plus utile dans des pipelines automatisés. Avec -json, vous pouvez analyser le tableau diagnostics pour extraire chemins de fichiers et numéros de ligne, annoter les diffs de pull request avec des commentaires d'erreur en ligne via l'API GitHub Checks, ou envoyer les erreurs dans une notification Slack personnalisée. Analysez d'abord le booléen valid : s'il vaut true, le tableau diagnostics peut encore contenir des avertissements qu'il vaut la peine de signaler.

Validez chaque module indépendamment

terraform validate dans un module racine vérifie aussi les modules locaux appelés, mais les modules distants ne sont contrôlés qu'après leur téléchargement par init. Pour les dépôts de modules, exécutez validate séparément dans chaque répertoire de module pendant le développement. Cela fait apparaître les erreurs de schéma du module lui-même avant que les consommateurs ne le référencent.

Gardez les fichiers .tf formatés avant de committer

Utilisez un hook pre-commit qui exécute terraform fmt -check et échoue si un fichier .tf n'est pas au format canonique. Cela garde tout le code cohérent, évite les diffs purement stylistiques en revue de code et rend la sortie de validate plus lisible grâce à une structure de code propre. Supprimez les commentaires de développement des configurations de production avec le suppresseur de commentaires Terraform HCL pour garder les fichiers committés propres et lisibles.