Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 9: Remote State, Sperren und Verschlüsselung

Ziel: Den State aus dem Projektordner in einen S3-Speicher verlegen, mit einer Sperre gleichzeitige Läufe verhindern und den State mit der Verschlüsselung von OpenTofu schützen. · Dauer: ca. 90 min · Voraussetzung: Tag 8

Briefing

  • Ein Backend bestimmt, wo der State liegt. Standard ist local (die Datei terraform.tfstate). Im Team liegt er zentral, zum Beispiel in einem S3-Bucket.
  • Laufen zwei apply gleichzeitig, überschreibt der zweite die Arbeit des ersten. Eine Sperre verhindert das: OpenTofu legt neben dem State eine Lock-Datei an – nur wenn der Speicher das atomar kann („bedingtes Schreiben”).
  • Der State enthält Passwörter und Schlüssel. OpenTofu kann ihn verschlüsseln, bevor er das Backend erreicht – der Speicher sieht nur Chiffretext.
  • Henne und Ei: Der Speicher für den State wird nicht mit dem State verwaltet, den er speichert. Er entsteht einmal von Hand oder in einer eigenen kleinen Konfiguration.
 tag05, tag06 … ─► backend "s3" ─► Versity S3 Gateway :7070 ─► Bucket tofu-state
                     use_lockfile    (Volume s3-daten)          tag05/terraform.tfstate
                     encryption: aes_gcm, Schlüssel aus Passphrase   …tfstate.tflock

Terraform: Das S3-Backend mit use_lockfile gibt es dort seit 1.11. Die Verschlüsselung des States im Block encryption gibt es nur in OpenTofu.

Drill 1: Ein S3-Speicher

Als S3-Speicher dient das Versity S3 Gateway: ein schlanker Dienst, der einen Ordner als S3-API anbietet und bedingtes Schreiben beherrscht.

mkdir -p ~/tf-lab/tag09 && cd ~/tf-lab/tag09
docker volume create s3-daten >/dev/null
docker run -d --name s3 --restart unless-stopped -p 127.0.0.1:7070:7070 \
  -e ROOT_ACCESS_KEY=tofu -e ROOT_SECRET_KEY=lab-s3-pw-123456 \
  -v s3-daten:/data versity/versitygw:v1.10.0 posix /data | cut -c1-12
cat >> ~/tf-lab/setup/env.sh <<'EOF'
export AWS_ACCESS_KEY_ID=tofu                         # S3-Speicher (ab Tag 9)
export AWS_SECRET_ACCESS_KEY=lab-s3-pw-123456
EOF
source ~/tf-lab/setup/env.sh
sleep 2
curl -s -o /dev/null -w 'Bucket anlegen: %{http_code}\n' -X PUT \
  --aws-sigv4 "aws:amz:us-east-1:s3" \
  --user "$AWS_ACCESS_KEY_ID:$AWS_SECRET_ACCESS_KEY" http://127.0.0.1:7070/tofu-state
cat >> ~/tf-lab/setup/env.sh <<'EOF'
s3ls() { curl -s --aws-sigv4 "aws:amz:us-east-1:s3" \
  --user "$AWS_ACCESS_KEY_ID:$AWS_SECRET_ACCESS_KEY" "http://127.0.0.1:7070/$1"; }
EOF
source ~/tf-lab/setup/env.sh
s3ls | grep -o '<Name>[^<]*</Name>'

Erwartet:

3f9d2c1a7b4e
Bucket anlegen: 200
<Name>tofu-state</Name>
  • curl --aws-sigv4 signiert eine Anfrage so, wie S3 es verlangt – ohne eigenes S3-Werkzeug. PUT /tofu-state legt den Bucket an, GET / listet alle.
  • s3ls ist derselbe curl-Aufruf als kleine Funktion in env.sh: s3ls listet die Buckets, s3ls 'tofu-state?list-type=2' die Objekte, s3ls tofu-state/<schlüssel> holt eines.
  • OpenTofu liest die Zugangsdaten aus AWS_ACCESS_KEY_ID und AWS_SECRET_ACCESS_KEY. Sie stehen jetzt in env.sh – im Labor in Ordnung, in der Praxis kommen sie aus einem Secret-Speicher.

Fortschritt speichern? Kostenlos registrieren

Drill 2: Den State umziehen

Der State der beiden notes-Stacks aus Tag 5 zieht in den Bucket:

