Was prüft terraform validate tatsächlich?

terraform validate ist ein eingebautes Terraform-Unterkommando, das eine statische Analyse deiner Konfigurationsdateien durchführt. Es liest jede .tf- und .tfvars-Datei im aktuellen Arbeitsverzeichnis - und rekursiv alle lokalen Module -, parst sie und prüft, ob die Konfiguration intern konsistent und strukturell gültig ist.

Statische Analyse, keine Ausführung

Das entscheidende Merkmal von terraform validate ist, dass es vollständig statisch ist. Es werden keine Netzwerkverbindungen aufgebaut, keine Provider-APIs aufgerufen und keine State-Datei gelesen. Die Prüfung findet vollständig im Speicher auf der Maschine statt, die den Befehl ausführt. Dadurch ist es in jeder Umgebung sicher, auch auf CI-Runnern ohne Cloud-Zugangsdaten, und es ist bei den meisten realen Konfigurationen in unter zwei Sekunden fertig.

Das steht im Gegensatz zu terraform plan, das dieselben statischen Prüfungen ausführt und dann Provider-APIs kontaktiert, um ein Diff gegen echte Infrastruktur zu berechnen. Validate ist das leichte erste Tor; plan ist das umfassende Tor vor dem Apply. Beide nacheinander auszuführen gibt dir die breiteste Abdeckung, bevor du dich auf eine Infrastrukturänderung festlegst.

Die drei Betriebsmodi

• Standardmodus – läuft nach terraform init; prüft Syntax, Schema gegen heruntergeladene Provider-Plugins und dateiübergreifende Referenzen
• Ohne init – existiert kein .terraform-Verzeichnis, läuft validate weiter, überspringt aber Provider-Schema-Prüfungen und meldet nur HCL-Parse-Fehler und Referenzprobleme, die ohne Provider-Metadaten auflösbar sind
• JSON-Modus (-json) – gibt ein strukturiertes JSON-Objekt mit einem booleschen valid, einer Ganzzahl error_count und einem Array diagnostics aus, geeignet für CI-Auswertung und Editor-Integration

Die drei Kategorien zu verstehen, die terraform validate abdeckt, hilft dir, genau zu wissen, was eine bestandene Validierung garantiert - und wo diese Garantie endet.

1. Korrektheit der HCL-Syntax

Der erste Durchgang parst jede .tf-Datei auf gültige HCL2-Syntax. Das erkennt nicht geschlossene Klammern, fehlende Gleichheitszeichen bei Attributzuweisungen, ungültige Blockdefinitionen, falsche Verwendung der Heredoc-Syntax und jede andere Konstruktion, die kein gültiges HCL ist. Eine Datei, die diese Prüfung nicht besteht, kann von Terraform überhaupt nicht gelesen werden - plan und apply würden ebenfalls fehlschlagen. Validate erkennt diese Fehler sofort mit Dateipfad und Zeilennummer.

2. Konformität mit dem Provider-Schema

Nach dem Parsen prüft validate jeden Ressourcenblock, Data-Source-Block und jede Provider-Konfiguration gegen das Schema des zuständigen Provider-Plugins. Schemas legen fest, welche Argumente gültig sind, welche erforderlich und welche optional sind und welchen Typ jedes Argument erwartet (string, number, bool, list, map, object). Validate erkennt ein Argument, das es für einen Ressourcentyp nicht gibt, ein Argument mit falschem Typ (etwa einen String, wo eine Zahl erwartet wird) und ein vollständig fehlendes Pflichtargument.

3. Gültigkeit interner Referenzen

Die dritte Kategorie ist die Prüfung von Querverweisen innerhalb der Konfiguration. Terraform-Konfigurationen referenzieren regelmäßig andere Ressourcen, Variablen, locals, Modul-Outputs und Data Sources über den Namen. Validate prüft, ob jede Referenz (z. B. var.region, local.common_tags, aws_vpc.main.id, module.networking.subnet_ids) auf etwas zeigt, das irgendwo in der Konfiguration tatsächlich deklariert ist. Eine nicht deklarierte Variable, ein Tippfehler in einer Ressourcenreferenz oder ein fehlender Modul-Output werden hier erkannt.

Die Grenzen von terraform validate sind ebenso wichtig wie sein Umfang. Viele Entwickler lernen sie kennen, wenn eine validierte Konfiguration zur Apply-Zeit fehlschlägt. Jede dieser Kategorien erfordert terraform plan, Integrationstests oder Policy-Werkzeuge wie tflint oder Checkov.

Reale Werte von Ressourcenargumenten

