Terraform State

6 Kernkonzepte

Die wichtigsten Konzepte für den Terraform State: terraform.tfstate · Remote State · State Locking · terraform state · Sensitive Data · Backends Der Terraform State ist das Herzstück von Terraform – er speichert den aktuellen Zustand der verwalteten Infrastruktur. Diese Konzepte sind essenziell für die Zusammenarbeit im Team und die sichere Verwaltung von Ressourcen.

State-Datei – terraform.tfstate

terraform.tfstate · terraform.tfstate.backup

# Standard-State-Datei terraform.tfstate # Backup terraform.tfstate.backup

terraform.tfstate ist die zentrale Datei, die den aktuellen Zustand der von Terraform verwalteten Infrastruktur speichert. Sie enthält alle Ressourcen, ihre Attribute und Abhängigkeiten.

Wichtige Informationen in der State-Datei

Feld	Beschreibung
version	State-Format-Version
terraform_version	Verwendete Terraform-Version
resources	Liste aller verwalteten Ressourcen
outputs	Definierte Outputs mit Werten
serial	Inkrementelle Versionsnummer bei Änderungen
lineage	Eindeutige ID der State-Datei

Beispiele

# State-Datei anzeigen (nur zur Information)

cat terraform.tfstate

# State-Datei formatieren (hübsch ausgeben)

terraform show -json terraform.tfstate

# Nur Ressourcen-Liste anzeigen

terraform state list

Typische State-Datei (Auszug):
{
"version": 4,
"terraform_version": "1.5.0",
"resources": [
{
"mode": "managed",
"type": "aws_instance",
"name": "web",
"attributes": {
"ami": "ami-0c55b159cbfafe1f0",
"instance_type": "t2.micro"
}
}
]
}

⚠️ Warnung: Die State-Datei enthält sensible Daten wie Passwörter, Keys und IDs – Niemals in Git committen! Verwenden Sie Remote State mit sicheren Backends.

Remote State – State in der Cloud speichern

backend · S3 · Azure · GCS · Terraform Cloud

terraform { backend "s3" { bucket = "my-terraform-state" key = "prod/terraform.tfstate" region = "eu-central-1" } }

Remote State ermöglicht die Speicherung der State-Datei an einem zentralen Ort – ideal für Teamarbeit und Continuous Integration. Terraform unterstützt viele Backends.

Häufige Backends

Backend	Beschreibung
s3	AWS S3 (mit DynamoDB für State Locking)
azurerm	Azure Storage Account
gcs	Google Cloud Storage
terraform	Terraform Cloud / Terraform Enterprise
consul	HashiCorp Consul
kubernetes	Kubernetes Secrets
local	Lokale Datei (Standard)

Beispiele

# AWS S3 Backend mit DynamoDB Locking

