Terraform und OpenTofu: Teambetrieb — Cheat Sheet

Der Spickzettel zur zweiten Hälfte des Seminars Terraform und OpenTofu in der Praxis: wo Geheimnisse trotz sensitive landen, wie Umgebungen getrennt werden, wie Bestand übernommen und Drift behandelt wird, welche Prüfung welchen Fehler findet, woran ein gespeicherter Plan gebunden ist — und worin sich die beiden Werkzeuge inzwischen unterscheiden. Sprache, Ressourcen, Module und State stehen auf dem ersten Blatt: Terraform und OpenTofu: Kern.

Maßgeblich für Argumente, Flags und Versionsstände ist die Originaldoku — developer.hashicorp.com/terraform und opentofu.org/docs. Dieses Blatt trifft eine Auswahl, Stand Terraform 1.16 und OpenTofu 1.13 (Ende September 2026); die Befehle gelten mit tofu statt terraform gleich.

Zugänge trennen und wo Geheimnisse landen

Ein Lauf braucht drei verschiedene Zugänge: zum Backend mit dem State, zum Zielsystem des Providers und die Identität der Umgebung, in der er läuft.

Wer den Docker-Daemon steuern darf, hat faktisch Root-Rechte auf dem Host — der kritischste Zugang.

sensitive = true wirkt nur auf die Anzeige. Ein normales Argument wie env speichert der Provider vollständig im State:

Modul: Secrets und sensible Daten

Ephemeral Values, Write-only und State-Verschlüsselung

Ephemeral Values existieren nur während eines Laufs und landen weder im State noch in der Plan-Datei: Variablen und Outputs mit ephemeral = true und Ephemeral Resources aus einem ephemeral-Block. In eine verwaltete Ressource gelangen sie nur über Write-only Arguments — und die muss der Provider anbieten, etwa password_wo samt password_wo_version einer Cloud-Datenbank. Rotiert wird über eine höhere _wo_version; ohne sie plant das Werkzeug keine Änderung.

Der Docker-Provider 4.6 hat kein Argument mit der Endung _wo; ephemere Werte gehen dort nur in den Provider-Block (etwa registry_auth). Der Ausweg ist eine Datei, deren Pfad allein im State steht:

resource "docker_container" "db" {
  env = ["POSTGRES_PASSWORD_FILE=/geheim/db"]
  volumes {
    host_path      = "/srv/saatplan/geheim"
    container_path = "/geheim"
    read_only      = true
  }
}

OpenTofu verschlüsselt seit 1.7 State und Plan-Dateien selbst — im encryption-Block innerhalb von terraform oder über TF_ENCRYPTION. Terraform kennt keinen solchen Block; dort verschlüsselt allenfalls das Backend.

encryption {
  key_provider "pbkdf2" "saatplan" {
    passphrase = var.state_passphrase   # mindestens 16 Zeichen
  }
  method "aes_gcm" "saatplan" {
    keys = key_provider.pbkdf2.saatplan
  }
  state { method = method.aes_gcm.saatplan }
  plan  { method = method.aes_gcm.saatplan }
}

Statt pbkdf2 gehen Schlüssel aus AWS KMS, GCP KMS, Azure Key Vault oder OpenBao. Beim Umstellen und Rotieren steht die alte Methode als fallback, bis jeder State neu geschrieben ist; danach enforced = true. Was Verschlüsselung nicht leistet: Sie schützt nicht vor Datenverlust (ohne Schlüssel ist der State verloren), verhindert keinen Replay mit einem älteren State und ersetzt keine Berechtigungen — wer tofu ausführt, sieht die Geheimnisse weiterhin. Key Provider und Methoden nie umbenennen, ihre Namen stehen im State.

Modul: Secrets und sensible Daten

Umgebungen: Workspaces oder getrennte Root Modules

Test und Produktion dürfen sich keinen State teilen.

Unterschiede gehören in Variablenwerte, nicht in Bedingungen im Modul: terraform.tfvars wird automatisch geladen, weitere Dateien per -var-file. Dann steht der Unterschied zwischen test und prod im Diff. Beim pg-Backend braucht jede Umgebung ein eigenes schema_name — sonst teilen sich beide die Zeile default und damit den State.

Mehrere Ziele in einer Konfiguration laufen über alias; an ein Modul geht die Konfiguration mit providers = { docker = docker.prod } im module-Block.

Zwischen Teams wird per Datenquelle nach Namen übergeben, nicht per Schreibzugriff.

terragrunt run --all arbeitet die Units in der Reihenfolge ihrer dependency-Blöcke ab. Das Werkzeug ordnet nur, was schon geschnitten ist — die State-Grenzen kommen zuerst.

Modul: Umgebungen und größere Strukturen

Bestand übernehmen: import, moved, removed

