Terraform zu OpenTofu migrieren: Leitfaden mit Kompatibilitätsrahmen

Kubernetes-Cluster aus Terraform- oder OpenTofu-Code bereitstellen? Terraform/OpenTofu gehört zu unserer Bereitstellung von Kubernetes-Clustern auf Hetzner und Proxmox. Kubernetes auf Hetzner ansehen

Dieser Leitfaden beschreibt, wie sich Terraform-Konfigurationen auf OpenTofu umstellen lassen, welche Terraform-Versionen dafür in Frage kommen und wo Umstellungen scheitern. Stand Oktober 2026: Terraform ist bei Version 1.17.1 (28.10.2026), OpenTofu bei 1.13.2 (21.10.2026). Grundlage sind die Primärquellen: HashiCorp, das OpenTofu-Projekt, die Linux Foundation und die CNCF, abgerufen am 28.10.2026. Der Artikel ist keine Rechtsberatung und keine Empfehlung zu wechseln, sondern die Entscheidungs- und Umsetzungsgrundlage.

Inhaltsverzeichnis

• Was OpenTofu ist und warum es den Fork gibt
• Lizenz und Projektstatus im Vergleich
• Kompatibilitätsrahmen nach Terraform-Version
• Funktionen von OpenTofu nach Version
• Migration in sieben Schritten
• Mehrere abhängige Konfigurationen
• Fallstricke
• Rollback
• Checkliste vor dem Wechsel
• Stand und Methodik
• Unser Vorgehen bei WZ-IT
• Weiterführende Guides

Was OpenTofu ist und warum es den Fork gibt

OpenTofu ist ein quelloffener Fork von Terraform unter der MPL-2.0. HashiCorp hat am 10.08.2023 angekündigt, die Lizenz künftiger Releases von MPL 2.0 auf die Business Source License 1.1 (BSL) umzustellen. Terraform 1.5.7 (07.09.2023) steht noch unter MPL-2.0, 1.6.0 (04.10.2023) unter der BSL. Am 20.09.2023 hat die Linux Foundation die Gründung von OpenTofu angekündigt, am 10.01.2024 erschien OpenTofu 1.6.0. Seit dem 23.04.2025 gehört das Projekt als Sandbox-Projekt zur CNCF.

Die BSL erlaubt den produktiven Einsatz, sofern Terraform nicht Dritten gehostet oder eingebettet angeboten wird, um mit den kostenpflichtigen Versionen des Lizenzgebers zu konkurrieren. Die aktuelle LICENSE-Datei nennt IBM als Lizenzgeber und zählt Produkte als konkurrierend, die gegen Bezahlung angeboten werden, auch über kostenpflichtigen Support, und sich wesentlich mit den kostenpflichtigen IBM-Versionen überschneiden. Interne Nutzung gilt ausdrücklich nicht als konkurrierendes Angebot. Jede Version wechselt vier Jahre nach Veröffentlichung auf MPL 2.0. Ob eine konkrete Nutzung unter die Klausel fällt, klärt die Rechtsabteilung, nicht dieser Artikel.

Lizenz und Projektstatus im Vergleich

Quellen: Releases von Terraform und OpenTofu, Support-Zeiträume im Kopf der Changelogs von 1.12, 1.13 und main, OpenTofu-FAQ.

Kompatibilitätsrahmen nach Terraform-Version

Die OpenTofu-FAQ sagt: OpenTofu arbeitet mit State-Dateien bis einschließlich Terraform 1.5.x. Für die Versionen danach hatte die Dokumentation bis OpenTofu 1.9 versionsspezifische Anleitungen für Terraform 1.5 bis 1.9, zum Beispiel für Terraform 1.9. Jede gilt für einen bestimmten Patchstand (1.5.7, 1.6.6, 1.7.5, 1.8.2, 1.9.8); ältere Patchstände sind vorher anzuheben. Aus den Anleitungen ergibt sich folgender Rahmen:

Die Anleitungen empfehlen, zuerst auf die passende OpenTofu-Version zu wechseln und danach auf die aktuelle Reihe zu aktualisieren. Für Terraform ab 1.10 gibt es seit OpenTofu 1.10 nur noch die allgemeine Anleitung. Funktionen, die Terraform nach 1.9 eingeführt hat, sind einzeln zu prüfen: Die Changelogs von OpenTofu 1.10 bis 1.13 nennen kein Gegenstück zu den action-Blöcken und zu List Resources mit terraform query aus Terraform 1.14 (Changelog) sowie zu Terraform Policy, das in 1.17 allgemein verfügbar wurde (Changelog). Ephemere Werte und write-only-Attribute unterstützt OpenTofu seit 1.11.

Funktionen von OpenTofu nach Version

Nicht jede Funktion ist ein Migrationsgrund, aber wer sie nutzt, erschwert sich den Rückweg zu Terraform. Die Tabelle stammt aus den Changelogs der jeweiligen Reihe; ob Terraform ein Gegenstück bietet, ist nicht Teil der Auswertung.

Zur State-Verschlüsselung nennt die Dokumentation Verschlüsselung im Ruhezustand für lokalen State und Backends. Als Methode gilt AES-GCM; Schlüssel kommen aus einer Passphrase (PBKDF2), AWS KMS, GCP KMS, Azure Key Vault, OpenBao, OVHcloud KMS oder einem externen Programm. Die Dokumentation grenzt ab: Verschlüsselung schützt nicht vor Datenverlust und nicht vor Replay, und ohne den Schlüssel ist der State nicht lesbar. Bereits verschlüsselte Daten dürfen Schlüsselquellen und Methoden nicht umbenennen; Änderungen laufen über fallback-Blöcke. Die Dokumentation empfiehlt je State einen eigenen KMS-Schlüssel. Ein Rückbau gelingt über die Methode unencrypted.

Migration in sieben Schritten

Die Schritte folgen der offiziellen Anleitung und ergänzen Prüfpunkte aus den Changelogs.

1. Bestand aufnehmen. Terraform-Version je Konfiguration, Provider, Module, Backends, required_version, genutzte Funktionen aus den Tabellen oben, Pipelines und alle Konfigurationen mit terraform_remote_state.
2. Sichern. Lokalen State kopieren, bei Remote-State die Backup-Verfahren des Backends nutzen (zum Beispiel S3-Versionierung), Code in einen Migrations-Branch committen, .terraform.lock.hcl mitsichern. Die Wiederherstellung einmal tatsächlich testen.
3. Terraform-Stand abschließen. Alle Änderungen mit terraform apply anwenden; terraform plan zeigt keine Änderungen. Offene Änderungen während der Migration sind laut den versionsspezifischen Anleitungen möglich, aber nicht empfohlen.
4. OpenTofu installieren. Die zum Rahmen passende Version wählen, mit tofu --version prüfen. Beide Binaries bleiben bis zur Abnahme nebeneinander verfügbar.
5. Initialisieren. tofu init lädt Provider und Module aus der OpenTofu-Registry und initialisiert das Backend. Die Lock-Datei behält den Namen .terraform.lock.hcl, enthält aber Einträge der Form registry.opentofu.org/hashicorp/<provider>. Den Diff prüfen und committen. -upgrade nur bewusst setzen, da es neue Provider-Versionen wählt.
6. Plan prüfen, anwenden, testen. tofu plan muss „No changes" zeigen. Bei unerwarteten Änderungen nicht anwenden, sondern die Ursache klären oder zurückgehen. Danach tofu apply (aktualisiert bei Bedarf das State-Format) und eine kleine, unkritische Änderung testen.
7. CI/CD umstellen. GitHub Actions: opentofu/setup-opentofu mit gepinntem tofu_version. Befehle von terraform auf tofu ändern, Caches für .terraform und Provider zurücksetzen, Hooks, Linter und Policy-Prüfungen auf Kompatibilität testen. Plan und Apply laufen mit demselben Werkzeug, Plan-Dateien werden nicht zwischen terraform und tofu übergeben (Einordnung). Zuletzt auf die aktuelle OpenTofu-Reihe aktualisieren (Upgrade-Anleitung).

Mehrere abhängige Konfigurationen