cd ~/tf-lab/tag05
cat > backend.tf <<'EOF'
terraform {
  backend "s3" {
    bucket                      = "tofu-state"
    key                         = "tag05/terraform.tfstate"
    region                      = "us-east-1"
    endpoints                   = { s3 = "http://127.0.0.1:7070" }
    use_path_style              = true
    use_lockfile                = true
    skip_credentials_validation = true
    skip_requesting_account_id  = true
    skip_metadata_api_check     = true
    skip_region_validation      = true
  }
}
EOF
tofu init -migrate-state -force-copy -no-color | grep -E 'Successfully|copy|initialized'
s3ls 'tofu-state?list-type=2' | grep -o '<Key>[^<]*</Key>'
wc -c < terraform.tfstate
tofu plan -no-color | tail -1

Erwartet:

Successfully configured the backend "s3"! OpenTofu will automatically
OpenTofu has been successfully initialized!
<Key>tag05/terraform.tfstate</Key>
0
No changes. Your infrastructure matches the configuration.
  • -migrate-state kopiert den bisherigen State ins neue Backend, -force-copy beantwortet die Rückfrage mit „ja”.
  • Die lokale Datei ist jetzt leer; der State lebt im Bucket. Gleiche Adressen, gleiche Objekte – der Plan sieht keinen Unterschied.
  • Die skip_…-Einstellungen schalten Prüfungen ab, die nur bei echtem AWS Sinn ergeben.

Fortschritt speichern? Kostenlos registrieren

Drill 3: Die Sperre

Eine kleine Übungskonfiguration mit einem absichtlich langsamen Schritt:

mkdir -p ~/tf-lab/tag09/sperre && cd ~/tf-lab/tag09/sperre
sed 's|tag05/terraform.tfstate|tag09/sperre.tfstate|' ~/tf-lab/tag05/backend.tf \
  > backend.tf
cat > main.tf <<'EOF'
resource "terraform_data" "langsam" {
  triggers_replace = timestamp()
  provisioner "local-exec" {
    command = "sleep 15"
  }
}
EOF
tofu init -no-color >/dev/null
tofu apply -auto-approve -no-color > erster.log 2>&1 &
sleep 6
s3ls 'tofu-state?list-type=2' | grep -o '<Key>[^<]*sperre[^<]*</Key>'
tofu plan -no-color -lock-timeout=0s 2>&1 | grep -E 'Error acquiring|Operation:|Who:'
wait
grep 'Apply complete' erster.log

Erwartet:

<Key>tag09/sperre.tfstate.tflock</Key>
Error: Error acquiring the state lock
  Operation: OperationTypeApply
  Who:       ubuntu@tf
Apply complete! Resources: 1 added, 0 changed, 0 destroyed.
  • Während der erste Lauf arbeitet, liegt ….tfstate.tflock im Bucket. Der zweite bekommt sie nicht und bricht ab – mit Angaben, wer sperrt und was er tut.
  • -lock-timeout=60s würde stattdessen bis zu einer Minute warten.
  • Bleibt eine Sperre nach einem Absturz liegen, löst tofu force-unlock <ID> sie. Nur, wenn sicher kein anderer Lauf mehr arbeitet (Tag 15).

Fortschritt speichern? Kostenlos registrieren

Drill 4: Den State verschlüsseln

cd ~/tf-lab/tag05
s3ls tofu-state/tag05/terraform.tfstate | grep -c 'lab-db-pw-123'
cat > encryption.tf <<'EOF'
variable "state_passphrase" {
  type      = string
  sensitive = true
}

terraform {
  encryption {
    key_provider "pbkdf2" "lab" {
      passphrase = var.state_passphrase
    }
    method "aes_gcm" "lab" {
      keys = key_provider.pbkdf2.lab
    }
    method "unencrypted" "migration" {}
    state {
      method = method.aes_gcm.lab
      fallback {
        method = method.unencrypted.migration
      }
    }
  }
}
EOF
echo 'export TF_VAR_state_passphrase=lab-state-passphrase-123      # nur Labor' \
  >> ~/tf-lab/setup/env.sh
source ~/tf-lab/setup/env.sh
tofu apply -auto-approve -no-color | grep 'Apply complete'
s3ls tofu-state/tag05/terraform.tfstate | jq -c 'keys'
s3ls tofu-state/tag05/terraform.tfstate | grep -c 'lab-db-pw-123'

Erwartet:

1
Apply complete! Resources: 0 added, 0 changed, 0 destroyed.
["encrypted_data","encryption_version","lineage","meta","serial"]
0
  • Vorher stand das Datenbank-Passwort im Klartext im Bucket (grep -c zählt die Zeile – der State ist eine einzige lange JSON-Zeile), jetzt nur noch Chiffretext. Der Schlüssel entsteht aus der Passphrase (PBKDF2) und verlässt nie die Maschine, auf der tofu läuft.
  • fallback mit unencrypted erlaubt OpenTofu einmalig, den alten unverschlüsselten State zu lesen. Das apply schreibt ihn verschlüsselt zurück.

Der Rückweg ist jetzt zu – die Fallback-Methode wird entfernt:

python3 - <<'PY'
import re
s = open("encryption.tf").read()
s = re.sub(r'\n    method "unencrypted" "migration" \{\}', "", s)
s = re.sub(r"\n      fallback \{.*?\n      \}", "", s, flags=re.S)
open("encryption.tf", "w").write(s)
PY
tofu plan -no-color | tail -1
TF_VAR_state_passphrase=falsche-passphrase-123 tofu plan -no-color 2>&1 \
  | grep -m1 'Error'

Erwartet:

No changes. Your infrastructure matches the configuration.
Error: error loading state: decryption failed for all provided methods

Ohne die richtige Passphrase kann niemand den State lesen – auch du nicht. Sie gehört in einen Passwort-Manager oder einen Vault, nicht nur in env.sh.

Fortschritt speichern? Kostenlos registrieren

Kontrollpunkt

s3ls 'tofu-state?list-type=2' | grep -o '<Key>[^<]*</Key>'

Erwartet:

<Key>tag05/terraform.tfstate</Key>
<Key>tag09/sperre.tfstate</Key>
cd ~/tf-lab/tag05 && tofu plan -detailed-exitcode -no-color >/dev/null; echo "Exit: $?"

Erwartet:

Exit: 0
docker ps --filter name=^s3$ --format '{{.Names}} {{.Image}}'

Erwartet:

s3 versity/versitygw:v1.10.0

Challenge

Zieh auch den State von Tag 6 (notes auf Kubernetes) in den Bucket, unter dem Schlüssel tag06/terraform.tfstate, und verschlüssle ihn gleich mit.

Hinweis: Kopier backend.tf und encryption.tf aus Tag 5. Für den ersten Lauf braucht es wieder die Fallback-Methode – oder du verschlüsselst direkt beim Umzug, denn der lokale State ist ja unverschlüsselt.

Lösung

cd ~/tf-lab/tag06
export TF_VAR_vm_ip=$VM_IP
sed 's|tag05/terraform.tfstate|tag06/terraform.tfstate|' ~/tf-lab/tag05/backend.tf \
  > backend.tf
cat > encryption.tf <<'EOF'
variable "state_passphrase" {
  type      = string
  sensitive = true
}

terraform {
  encryption {
    key_provider "pbkdf2" "lab" {
      passphrase = var.state_passphrase
    }
    method "aes_gcm" "lab" {
      keys = key_provider.pbkdf2.lab
    }
    method "unencrypted" "migration" {}
    state {
      method = method.aes_gcm.lab
      fallback {
        method = method.unencrypted.migration
      }
    }
  }
}
EOF
tofu init -migrate-state -force-copy -no-color >/dev/null
tofu apply -auto-approve -no-color | grep 'Apply complete'
s3ls tofu-state/tag06/terraform.tfstate | jq -r 'has("encrypted_data")'

Erwartet:

Apply complete! Resources: 0 added, 0 changed, 0 destroyed.
true

Beim Umzug liest OpenTofu den lokalen State über den Fallback und schreibt ihn verschlüsselt in den Bucket. Den Fallback kannst du danach wie in Drill 4 entfernen.

Fortschritt speichern? Kostenlos registrieren

Enterprise-Notiz

  • Echte Backends: S3 (AWS oder kompatibel), Azure Storage, Google Cloud Storage, pg (Postgres), HTTP. Wichtig sind Sperren, Versionierung des Buckets und eingeschränkter Zugriff – der State ist so wertvoll wie die Zugangsdaten darin.
  • Schlüssel statt Passphrase: In Produktion kommt der Schlüssel aus einem KMS (AWS, GCP) oder OpenBao/Vault (key_provider "openbao"), und wird regelmäßig gewechselt.
  • Ein Bucket, viele States: Ein Schlüssel pro Konfiguration und Umgebung (team/dienst/umgebung.tfstate). Rechte pro Präfix verhindern, dass ein Team den State eines anderen liest.