Die Doku empfiehlt den Block. Die ID muss beim Plan bekannt sein; die Zieldatei von -generate-config-out darf noch nicht existieren, und die Generierung gilt in beiden Werkzeugen als experimentell. Ziel ist ein Plan mit 1 to import und sonst nur Nullen.

import {
  to = docker_container.db
  id = var.db_container_id
}
moved {
  from = docker_container.db
  to   = module.saatplan_db.docker_container.db
}
removed {
  from = docker_volume.daten
  lifecycle {
    destroy = false
  }
}

moved hält eine neue Adresse fest (in geteilten Modulen stehen lassen — ihr Entfernen bricht ältere Aufrufer); er wandelt keine verwaltete Ressource in eine Data Source um. removed ohne destroy = false löscht das Objekt, als wäre die Ressource aus dem Code entfernt worden.

Modul: Bestand übernehmen und refaktorieren

Drift erkennen und behandeln

terraform plan -refresh-only        # nur lesen: was hat sich draußen geändert?
terraform apply -refresh-only       # Abweichung bewusst in den State übernehmen
terraform plan -detailed-exitcode   # 0 = keine Änderung, 1 = Fehler, 2 = Drift

terraform refresh ist veraltet — es übernimmt Abweichungen ohne Rückfrage.

Beim Docker-Provider zeigt sich Drift so: Ein gestoppter Container gilt als Änderung (must_run), docker update --restart erscheint bei restart, ein gelöschter und neu gestarteter Container hat eine neue ID und gilt als verschwunden.

Module: Bestand übernehmen und refaktorieren · Betrieb, Fehler und Upgrades

Welche Prüfung welchen Fehler findet

validate läuft auch nach init -backend=false — so prüft die Pipeline, ohne den Remote State anzufassen. Ehrlich zur Abdeckung: Für kreuzwerker/docker pflegt TFLint keinen Regelsatz (nur AWS, Azure, Google Cloud), und Checkov hat keine Regel für docker_container, docker_image oder docker_network — ein grünes Ergebnis heißt dort: nichts geprüft.

# *.tftest.hcl — run-Block führt plan oder apply aus (Standard: apply)
mock_provider "docker" {}
run "web_port_unter_1024_abgelehnt" {
  command = plan
  variables { ports = { web = 80 } }
  expect_failures = [var.ports]
}
run "db_port_bleibt_intern" {
  command = plan
  assert {
    condition     = length(docker_container.db.ports) == 0
    error_message = "saatplan-db veröffentlicht Ports"
  }
}

In expect_failures stehen nur eigene Bedingungen: Validierungen, Pre- und Postconditions, check-Blöcke. Eine reale Umgebung braucht ein Test, wenn Port-Bindung, Netzanschluss oder Volume-Mount die Frage sind oder ein Dienst antworten muss. Am Ende jeder Datei wird in umgekehrter run-Reihenfolge zerstört — auch nach roten Assertions.

Modul: Automatisierte Tests und Qualitätsprüfungen

Pipeline: Stufen und gespeicherter Plan

Mit -input=false bricht ein Schritt ab, statt zu warten. Ausgeführt wird der geprüfte Plan, nicht ein neuer — dafür laut Doku das Arbeitsverzeichnis samt .terraform archivieren und am selben absoluten Pfad auspacken.

Betriebssystem und Architektur müssen bei Plan und Apply gleich sein. -auto-approve beim Apply eines gespeicherten Plans wirkt nicht. Ein Lauf je State, keiner wird abgebrochen:

concurrency:
  group: saatplan-infra-prod
  cancel-in-progress: false
  queue: max          # bis zu 100 wartende Läufe statt verwerfen

Der State-Lock des Backends bleibt die letzte Absicherung. Schon ein Plan führt Provider-Code aus und braucht Zugang zum Ziel — Pull Requests aus Forks bekommen deshalb nur fmt, validate und Tests mit Mocks.

Policies lesen den Plan als JSON (terraform show -json). Zur Regel gehört ein Ausnahmeprozess — conftest kennt exception-Regeln, Checkov den Kommentar checkov:skip samt Begründung; jede Ausnahme bekommt ein Ablaufdatum.

Modul: Pipelines und freigegebene Änderungen

Fehlgeschlagene Läufe und Wiederherstellung

Bricht apply ab, sind die bis dahin ausgeführten Änderungen real; zurückgerollt wird nicht automatisch, ein halb erzeugtes Objekt ist in der Regel tainted.

Ein erneutes apply vor dem state push erzeugt einen geforkten State. In der Pipeline das Arbeitsverzeichnis als Artefakt sichern, bevor der Runner es wegräumt. Das pg-Backend führt keine State-Historie und nutzt Advisory Locks, die mit der Sitzung fallen — force-unlock gibt es dort nicht.

