Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 3: State verstehen

Ziel: Wissen, was im State steht und warum er wichtig ist, Abhängigkeiten lesen, Änderungen von außen (Drift) erkennen und gezielt einzelne Ressourcen ersetzen. · Dauer: ca. 75 min · Voraussetzung: Tag 2

Briefing

  • Der State (terraform.tfstate) ist OpenTofus Gedächtnis: Er verbindet jede Ressource im Code mit einem echten Objekt (über dessen ID) und hält die zuletzt bekannten Werte fest.
  • Bei jedem plan liest OpenTofu den echten Zustand neu ein (Refresh) und vergleicht dreifach: Code, State, Wirklichkeit.
  • Drift heißt: Jemand hat außerhalb von OpenTofu etwas geändert. Der Plan zeigt es, -refresh-only übernimmt die Wirklichkeit in den State, ohne etwas zu ändern.
  • Der State enthält alle Attribute – auch Passwörter. Er wird nie von Hand bearbeitet und nie ins Git eingecheckt.
 Code (*.tf) ─┐
 State ───────┼─► tofu plan ─► Unterschiede ─► apply
 Wirklichkeit ┘   (Refresh)        └ Drift: „has been deleted / changed outside"

Drill 1: Was im State steht

mkdir -p ~/tf-lab/tag03 && cd ~/tf-lab/tag03
cat > main.tf <<'EOF'
terraform {
  required_providers {
    docker = {
      source  = "kreuzwerker/docker"
      version = "~> 4.6"
    }
  }
}

provider "docker" {}

resource "docker_network" "notes" {
  name = "notes-tag03"
}

resource "docker_volume" "db" {
  name = "notes-db-tag03"
}

resource "docker_image" "postgres" {
  name         = "postgres:18.6-alpine"
  keep_locally = true
}

resource "docker_container" "db" {
  name  = "notes-db-tag03"
  image = docker_image.postgres.image_id
  env = [
    "POSTGRES_USER=notes",
    "POSTGRES_PASSWORD=lab-db-pw-123",
    "POSTGRES_DB=notes",
  ]
  networks_advanced {
    name = docker_network.notes.id
  }
  volumes {
    volume_name    = docker_volume.db.name
    container_path = "/var/lib/postgresql"
  }
}
EOF
tofu init -no-color >/dev/null
tofu apply -auto-approve -no-color | grep 'Apply complete'
tofu state list
tofu state show docker_container.db | grep -E '^    (name|hostname|restart) +='
jq -c '{version, serial, lineage: .lineage[0:8]}' terraform.tfstate
grep -c 'lab-db-pw-123' terraform.tfstate

Erwartet:

Apply complete! Resources: 4 added, 0 changed, 0 destroyed.
docker_container.db
docker_image.postgres
docker_network.notes
docker_volume.db
    hostname                                    = "9e78154a87ae"
    name                                        = "notes-db-tag03"
    restart                                     = "no"
{"version":4,"serial":1,"lineage":"dd1ff8d3"}
1
  • Der State ist JSON. serial zählt jede Änderung am State hoch, lineage kennzeichnet genau diesen State – OpenTofu weigert sich, einen State mit fremder lineage zu überschreiben.
  • Das Datenbank-Passwort steht im Klartext darin. Wer den State lesen kann, kennt alle Geheimnisse dieser Konfiguration (Tag 9 und 12).
  • tofu state show zeigt eine Ressource so, wie OpenTofu sie zuletzt gesehen hat – auch Werte, die du nie gesetzt hast, wie den hostname.

Fortschritt speichern? Kostenlos registrieren

Drill 2: Abhängigkeiten

tofu graph | grep -- '->' | grep -v provider

Erwartet (eingerückt):

"[root] docker_container.db (expand)" -> "[root] docker_image.postgres (expand)"
"[root] docker_container.db (expand)" -> "[root] docker_network.notes (expand)"
"[root] docker_container.db (expand)" -> "[root] docker_volume.db (expand)"

Jede Zeile ist eine Kante: Der Container hängt an Image, Netz und Volume. [root] und (expand) sind interne Markierungen von OpenTofu, grep -v provider blendet die Kanten zum Provider aus.

Der Graph entsteht aus den Referenzen im Code. Beim Anlegen geht OpenTofu von unten nach oben (erst Image, Netz und Volume, dann der Container), beim Löschen umgekehrt. Fehlt eine Referenz, obwohl eine Abhängigkeit besteht, hilft depends_on = [ … ].

Fortschritt speichern? Kostenlos registrieren

Drill 3: Drift

Jemand löscht den Container von Hand:

docker rm -f notes-db-tag03 >/dev/null
tofu plan -no-color | grep -E 'has been deleted|will be created|Plan:'