Systeme aus mehreren Konfigurationen, die per terraform_remote_state Daten teilen, folgen einer eigenen Anleitung. Grundlage: OpenTofu liest Terraform-State, Terraform liest OpenTofu-State aber nicht zuverlässig, vor allem bei OpenTofu-spezifischen Funktionen. Deshalb wird von unten nach oben migriert: zuerst die Konfigurationen, die von keiner anderen gelesen werden, zuletzt die Wurzeln. Für die Übergangszeit gilt: OpenTofu-spezifische Funktionen vermeiden, alle Konfigurationen vorher auf dieselbe Terraform-Version bringen und dokumentieren, welche Konfiguration auf welchem Werkzeug läuft.

Fallstricke

• required_version: Terraform 1.17 und OpenTofu 1.13 sind verschiedene Versionsreihen. Die Dokumentation empfiehlt für Module, die beide Werkzeuge bedienen, eine versions.tofu mit der OpenTofu-Bedingung und eine versions.tf mit der Terraform-Bedingung. Liegen gleichnamige .tf- und .tofu-Dateien vor, lädt OpenTofu nur die .tofu-Datei.
• Registry: Fehlt ein Provider oder Modul in der OpenTofu-Registry, scheitert tofu init mit Failed to query available provider packages oder Module not found. Die Anleitung rät, den Eintrag im Registry-Repository zu beantragen.
• Lock-Datei und Plattformen: Läuft die Pipeline auf einer anderen Plattform als der Entwicklerrechner oder bezieht sie Provider über einen Mirror, können Hashes der Zielplattform in der Lock-Datei fehlen. OpenTofu 1.12 nimmt über die Registry Hashes aller unterstützten Plattformen auf (h1); davor war tofu providers lock mit den Zielplattformen das Mittel der Wahl (Lock-Datei).
• State-Adressen und Namespaces: Seit 1.6.0 behandelt OpenTofu Provider-Adressen aus registry.terraform.io im State als registry.opentofu.org, abschaltbar mit OPENTOFU_STATEFILE_PROVIDER_ADDRESS_TRANSLATION=0. Providers ohne Namespace erhalten opentofu statt hashicorp; ein expliziter source in required_providers vermeidet Überraschungen.
• cloud und remote: Der Hostname muss seit 1.6.0 explizit angegeben werden; OpenTofu fällt nicht auf app.terraform.io zurück. Funktionen, die an die Plattform des Terraform-Herstellers gebunden sind, brauchen eine Alternative; die OpenTofu-Dokumentation verweist auf TACOS-Plattformen.
• Fehlende Funktionen in älteren OpenTofu-Reihen: Die Anleitungen für Terraform 1.8 und 1.9 führen encode_tfvars, decode_tfvars und encode_expr als nicht unterstützt. Seit OpenTofu 1.10 bietet der eingebaute Provider terraform Funktionen zum Kodieren und Dekodieren von .tfvars und zum Kodieren von Ausdrücken.
• Verschlüsselter State: Wer die Verschlüsselung mit der Migration einführt, sollte beide Änderungen trennen: erst migrieren und abnehmen, dann verschlüsseln.

Rollback

Die Dokumentation beschreibt den Rückweg so: OpenTofu nicht mehr verwenden, den State aus dem Backup wiederherstellen (falls er verändert wurde), terraform init und terraform plan ausführen und prüfen, dass keine unerwarteten Änderungen erscheinen, anschließend mit Terraform weiterarbeiten. Die versionsspezifischen Anleitungen empfehlen zusätzlich, den Rückweg mit einer kleinen, unkritischen Änderung zu testen. Je mehr OpenTofu-Funktionen genutzt werden, desto näher kommt der Rollback einer Wiederherstellung aus dem Backup, bei der Änderungen seit dem Wechsel verloren gehen (Einordnung). Praktisch heißt das: Backup-Stand und Lock-Datei bis zur Abnahme aufbewahren, den Rückweg an einer unkritischen Konfiguration proben und OpenTofu-spezifische Funktionen erst nach der Abnahme einsetzen.

Checkliste vor dem Wechsel

