# Terraform State: Das Herzstück Ihrer Infrastruktur-Automatisierung

TL;DR / Management Summary Die State-Datei (terraform.tfstate) ist die wichtigste Datei in Ihrem Automatisierungsprojekt. Sie ist das einzige Bindeglied zwischen Ihrem Code (Soll-Zustand) und den echten VMs in Proxmox (Ist-Zustand). Ein Senior Admin speichert diese Datei niemals lokal, sondern nutzt ein Remote Backend (z.B. in GitLab, S3 oder Terraform Cloud) mit State Locking, um Datenverlust und Race-Conditions bei der Zusammenarbeit im Team zu verhindern.

# 1. Was steht im State?

Die Wahrheit in JSON.

Terraform speichert im State:

• Mappings: Welche HCL-Ressource gehört zu welcher VM-ID in Proxmox.
• Metadaten: IP-Adressen, MAC-Adressen, UUIDs.
• Abhängigkeiten: In welcher Reihenfolge wurden Ressourcen erstellt.
• Sensible Daten: Passwörter und API-Keys (daher: State-Datei zwingend verschlüsseln!).

# 2. Remote Backends

Sicherer Speicher für den Status.

Standardmäßig speichert Terraform den State lokal auf Ihrem Laptop.

• Problem: Wenn Ihr Kollege das Skript ausführt, weiß sein Terraform nichts von Ihren VMs und versucht diese erneut zu erstellen.
• Lösung: Nutzen Sie ein zentrales Repository.

# backend.tf
terraform {
  backend "http" {
    address        = "https://gitlab.firma.de/api/v4/projects/1/terraform/state/production"
    username       = "admin"
    password       = "personal-access-token"
    lock_address   = "..."
    unlock_address = "..."
  }
}

# 3. Deep Dive: State Locking

Den Cluster vor zwei Kapitänen schützen.

Wenn zwei Admins gleichzeitig terraform apply ausführen, könnte der State korrumpiert werden.

• Mechanismus: Das Remote Backend setzt eine “Sperre” (Lock).
• Wirkung: Der zweite Admin bekommt eine Fehlermeldung: “State is locked by Admin-A”.
• Anforderung: Nur Backends mit Locking-Support (S3 + DynamoDB, GitLab, Terraform Cloud) bieten diesen Schutz.

# 4. Day-2 Operations: State Manipulation

Reparatur am offenen Herzen.

Manchmal müssen Sie Terraform mitteilen, dass eine Ressource nicht mehr verwaltet werden soll oder dass eine VM manuell in den State aufgenommen werden muss.

• Import: terraform import proxmox_vm_qemu.vm100 100 (Nimmt eine bestehende VM in den Code auf).
• Remove: terraform state rm proxmox_vm_qemu.alt_vm (Löscht die VM aus dem State, aber nicht physisch in Proxmox).

# 5. Troubleshooting & “War Stories”

Wenn der State lügt.

# Top 3 Fehlerbilder

1. Symptom: Terraform will alle Ressourcen löschen und neu erstellen.

   • Ursache: Die State-Datei wurde gelöscht oder der Zugriff auf das Remote Backend schlägt fehl.
   • Lösung: STOPP! Nichts ausführen. State-Backup wiederherstellen.

2. Symptom: “Error acquiring the state lock”.

   • Ursache: Ein vorheriger Lauf ist abgestürzt und hat den Lock nicht gelöst.
   • Fix: terraform force-unlock <ID>.

3. Symptom: Secrets im State sind sichtbar.

   • Lösung: State-Backends mit nativer Verschlüsselung (At-Rest) nutzen.

# “War Story”: Der “Local-State” Albtraum

Ein Team von drei Admins arbeitete an einem Cluster. Admin A erstellte VMs mit lokalem State. Admin B wusste nichts davon und führte sein (leeres) Terraform-Skript aus. Das Ergebnis: Terraform (B) sah keine VMs im lokalen State und löschte daraufhin alle VMs in Proxmox, die er nicht “kannte” (da Admin B eine manage_all = true Option nutzte). Lehre: Aktivieren Sie ein Remote Backend als allerersten Schritt in jedem Projekt. Lokale States sind nur für “Hallo Welt” Beispiele gedacht.

# 6. Monitoring & Reporting

Backup des Backups.

# State Backups

Konfigurieren Sie Ihr Backend so, dass es Versionierung unterstützt (z.B. S3 Versioning).

• KPI: State File Freshness. Passt der Zeitstempel des States zum letzten erfolgreichen CI/CD Lauf?

# 7. Fazit & Empfehlung

State Management ist die Grundlage für Team-Kollaboration.

• Empfehlung: Nutzen Sie die GitLab Terraform Integration. Sie ist für Teams, die bereits GitLab nutzen, die einfachste und sicherste Lösung.
• Wichtig: Committen Sie niemals die Datei terraform.tfstate oder terraform.tfstate.backup in Ihr Git-Repository! Nutzen Sie stattdessen den .gitignore Eintrag.

# Anhang: Cheatsheet (State CLI)

# Referenzen

• Terraform Documentation: Purpose of Terraform State
• Remote Backend Types Reference
• GitLab: Terraform State Storage