Terraform und OpenTofu: Kern — Cheat Sheet

Der Spickzettel zur ersten Hälfte des Seminars Terraform und OpenTofu in der Praxis: Plan lesen, Projekt aufbauen, Typen, Ressourcen, Module und State. Er bringt nichts davon bei, dafür sind die Module da. Secrets, Umgebungen, Import, Tests, Pipelines, Betrieb und Migration stehen auf dem zweiten Blatt: Terraform und OpenTofu: Teambetrieb.

Maßgeblich für Argumente, Flags und Versionsstände sind die Terraform-Dokumentation und die OpenTofu-Dokumentation. Dieses Blatt trifft eine Auswahl. Wo die beiden Werkzeuge auseinandergehen, steht Nur OpenTofu dabei; die Befehle sind als terraform geschrieben, bei OpenTofu heißt es tofu.

Plan-Symbole: was mit einer Ressource passiert

Ob geändert oder ersetzt wird, legt der Provider je Argument fest. Im Plan steht es als # forces replacement.

# docker_container.web must be replaced
-/+ resource "docker_container" "web" {
      name = "saatplan-web"
    ~ ports {
        ~ external = 8008 -> 8080 # forces replacement
          internal = 80
      }
  }
Plan: 1 to add, 0 to change, 1 to destroy.

Vor jedem apply: Was wird ersetzt, was entfernt, und ist das gewollt? Der State ordnet jeder Ressource genau ein reales Objekt zu; fehlt er, will das Werkzeug alles neu anlegen.

Module: Infrastructure as Code einordnen · CLI-Workflow und Projektstruktur

Terraform oder OpenTofu

Interne Nutzung erlauben beide, die BSL schließt nur konkurrierende Angebote aus.

Die Unterschiede aus diesem Teil des Seminars (— heißt: dort nicht vorhanden):

Modul: Infrastructure as Code einordnen

Werkzeuge abgrenzen

Die Grenze folgt dem Lebenszyklus: Was gemeinsam entsteht und vergeht, gehört zu einem Werkzeug.

Modul: Infrastructure as Code einordnen

Projektdateien und was in Git gehört

Alle .tf-Dateien eines Verzeichnisses bilden zusammen eine Konfiguration, die Aufteilung ist Konvention. Jede Variable bekommt type und description.

terraform {
  required_version = ">= 1.16.0"
  required_providers {
    docker = {
      source  = "kreuzwerker/docker"
      version = "~> 4.6"
    }
  }
}

Ohne Internet: plugin_cache_dir und filesystem_mirror im Block provider_installation der CLI-Konfiguration; den Spiegel füllt terraform providers mirror.

Module: CLI-Workflow und Projektstruktur · HCL, Datentypen und robuste Konfigurationen

CLI-Zyklus: acht Befehle

fmt arbeitet nur im aktuellen Verzeichnis, für Unterordner braucht es -recursive.

terraform plan -out=saatplan.tfplan
terraform show saatplan.tfplan
terraform show -json saatplan.tfplan > plan.json
terraform apply saatplan.tfplan

apply mit Plandatei fragt nicht mehr nach. Die Datei enthält sensible Werte im Klartext.

Ohne -detailed-exitcode endet plan auch bei ausstehenden Änderungen mit 0.

Modul: CLI-Workflow und Projektstruktur

HCL: resource oder data, Variablen, Locals, Outputs

variable "umgebung" {
  type        = string
  description = "Zielumgebung, test oder prod"
}
locals {
  praefix = "saatplan-${var.umgebung}"
  restart = var.umgebung == "prod" ? "always" : "no"
  api_env = [for k, v in var.api.env : "${k}=${v}"]
}
output "web_name" {
  description = "Name des Web-Containers"
  value       = docker_container.web.name
}

Gelesen wird local.praefix, nicht locals. Ein Argument mit null verhält sich, als fehlte es. JSON und YAML baut man mit jsonencode und yamlencode, nicht per Template.

Modul: HCL, Datentypen und robuste Konfigurationen

Typen, optionale Attribute und Validierung

Die Doku ist deutlich: any nie verwenden, nur um sich die Typangabe zu sparen.

variable "api" {
  type = object({
    image   = string
    port    = number
    restart = optional(string, "unless-stopped")
    env     = optional(map(string), {})
  })
  description = "Einstellungen des API-Containers"
}
variable "api_port" {
  type        = number
  description = "Externer Port der Saatplan-API"
  validation {
    condition     = var.api_port >= 1024 && var.api_port <= 65535
    error_message = "Port 1024 bis 65535 erwartet."
  }
}

Fehlt ein optionales Attribut oder ist es null, gilt der Standardwert. Mehrere validation-Blöcke je Variable sind erlaubt; seit Terraform 1.9 und OpenTofu 1.9 dürfen sie auch andere Variablen einbeziehen.

Modul: HCL, Datentypen und robuste Konfigurationen

count, for_each und depends_on

resource "docker_container" "api" {
  for_each = toset(var.standorte)   # list(string)
  name     = "saatplan-api-${each.key}"
  image    = docker_image.api.image_id
  env      = ["STANDORT=${each.key}"]
}

for_each braucht eine Map oder ein Set aus Strings mit bekannten Schlüsseln, nicht „known after apply“.

Abhängigkeiten entstehen über Verweise, nicht über depends_on. Das kostet: mehr unbekannte Werte, mehr Ersetzungen, Data Sources erst beim apply gelesen. Und Reihenfolge ist nicht Bereitschaft.