Validate prüft, ob ein Argument existiert und den richtigen Typ hat - aber nicht, ob der Wert in der realen Welt gültig ist. Eine aws_instance-Ressource kann ein ami-Argument haben, das ein String ist (typgerecht), doch validate kann nicht wissen, ob diese konkrete AMI-ID in deinem AWS-Konto oder deiner Region existiert. Ein ungültiges AMI, eine nicht existierende Security-Group-ID oder ein falscher Availability-Zone-Name bestehen validate und scheitern erst bei plan oder apply.

State-Datei und bestehende Infrastruktur

Validate liest niemals deine Terraform-State-Datei. Es kann nicht erkennen, dass eine von dir definierte Ressource mit einer bereits bestehenden kollidiert, dass eine Ressource außerhalb von Terraform gelöscht wurde (State-Drift) oder dass eine geplante Änderung eine Einschränkung verletzt, die sich nur gegen die aktuelle reale Infrastruktur bewerten lässt. All das sind Themen der Plan- und Apply-Phase.

Dynamische Ausdrücke, die von Data Sources abhängen

count-, for_each- und Bedingungsausdrücke sind gültiges HCL und validate parst sie problemlos. Wenn ihre Werte jedoch von einer Data Source abhängen (z. B. for_each = toset(data.aws_availability_zones.available.names)), kann der Ausdruck zur Validierungszeit nicht vollständig ausgewertet werden, weil die Data Source nicht abgefragt wurde. Validate bestätigt, dass die Syntax des Ausdrucks korrekt ist; das Laufzeitergebnis kann es nicht bestätigen.

Provider-Authentifizierung und Berechtigungen

Validate führt keinerlei API-Aufrufe aus. Es erkennt nicht, dass deine AWS-Zugangsdaten abgelaufen sind, dass deinem Servicekonto die nötigen IAM-Berechtigungen fehlen oder dass deine Provider-Konfiguration auf die falsche Region oder das falsche Projekt zeigt. Alle Authentifizierungsfehler treten erst bei plan oder apply auf, wenn der Provider-Client tatsächlich initialisiert wird und Aufrufe erfolgen.

Sicherheitsrichtlinien und Compliance-Regeln

Validate kennt keine Sicherheitsrichtlinien. Ein als öffentlich konfigurierter S3-Bucket, eine EC2-Instanz ohne Verschlüsselung oder eine Security Group mit 0.0.0.0/0-Ingress auf Port 22 bestehen validate ohne Warnung. Sicherheits- und Compliance-Prüfungen erfordern spezielle Policy-Werkzeuge wie Checkov, tfsec oder HashiCorp Sentinel.

Die häufigste Verwirrung rund um terraform validate betrifft den Unterschied zu terraform plan. Sie überschneiden sich deutlich, arbeiten aber auf verschiedenen Ebenen - und beide sind für einen vollständigen Workflow vor dem Apply nötig.

terraform validate prüft, ob eine Konfiguration syntaktisch gültig und intern konsistent ist, unabhängig von übergebenen Variablen oder vorhandenem State.

Wo sie sich überschneiden

Beide Befehle parsen deine HCL-Dateien und suchen Syntaxfehler. Beide prüfen Provider-Schemas, wenn Provider-Plugins verfügbar sind. Beide validieren interne Referenzen. Ein Konfigurationsfehler, den terraform validate findet, würde auch von terraform plan gefunden - validate ist einfach schneller und benötigt weder Cloud-Zugangsdaten noch ein State-Backend.

Wo plan weiter geht

terraform plan initialisiert Provider-Clients, authentifiziert sich bei Cloud-APIs, liest den aktuellen State und fragt Data Sources ab. Damit erkennt es Dinge, die validate nicht kann: einen Argumentwert, den die Provider-API ablehnt, eine Data-Source-Abfrage mit unerwarteten Ergebnissen, Quota- oder Rate-Limit-Fehler und Konflikte zwischen der vorgeschlagenen Konfiguration und der im State erfassten bestehenden Infrastruktur.

terraform validate auszuführen ist unkompliziert, doch die Schritte drumherum sind wichtig, um das Beste aus dem Befehl herauszuholen.

# Grundlegende Validierung
terraform validate

# JSON-Ausgabe für die CI-Auswertung
terraform validate -json

