Jedes Terraform-Projekt startet sauber. Ein `main.tf`, ein paar Variablen, klare Resources. Nach zwei Jahren sieht dieselbe Codebase aus wie der Dachboden einer Erbtante: 400-Zeilen-Module, drei verschiedene State-Strukturen, Workspaces und Terragrunt gleichzeitig, niemand traut sich mehr zu applyen.
Das Problem ist nicht Terraform. Das Problem ist, dass die meisten Teams die Struktur erst dann ernsthaft designen, wenn sie bereits dringend einen Rewrite bräuchten. Hier ist die Struktur, die wir seit fünf Jahren bei Kunden einsetzen und die noch nie kollabiert ist.
Drei Ebenen, nicht mehr
Die wichtigste Regel: drei Ebenen von Terraform-Code. Mehr Abstraktionsebenen führen zu 'Module, die Module aufrufen, die Module aufrufen' — unlesbar und unwartbar.
- Ebene 1 — Leaf-Module: wrappen EINE Resource oder eine kleine Gruppe eng zusammenhängender Resources
- Ebene 2 — Service-Module: komponieren Leaf-Module zu einem Service (z.B. 'postgres-cluster' = aurora + security-groups + iam + backups)
- Ebene 3 — Environment-Configs: konkrete Instantiierungen der Service-Module mit Umgebungs-spezifischen Werten
Ein Repo pro Scope, nicht pro Service
Ein Anti-Pattern, das wir oft sehen: jedes Service-Team hat sein eigenes Terraform-Repo. Das klingt nach guter Isolation, aber führt zu Duplikation, Inkonsistenz und Audit-Albträumen.
Besser: ein Repo pro Scope — typischerweise 'infrastructure-global' (Networking, IAM, Organization-Policies), 'infrastructure-shared' (Databases, Caches, Message-Brokers) und 'infrastructure-apps' (Kubernetes-Cluster, Service-Mesh). Service-Teams contributen über PRs, aber die Strukturen gehören dem Platform-Team.
State-Management als First-Class-Concern
State ist der wichtigste Teil Ihrer Terraform-Strategie und wird am häufigsten vernachlässigt. Regeln, die wir konsequent anwenden:
- State immer in S3/Azure Blob/GCS mit Locking (DynamoDB / Blob Lease)
- State-Keys als Pfad-Hierarchie: `<env>/<scope>/<service>.tfstate`
- Remote-State-Reads sind OK; Remote-State-Dependencies sind ein Code-Smell
- Workspaces sind eine Falle — nutzt separate State-Files stattdessen
Apply-Strategie
Handgemachte `terraform apply` aus dem Entwickler-Terminal sind auch 2026 noch die häufigste Ursache für Prod-Outages. Atlantis oder Spacelift lösen das Problem: alle Applies laufen über PRs, Plan-Output ist automatisch im PR-Kommentar, Apply erfordert Approval.
“Der beste Terraform-Code ist der, den man nach zwei Jahren Abstand ohne Grit lesen kann.”
Zusammenfassung
Terraform-Struktur ist kein Framework-Problem, sondern ein Software-Engineering-Problem. Drei Ebenen, ein Repo pro Scope, Remote-State mit Locking, Apply über PR-Bot. Das ist alles. Der Rest ist Disziplin.