1. Terraform-Version je Konfiguration ist bekannt und liegt im Rahmen der Tabelle.
2. Genutzte Funktionen sind gegen die Anleitung der Version und den OpenTofu-Changelog geprüft.
3. Alle Provider und Module sind in registry.opentofu.org verfügbar oder gespiegelt.
4. State-Backup und Wiederherstellung sind getestet.
5. required_version und Dateinamen (.tf oder .tofu) sind geklärt.
6. Backends mit cloud oder remote haben einen expliziten Hostname.
7. Konfigurationen mit terraform_remote_state sind in eine Reihenfolge gebracht (von unten nach oben).
8. CI/CD-Image, Caches, Hooks und Policy-Prüfungen sind auf tofu getestet.
9. Lock-Datei enthält die Hashes aller Zielplattformen.
10. Der Rollback ist an einer unkritischen Konfiguration geprobt.
11. Der Lizenzstand von Terraform ist von der Rechtsabteilung bewertet.
12. Wer entscheidet über die Abnahme, und bis wann bleibt Terraform verfügbar?

Stand und Methodik

Die Aussagen geben den Stand vom 28.10.2026 wieder. Versionen und Daten stammen aus den GitHub-Releases, Lizenzen aus den LICENSE-Dateien der Repositories, Funktionen aus den Changelogs und der Dokumentation des OpenTofu-Projekts. Die Terraform-Spalten stützen sich auf Releases, LICENSE und Changelog von HashiCorp. Die Tabelle zu den Terraform-Versionen übernimmt die versionsspezifischen Anleitungen der OpenTofu-Dokumentation bis Reihe 1.9; für neuere Terraform-Versionen existiert keine solche Anleitung. Getestet wurde keine Migration, gemessen wurde nichts. Einordnungen sind als solche gekennzeichnet.

Quellen, abgerufen am 28.10.2026:

• HashiCorp: Ankündigung der BSL (10.08.2023) und LICENSE-Dateien von 1.5.7, 1.6.0 und main
• Linux Foundation: Ankündigung von OpenTofu und CNCF: Projektseite
• OpenTofu: FAQ, Migrationsanleitung, mehrere Konfigurationen, State-Verschlüsselung, Lock-Datei, Einstellungen
• Changelogs von OpenTofu 1.6, 1.7, 1.8, 1.9, 1.10, 1.11, 1.12 und 1.13
• Versionsspezifische Anleitungen im Stand von OpenTofu 1.9

Unser Vorgehen bei WZ-IT

Terraform oder OpenTofu gehört zu unserer Bereitstellung von Kubernetes-Clustern, wie die Seite zu Kubernetes auf Hetzner beschreibt. Der Ratgeber Talos auf Proxmox mit OpenTofu zeigt den Aufbau mit gepinnten Provider-Versionen, abgesichertem State und Abnahme. Für das eigene Team ergibt sich aus diesem Leitfaden diese Reihenfolge: Konfigurationen, Backends, Provider und Pipelines erfassen, die genutzten Funktionen gegen die Tabellen dieses Artikels prüfen und eine unkritische Konfiguration als Probe migrieren. Danach folgen die übrigen Konfigurationen von unten nach oben, die Pipelines werden umgestellt, und der Rollback bleibt bis zur Abnahme erhalten.

Weiterführende Guides

• Talos auf Proxmox mit OpenTofu automatisieren - OpenTofu-Aufbau mit gepinnten Providern und State-Schutz
• kube-hetzner, hetzner-k3s oder Talos - Clusterbereitstellung, kube-hetzner läuft mit beiden Werkzeugen
• Helm 3 auf Helm 4 migrieren - ein weiterer Migrationsleitfaden aus dem Cluster
• Kubernetes-Backup und Restore - Sicherung und Wiederherstellungstest
• Kubernetes auf Hetzner - Provisionierung auf Cloud und Bare Metal

Kubernetes-Cluster mit Terraform oder OpenTofu aufbauen lassen? Terraform/OpenTofu gehört zu unserer Bereitstellung von Kubernetes-Clustern auf Hetzner und Proxmox. Kubernetes auf Hetzner · Talos auf Proxmox mit OpenTofu