# Beispiel für die JSON-Ausgabestruktur
{
  "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 passt hervorragend in CI-Pipelines, weil es keine Cloud-Zugangsdaten benötigt, in Sekunden läuft und die meisten Autorenfehler erkennt, bevor sie eine Plan-Ausführung verschwenden oder ein Code-Review erreichen. Das Standardmuster ist, es bei jedem Pull Request auszuführen, der .tf-Dateien ändert.

Beispiel für GitHub Actions

Der folgende Workflow installiert Terraform, führt init mit -backend=false aus, um keine State-Zugangsdaten zu benötigen, und führt validate aus. Schlägt validate fehl, endet der Workflow mit einem Exit-Code ungleich null und blockiert das Mergen des Pull Requests.

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

validate mit tflint kombinieren

tflint ist ein Linter, der Probleme erkennt, die terraform validate übersieht - providerspezifische Regelprüfungen (etwa ungültige AWS-Instanztypen), ungenutzte Deklarationen und eigene Policy-Regeln. tflint nach validate im selben CI-Job auszuführen, ergibt eine breitere Abdeckung der statischen Analyse. tflint bietet providerspezifische Regel-Plugins für AWS, Azure und GCP, die Argumentwerte gegen bekannte gültige Optionen prüfen und damit Fehler finden, die die generische Schema-Prüfung von validate nicht erkennt.

• terraform fmt -check – prüft, ob der Code den Terraform-Stilkonventionen entspricht (schlägt fehl, wenn eine Datei neu formatiert werden muss)
• terraform validate – prüft Syntax, Schema-Konformität und interne Referenzen
• tflint – providerspezifische Regeln, Erkennung ungenutzter Variablen, Durchsetzung eigener Policies
• Checkov oder tfsec – Scanning von Sicherheits- und Compliance-Richtlinien
• terraform plan – Laufzeitvalidierung in einer Staging-Umgebung mit echten Zugangsdaten

terraform validate ist ein Fundament, keine Obergrenze. Ein ausgereifter Terraform-Workflow stapelt mehrere Validierungstechniken, um verschiedene Fehlerklassen an der richtigen Stelle im Entwicklungszyklus zu erkennen.

Erst formatieren, dann validieren

Führe in jedem Workflow - lokal und in der CI - terraform fmt vor validate aus. Kanonische HCL-Formatierung ist nicht nur Stil: Sie verhindert Grenzfälle, in denen uneinheitliche Abstände oder Kommentarplatzierung echte Fehler in der Parse-Ausgabe verschleiern. Der HCL-Formatierer von Aback Tools bietet dieselbe Normalisierung im Browser, ohne dass Terraform installiert sein muss - nützlich für schnelle Reviews oder zum Bearbeiten auf Maschinen, auf denen du terraform fmt nicht ausführen kannst.

In der CI immer init vor validate

validate ohne init liefert nur eine Teilanalyse - HCL-Parsen und Referenzprüfung, aber keine Provider-Schema-Validierung. Wer die Schema-Prüfungen überspringt, kann eine Konfiguration mergen, die einen Argumentnamen mit Tippfehler verwendet oder den falschen Typ an ein Ressourcenattribut übergibt. Die paar zusätzlichen Sekunden, die init -backend=false zum CI-Job hinzufügt, sind die Abdeckung wert.

-json für strukturierte CI-Ausgaben nutzen

Die standardmäßige, für Menschen lesbare Ausgabe von validate ist beim lokalen Debuggen klar, aber in automatisierten Pipelines ist die JSON-Ausgabe weit nützlicher. Mit -json kannst du das diagnostics-Array auswerten, um Dateipfade und Zeilennummern zu extrahieren, Pull-Request-Diffs mit Inline-Fehlerkommentaren über die GitHub-Checks-API annotieren oder Fehler in eine eigene Slack-Benachrichtigung einspeisen. Werte zuerst den booleschen valid aus - ist er true, kann das diagnostics-Array dennoch Warnungen enthalten, die es wert sind, angezeigt zu werden.

Alle Module unabhängig validieren

terraform validate in einem Root-Modul prüft auch aufgerufene lokale Module, entfernte Module werden jedoch erst geprüft, nachdem init sie heruntergeladen hat. Führe für Modul-Repositories validate während der Entwicklung separat in jedem Modulverzeichnis aus. So treten Schemafehler im Modul selbst zutage, bevor Konsumenten es überhaupt referenzieren.

.tf-Dateien vor dem Commit formatiert halten

Nutze einen Pre-Commit-Hook, der terraform fmt -check ausführt und fehlschlägt, wenn eine .tf-Datei nicht kanonisch formatiert ist. Das hält die gesamte Codebasis konsistent, vermeidet reine Stil-Diffs in Code-Reviews und macht die validate-Ausgabe leichter lesbar, weil der Code eine saubere Struktur hat. Entferne Entwicklerkommentare aus Produktionskonfigurationen mit dem Terraform-HCL-Kommentar-Entferner, um committete Dateien sauber und lesbar zu halten.