terraform {

backend "s3" {

bucket = "tf-state-bucket"

key = "env/prod/terraform.tfstate"

region = "eu-west-1"

dynamodb_table = "tf-state-lock"

encrypt = true

}

# Azure Backend

backend "azurerm" {

resource_group_name = "rg-terraform"

storage_account_name = "tfstatesa"

container_name = "tfstate"

key = "prod.terraform.tfstate"

}

Tipp: Für Teamarbeit immer Remote State mit State Locking verwenden! S3 + DynamoDB oder Azure Storage + Blob Leases sind bewährte Kombinationen.

State Locking – Konflikte vermeiden

DynamoDB · Azure Storage · Consul

# Fehler bei aktivem Lock Error: Error acquiring the state lock # Lock manuell entfernen terraform force-unlock <LOCK_ID>

State Locking verhindert, dass mehrere Benutzer gleichzeitig Änderungen an der State-Datei vornehmen. Es wird von unterstützten Backends (S3+DynamoDB, Azure Storage) automatisch bereitgestellt.

Beispiele

# Lock-Status prüfen

terraform plan

# Lock bei Fehler manuell entfernen

terraform force-unlock <LOCK_ID>

# Lock-ID aus der Fehlermeldung entnehmen

Error: Error acquiring the state lock

Lock Info:

ID: 12345678-1234-1234-1234-123456789012

Path: my-bucket/prod/terraform.tfstate

# Mit AWS S3 + DynamoDB (automatisches Locking)

backend "s3" {

dynamodb_table = "terraform-state-lock"

}

⚠️ Vorsicht: terraform force-unlock sollte nur verwendet werden, wenn das Lock tatsächlich "stecken geblieben" ist (z.B. nach einem Abbruch). Ein manuelles Entsperren kann zu State-Korruption führen!

terraform state – State-Befehle

list · show · mv · rm · pull · push

terraform state list terraform state show aws_instance.web terraform state mv aws_instance.old aws_instance.new

terraform state Befehle ermöglichen die direkte Manipulation und Einsicht in die State-Datei – nützlich für Refactoring, Fehlerbehebung und Migration.

Wichtige State-Befehle

Befehl	Beschreibung
terraform state list	Alle Ressourcen im State auflisten
terraform state show <resource>	Details einer Ressource anzeigen
terraform state mv <src> <dst>	Ressource umbenennen oder verschieben
terraform state rm <resource>	Ressource aus dem State entfernen
terraform state pull	State aus Remote-Backend herunterladen
terraform state push	State in Remote-Backend hochladen
terraform state replace-provider	Provider in State ersetzen

Beispiele

# Alle Ressourcen auflisten

terraform state list

aws_instance.web

aws_security_group.sg

aws_vpc.main

# Details einer Ressource anzeigen

terraform state show aws_instance.web

# Ressource umbenennen (Refactoring)

terraform state mv aws_instance.web aws_instance.app_server

# Ressource aus State entfernen (Vorsicht!)

terraform state rm aws_instance.web

# State von Remote herunterladen

terraform state pull > state.json

Tipp: terraform state mv ist ideal für Refactoring – Sie können Ressourcen umbenennen, ohne sie neu erstellen zu müssen. terraform state rm entfernt Ressourcen nur aus dem State, die tatsächliche Infrastruktur bleibt erhalten.

Sensitive Data – State sicher halten

sensitive · sensitive_output · encryption

resource "aws_db_instance" "main" { password = var.db_password sensitive = true } output "secret" { value = resource.aws_db_instance.main.password sensitive = true }

Sensitive Data im State – Terraform speichert alle Werte im Klartext in der State-Datei. Verwenden Sie sensitive Attribute und Outputs, um sensible Daten zu schützen.

Best Practices für sensible Daten

Maßnahme	Beschreibung
Remote State	State in sicherem Backend speichern (S3, Azure, GCS mit Verschlüsselung)
State Encryption	Verschlüsselung für State-Backend aktivieren (z.B. SSE-S3)
sensitive = true	Ressourcen-Attribute als sensitive markieren
sensitive Outputs	Outputs als sensitive definieren (werden nicht im Log angezeigt)
.gitignore	terraform.tfstate und .terraform/ in .gitignore ausschließen
Variables	Sensible Variablen als sensitive deklarieren

Beispiele

# Variable als sensitive markieren

variable "db_password" {

type = string

sensitive = true

}

# Output als sensitive markieren

output "db_password" {

value = var.db_password

sensitive = true

}

# Sensitive Data in der State-Datei

# Wird als (sensitive value) angezeigt

# Terraform Cloud/Enterprise: Speicherung von sensitive Data

# Terraform Cloud speichert sensitive Daten verschlüsselt

Tipp: Verwenden Sie sensitive Outputs und Variablen, um zu verhindern, dass sensible Daten in Logs oder Konsolenausgaben erscheinen. Nutzen Sie für Produktion immer Remote State mit Verschlüsselung.

Backends – State-Speicherorte konfigurieren

backend · partial · init -reconfigure

terraform init -reconfigure terraform init -migrate-state # Backend-Konfiguration in backend.tf terraform { backend "s3" { bucket = "my-state-bucket" key = "prod/terraform.tfstate" region = "eu-west-1" } }

Backends definieren, wo der State gespeichert wird. Die Konfiguration erfolgt im terraform Block. Beim Wechsel des Backends muss terraform init mit speziellen Optionen ausgeführt werden.

Backend-Init-Optionen

Option	Beschreibung
-reconfigure	Backend neu konfigurieren (ignoriert vorhandene Konfiguration)
-migrate-state	State von altem zu neuem Backend migrieren
-force-copy	Migration ohne Bestätigung erzwingen
-backend-config	Backend-Konfiguration über CLI übergeben

Beispiele

# Backend-Konfiguration in backend.tf (partial)

terraform {

backend "s3" {

bucket = "tf-state-bucket"

key = "prod/terraform.tfstate"

region = "eu-west-1"

}

# Backend über CLI konfigurieren

terraform init -backend-config="bucket=tf-state-bucket" -backend-config="key=prod/terraform.tfstate"

# Von local zu remote migrieren

terraform init -migrate-state

# Backend wechseln (ohne Migration)

terraform init -reconfigure

Tipp: Verwenden Sie -migrate-state beim Wechsel von lokalem zu Remote-State. Bei einem reinen Backend-Wechsel ohne Migration verwenden Sie -reconfigure.

Terraform State im Überblick

State Aktueller Infrastruktur-Zustand
terraform.tfstate

Remote State in Cloud speichern
S3, Azure, GCS

Lock Konflikte vermeiden
DynamoDB, Azure Storage

Command State-Befehle
list, show, mv, rm

Sensitive Sensible Daten schützen
sensitive = true

Backend State-Speicher konfigurieren
backend.tf

Quick Summary

tfstate

State-Datei

Remote

Remote State

Lock

State Locking

state

State-Befehle

sensitive

Sensible Daten

backend

Backends

terraform state list · terraform state show aws_instance.web · terraform state mv aws_instance.old aws_instance.new · terraform init -migrate-state