HCP Terraform läuft bei HashiCorp, Terraform Enterprise beim Kunden — beide führen nur Terraform aus.

Modul: Betrieb, Fehler und Upgrades

Terraform und OpenTofu im Vergleich

OpenTofu will mit Terraform-Konfigurationen kompatibel bleiben, und die meisten laufen ohne Änderung. Seit der Abspaltung entwickeln sich beide aber getrennt weiter. Stand: Terraform 1.16, OpenTofu 1.13.

Wer beide Werkzeuge bedient, bleibt bei der gemeinsamen Teilmenge. Experimentelle Funktionen können sich in jedem Release ändern.

Module: Terraform und OpenTofu vergleichen und migrieren · Secrets und sensible Daten · Automatisierte Tests und Qualitätsprüfungen · Umgebungen und größere Strukturen · Betrieb, Fehler und Upgrades · KI-gestützte IaC-Entwicklung

Migration nach OpenTofu: Prüffragen und Rückweg

Auf HCP Terraform und Terraform Enterprise entscheidet die Plattform. Der erste Nachweis ist ein tofu plan ohne Änderungen; er zeigt nur, dass OpenTofu den State richtig liest. Erst eine angewendete kleine Änderung beweist, dass es die Umgebung auch verwaltet. tofu init ergänzt die Lock-Datei um die neuen Provider-Adressen — sie gehört in den Commit.

Wann der Rückweg zugeht: Solange nur Gemeinsames genutzt wird, führen terraform init und plan zurück. Verschlüsselter State ist für Terraform nicht mehr lesbar — dann ist die Entscheidung endgültig. Jede nur in OpenTofu verfügbare Funktion macht den Rückweg zur Umbauarbeit; wer ihn offenhalten will, bündelt Eigenes in .tofu-Dateien, die Terraform nicht liest.

Modul: Terraform und OpenTofu vergleichen und migrieren

KI-Werkzeuge und MCP Server

Wer plan aufrufen darf, kann auch apply aufrufen — die Rechte legt das Team fest, nicht das Modell. Im Kontext gehören Werkzeug und Version (OpenTofu 1.13 oder Terraform 1.16), Provider-Version, Modulschnittstelle und Sicherheitsvorgaben; ohne Provider-Version erfindet das Modell Argumente aus älteren Releases. Prüfgrundlagen statt Vertrauen:

tofu version                              # CLI und Provider-Versionen
tofu providers schema -json > schema.json # welche Argumente es wirklich gibt
tofu validate
tofu plan -out=vorschlag.tfplan
tofu show -json vorschlag.tfplan > plan.json

Statt --toolsets gehen einzelne Werkzeuge mit --tools — nie beide zugleich. Der Server kennt nur Terraform; für OpenTofu-Code sind opentofu.org und der OpenTofu MCP Server die Quelle.

Modul: KI-gestützte IaC-Entwicklung

Typische Fallen

• Ein Admin-Zugang für alles. Wer den State liest, kann dann auch produktiv ausrollen.
• Passwort im backend-Block. Die Verbindungszeichenfolge steht damit im Repository.
• Secret Store angebunden, Wert trotzdem im State. Er wurde über ein normales Argument weitergereicht.
• Ephemere Variable an env. Normale Argumente lehnen ephemere Werte mit einem Fehler ab.
• prod aus test kopiert. Bald sind es zwei Konfigurationen, und ein Fix landet nur in einer.
• States lesen sich gegenseitig über terraform_remote_state — ein Neuaufbau wird unmöglich.
• generated.tf ungeprüft übernommen. Darin stehen Standardwerte, berechnete Werte und Umgebungsvariablen im Klartext, samt Passwort.
• Fehlende Zugangsdaten für Drift gehalten. Sie sehen aus wie gelöschte Objekte — erst den Plan lesen.
• Test-Container nach hartem Abbruch. Sie bleiben stehen — per labels markieren; Tests mit apply nie neben prod.
• Saved plan is stale mit neuem Plan umgangen. Ausgeführt wird dann etwas ohne Freigabe; ebenso ein abgelehnter Plan, dessen Artefakt noch herumliegt.
• -lock=false als Rettung. Öffnet die Tür für zwei gleichzeitige Applies.
• Kompatibilität aus dem gemeinsamen Ursprung gefolgert statt per Plan geprüft.
• Terraform und OpenTofu abwechselnd gegen dieselbe Umgebung — oder die Pipeline ruft weiter terraform auf, obwohl längst tofu gilt.
• State, Plan-Ausgabe oder Passwort im Prompt. Sensible Werte fließen so ins KI-Werkzeug ab.
• Freigabe, weil die Pipeline grün ist — nicht, weil der Plan verstanden wurde.