Modul: Ressourcen modellieren und Änderungen steuern

Lifecycle-Regeln

Werte im lifecycle-Block müssen Literale sein, weil sie vor allen anderen Ausdrücken ausgewertet werden.

Modul: Ressourcen modellieren und Änderungen steuern

Precondition, Postcondition und Check

lifecycle {
  postcondition {
    condition     = length(self.ports) == 0
    error_message = "db veröffentlicht einen Port."
  }
}

In einer postcondition steht self für das Objekt selbst.

Modul: Ressourcen modellieren und Änderungen steuern

Gezielt eingreifen: -replace, -target, -exclude

terraform plan -out=saatplan.tfplan -replace='docker_container.api["sonnhalde"]'
terraform plan -target=docker_network.saatplan
tofu plan -exclude='docker_container.api["muehlwiese"]'

Statt Provisionern: upload-Block, Software ins Image, healthcheck und wait. Von count auf for_each zieht je Instanz ein moved-Block um.

Modul: Ressourcen modellieren und Änderungen steuern

Module: Schnittstelle und Provider

Ein Output ist ein Versprechen an alle Aufrufer; was nicht hinausgeht, darf sich ändern.

provider "docker" {
  alias = "test"
  host  = "ssh://deploy@docker-test.lindenhof.example"
}
module "saatplan_test" {
  source    = "./modules/saatplan-app"
  providers = { docker = docker.test }
}

Das Child Module deklariert nur required_providers mit source und Untergrenze (>= 4.6), keinen provider-Block: Sonst verträgt es kein count, for_each oder depends_on, und beim Entfernen fehlt der Provider zum Löschen. Ohne source nimmt das Werkzeug hashicorp/docker an.

Modul: Wiederverwendbare Module entwickeln

Modulquellen und Versionsbindung

version wirkt nur bei Registry-Quellen. Für die Registry heißt das Repository terraform-PROVIDER-NAME, Tags folgen Semantic Versioning (v1.0.4).

Modul: Wiederverwendbare Module entwickeln

State-Kommandos

Ändernde state-Kommandos schreiben immer ein Backup. Werkzeuge lesen den State über show -json und output -json, das Format kann sich ändern. terraform_remote_state liest nur Root-Outputs, braucht aber Lesezugriff auf den ganzen State samt sensibler Werte.

Modul: State, Backends und Zusammenarbeit

Remote Backend pg, Locking und Migration

Jedes Root Module braucht ein eigenes Schema. Zugangsdaten über die Umgebung (PG_CONN_STR, PGUSER, PGPASSWORD): Werte aus Code oder -backend-config landen in .terraform und in Plandateien.

terraform plan -lock-timeout=2m      # warten statt abbrechen
terraform init -migrate-state        # lokalen State ins Backend übernehmen

-reconfigure statt -migrate-state lässt den alten State zurück. Das pg-Backend führt keine Historie; gesichert wird per pg_dump.

Modul: State, Backends und Zusammenarbeit

Typische Fallen

• State und Plandatei im Commit. Beide tragen sensible Werte im Klartext ins Repository, plan.json ebenso.
• State gelöscht, weil die Container ja laufen. Der nächste Plan will alles neu anlegen. Von Hand editieren ist genauso falsch, dafür gibt es die state-Kommandos.
• Veralteter Plan. Hat sich der State seit dem Planen geändert, lehnt apply die Plandatei ab.
• Bequemer default. Ein Standardwert für Werte, die je Umgebung anders sind, verdeckt die vergessene Angabe.
• Validierung prüft nur die Form. Ob ein Port auf dem Host frei ist, weiß sie nicht. Unbekannte Werte verschieben die Prüfung bis zum apply.
• create_before_destroy mit festem Namen. Docker vergibt Containernamen nur einmal, das Ersetzen scheitert.
• ignore_changes = all. Friert die Ressource ein, auch gegen gewollte Änderungen.
• prevent_destroy überall. Blockiert auch gewollte Umbauten. Es gehört an Daten, die nicht neu entstehen können.
• replace_triggered_by auf ein wechselndes Attribut. Ersetzt das Objekt bei jedem Lauf.
• destroy löscht auch das Volume. Mit allen Daten darin, in prod nie beiläufig. Verwaltet wird das Volume, nicht die Daten darin.
• Ports aus Gewohnheit. Ein „nur zum Testen“ veröffentlichter Datenbankport ist danach von außen erreichbar.
• Modul reicht alles durch. Jedes Ressourcenargument als Variable heißt, das Modul verbirgt nichts mehr. Ganze Ressourcenobjekte als Output machen interne Attribute zum Vertrag.
• Variable ohne type. Sie nimmt jeden Wert an und scheitert erst tief im Plan.
• Umbenennen ohne deprecated. Aufrufer brechen ohne Vorwarnung.
• source zeigt auf einen Branch. Derselbe Aufruf liefert morgen anderen Code. Ein Breaking Change ohne neue Hauptversion wirkt genauso.
• Sicherung im selben Volume. Sie fällt mit dem State aus.
• Alter Stand mit -force zurückgespielt. Die Container sehen inzwischen anders aus.
• Gemischte OpenTofu-Versionen am pg-Backend. Ab OpenTofu 1.10 sperrt das Anlegen anders, also nie parallel auf eine Datenbank.