Erwartet:

  # docker_container.db will be created
Plan: 1 to add, 0 to change, 0 to destroy.

Der Refresh hat bemerkt, dass der Container fehlt, und der Plan legt ihn neu an. Das Volume ist geblieben – die Daten auch. Manchmal soll aber die Wirklichkeit gewinnen:

tofu plan -refresh-only -no-color | grep -E 'has been deleted|refresh-only|Objects'
tofu apply -refresh-only -auto-approve -no-color | grep -E 'Apply complete'
tofu state list | grep -c docker_container
tofu apply -auto-approve -no-color | grep 'Apply complete'

Erwartet:

Note: Objects have changed outside of OpenTofu
  # docker_container.db has been deleted
This is a refresh-only plan, so OpenTofu will not take any actions to undo
Apply complete! Resources: 0 added, 0 changed, 0 destroyed.
0
Apply complete! Resources: 1 added, 0 changed, 0 destroyed.

apply -refresh-only schreibt nur den State neu: Der Container ist dort jetzt auch weg. Das nächste normale apply legt ihn wieder an, weil der Code ihn verlangt.

Fortschritt speichern? Kostenlos registrieren

Drill 4: Gezielt ersetzen

docker ps -q --filter name=notes-db-tag03
tofu apply -replace=docker_container.db -auto-approve -no-color | grep 'Apply'
docker ps -q --filter name=notes-db-tag03
tofu plan -target=docker_volume.db -no-color 2>&1 | grep -E 'targeting|Plan:|No changes'

Erwartet (die IDs weichen ab – wichtig ist, dass sie sich unterscheiden):

3f2a9c1b7d4e
Apply complete! Resources: 1 added, 0 changed, 1 destroyed.
8c0d5e6f1a2b
No changes. Your infrastructure matches the configuration.
Warning: Resource targeting is in effect
  • -replace=adresse erzwingt das Neuanlegen – etwa wenn ein Container hängt, obwohl seine Konfiguration stimmt.
  • -target=adresse beschränkt Plan und Apply auf eine Ressource und ihre Abhängigkeiten. OpenTofu warnt ausdrücklich: Das ist ein Notbehelf, kein Alltag.

Fortschritt speichern? Kostenlos registrieren

Drill 5: Sicherungen und State lesen

ls terraform.tfstate*
tofu show -json | jq '.values.root_module.resources[].address'
tofu state pull | jq '.serial'

Erwartet (die Zahl hängt von deinen Läufen ab):

terraform.tfstate
terraform.tfstate.backup
"docker_container.db"
"docker_image.postgres"
"docker_network.notes"
"docker_volume.db"
4
  • Vor jedem Schreiben sichert OpenTofu den alten State als terraform.tfstate.backup – genau eine Generation.
  • tofu show -json und tofu state pull sind die offiziellen Wege, den State zu lesen. Die Datei direkt zu lesen klappt auch, aber nur solange der State lokal liegt.

Fortschritt speichern? Kostenlos registrieren

Kontrollpunkt

tofu state list | wc -l

Erwartet:

4
tofu plan -detailed-exitcode -no-color >/dev/null; echo "Exit: $?"

Erwartet:

Exit: 0
cat .gitignore 2>/dev/null || echo "noch keine .gitignore"

Erwartet:

noch keine .gitignore

Challenge

Leg eine .gitignore an, die verhindert, dass State, Sicherungen und der Ordner .terraform ins Git kommen – die Lock-Datei aber schon. Prüf es mit git status in einem frischen Repository.

Hinweis: git init -q und git status --short --ignored.

Lösung

cat > .gitignore <<'EOF'
.terraform/
*.tfstate
*.tfstate.*
*.tfvars
crash.log
EOF
git init -q && git status --short | sort

Erwartet:

?? .gitignore
?? .terraform.lock.hcl
?? main.tf

*.tfvars ist eine Vorsichtsmaßnahme: Dort landen gern Passwörter. Variablenwerte ohne Geheimnisse dürfen trotzdem ins Git – dann mit eigenem Namen wie dev.auto.tfvars und einer Ausnahme !dev.auto.tfvars.

Fortschritt speichern? Kostenlos registrieren

Enterprise-Notiz

  • State gehört nicht auf einen Laptop: Im Team liegt er zentral, verschlüsselt und mit Sperre gegen gleichzeitige Läufe (Tag 9).
  • State-Größe: Eine Konfiguration mit Tausenden Ressourcen macht jeden Plan langsam und jeden Fehler teuer. Kleine, getrennte States (je Dienst, je Umgebung) sind leichter zu beherrschen.
  • Drift regelmäßig suchen: Ein geplanter tofu plan -detailed-exitcode meldet Exit-Code 2, sobald jemand von Hand geändert hat (Tag 14).