Dieses Dokument wurde mithilfe automatisierter maschineller Übersetzungstechnologie übersetzt. Wir bemühen uns um korrekte Übersetzungen, übernehmen jedoch keine Gewähr für die Vollständigkeit, Richtigkeit oder Zuverlässigkeit der übersetzten Inhalte. Im Falle von Abweichungen ist die englische Originalversion maßgebend und stellt den verbindlichen Text dar.

k3s etcd-Snapshot

Diese Seite beschreibt, wie man das k3s etcd-snapshot CLI-Tool verwendet, um etcd-Snapshots zu verwalten und wie man von einem etcd-Snapshot wiederherstellt.

K3s etcd-Snapshots werden im Dateisystem des Knotens gespeichert und können optional in einen S3-kompatiblen Objektspeicher für Katastrophenwiederherstellungsszenarien hochgeladen werden. Snapshots können sowohl automatisiert nach einem wiederkehrenden Zeitplan als auch manuell auf Abruf erstellt werden. Das k3s etcd-snapshot CLI-Tool bietet eine Reihe von Unterkommandos, die verwendet werden können, um Snapshots zu erstellen, zu löschen und zu verwalten.

Unterkommando Beschreibung

delete

Gegebene Snapshot(s) entfernen

ls, list, l

Snapshots auflisten

prune

Snapshots entfernen, die die konfigurierte Aufbewahrungsanzahl überschreiten

save

Einen etcd-Snapshot auf Anfrage auslösen

Für weitere Informationen zu den etcd-Snapshot-Unterkommandos führen Sie k3s etcd-snapshot --help aus.

Erstellen von Snapshots

  • Geplant

  • Auf Anfrage

Geplante Snapshots sind standardmäßig aktiviert, um 00:00 und 12:00 Uhr Systemzeit, mit 5 aufbewahrten Snapshots. Geplante Snapshots haben einen Namen, der mit etcd-snapshot beginnt, gefolgt vom Knotennamen und dem Zeitstempel.

Die folgenden Optionen steuern den Betrieb der geplanten Snapshots:

Flaggen Beschreibung

--etcd-disable-snapshots

Geplante Snapshots deaktivieren.

--etcd-snapshot-name

Setzt den Basisnamen der geplanten etcd-Snapshots. (Standard: etcd-snapshot)

--etcd-snapshot-compress

Komprimieren Sie etcd-Snapshots.

--etcd-snapshot-dir

Verzeichnis zum Speichern von Datenbank-Snapshots. (Standardstandort: $<data-dir>/db/snapshots)

--etcd-snapshot-retention

Anzahl der zu behaltenden Snapshots. (Standardeinstellung: 5)

--etcd-snapshot-schedule-cron

Snapshot-Intervallzeit im Cron-Spezifikationsformat. Zum Beispiel alle 5 Stunden 0 */5 * * * (Standard: 0 */12 * * *).

Der Wert für data-dir ist standardmäßig /var/lib/rancher/k3s und kann unabhängig durch Setzen des --data-dir Flags geändert werden.

Geplante Snapshots werden im Pfad gespeichert, der durch den Wert --etcd-snapshot-dir des Servers festgelegt ist. Wenn Sie möchten, dass sie in S3-kompatiblen Objektspeichern repliziert werden, beziehen Sie sich auf S3-Konfigurationsoptionen.

Snapshots können manuell gespeichert werden, indem der k3s etcd-snapshot save Befehl ausgeführt wird. Für diese Snapshots auf Anfrage gibt es keine Aufbewahrung, und der Benutzer muss sie manuell mit den Befehlen k3s etcd-snapshot delete oder k3s etcd-snapshot prune entfernen. Snapshots auf Anfrage haben einen Namen, der mit on-demand beginnt, gefolgt vom Knotennamen und dem Zeitstempel.

Die folgenden Optionen steuern den Betrieb von Snapshots auf Anfrage:

Flaggen Beschreibung

--name

Setzt den Basisnamen der etcd-Snapshots auf Anfrage. (Standard: on-demand)

--etcd-snapshot-compress

Komprimieren Sie etcd-Snapshots.

--etcd-snapshot-dir

Verzeichnis zum Speichern von Datenbank-Snapshots. (Standardstandort: $<data-dir>/db/snapshots)

Der Wert für data-dir ist standardmäßig /var/lib/rancher/k3s und kann unabhängig durch Setzen des --data-dir Flags geändert werden.

Das --name Flag kann nur beim Ausführen des k3s etcd-snapshot save Befehls gesetzt werden. Die anderen beiden können ebenfalls Teil der k3s server Konfigurationsdatei sein.

Snapshots auf Anfrage werden im Pfad gespeichert, der durch den Wert --etcd-snapshot-dir des Servers festgelegt ist. Wenn Sie möchten, dass sie in S3-kompatiblen Objektspeichern repliziert werden, beziehen Sie sich auf S3-Konfigurationsoptionen.

Löschen von Snapshots

Geplante Snapshots werden automatisch gelöscht, wenn die Anzahl der Snapshots die konfigurierte Aufbewahrungsanzahl (standardmäßig 5) überschreitet. Die ältesten Snapshots werden zuerst entfernt.

Um geplante Snapshot(s) oder Snapshot(s) auf Anfrage manuell zu löschen, können Sie den k3s etcd-snapshot delete Befehl verwenden:

k3s etcd-snapshot delete <SNAPSHOT-NAME-1> <SNAPSHOT-NAME-2> ...

Der prune Unterbefehl entfernt Snapshots, die mit dem Namenspräfix (on-demand standardmäßig) übereinstimmen und die konfigurierte Aufbewahrungsanzahl überschreiten. Er enthält das Flag --snapshot-retention, um die Aufbewahrungsanzahl festzulegen. Für geplante Snapshots überschreibt es die standardmäßige Aufbewahrungsrichtlinie. Snapshots auf Anfrage haben keine Aufbewahrungsrichtlinie, daher ist dieses Flag erforderlich.

Reduzieren Sie Snapshots auf Anfrage auf eine kleinere Anzahl:

k3s etcd-snapshot prune --snapshot-retention  <NUM-OF-SNAPSHOTS-TO-RETAIN>

Reduzieren Sie "geplante" Snapshots auf eine kleinere Anzahl:

k3s etcd-snapshot prune --name etcd-snapshot --etcd-snapshot-retention <NUM-OF-SNAPSHOTS-TO-RETAIN>

S3-kompatible Objektspeicherunterstützung

K3s unterstützt die Replikation von etcd-Snapshots zu und die Wiederherstellung von etcd-Snapshots aus S3-kompatiblen Objektspeichern. S3-Unterstützung ist sowohl für Snapshots auf Anfrage als auch für geplante Snapshots verfügbar.

Flaggen Beschreibung

--etcd-s3

Sicherung zu S3 aktivieren

--etcd-s3-endpoint

S3-Endpunkt-URL

--etcd-s3-endpoint-ca

S3 benutzerdefiniertes CA-Zertifikat zur Verbindung mit dem S3-Endpunkt

--etcd-s3-skip-ssl-verify

Deaktiviert die SSL-Zertifikatsvalidierung für S3

--etcd-s3-access-key

S3 Zugriffsschlüssel

--etcd-s3-secret-key

S3 geheimer Schlüssel

--etcd-s3-bucket

S3 Bucket-Name

--etcd-s3-region

S3 Region / Bucket-Standort (optional). Der Standardwert ist us-east-1.

--etcd-s3-folder

S3-Ordner

--etcd-s3-proxy

Proxy-Server, der bei der Verbindung zu S3 verwendet werden soll, wobei alle proxybezogenen Umgebungsvariablen überschrieben werden.

--etcd-s3-insecure

Deaktiviert S3 über HTTPS

--etcd-s3-timeout

S3-Timeout (Standard: 5m0s)

--etcd-s3-config-secret

Name des Geheimnisses im kube-system-Namespace, das zur Konfiguration von S3 verwendet wird, wenn etcd-s3 aktiviert ist und keine anderen etcd-s3-Optionen festgelegt sind

Zum Beispiel so würde die Erstellung und Löschung von etcd-Snapshots auf Anfrage in S3 funktionieren:

$ k3s etcd-snapshot --s3 --s3-bucket=test-bucket --s3-access-key=test --s3-secret-key=secret save
INFO[0155] Snapshot on-demand-server-0-1753178523 saved.
INFO[0155] Snapshot on-demand-server-0-1753178523 saved.

$ k3s etcd-snapshot --s3 --s3-bucket=test-bucket --s3-access-key=test --s3-secret-key=secret ls
Name                              Location                                                                          Size    Created
on-demand-server-0-1753178523     s3://test-bucket/test-folder/on-demand-server-0-1753178523                        5062688 2025-07-22T10:02:03Z
on-demand-server-0-1753178523     file:///var/lib/rancher/k3s/server/db/snapshots/on-demand-server-0-1753178523     5062688 2025-07-22T10:02:03Z

$ k3s etcd-snapshot --s3 --s3-bucket=test-bucket --s3-access-key=test --s3-secret-key=secret delete on-demand-server-0-1753178523
INFO[0000] Snapshot on-demand-server-0-1753178523 deleted.

$ k3s etcd-snapshot --s3 --s3-bucket=test-bucket --s3-access-key=test --s3-secret-key=secret ls
Name                              Location                                                                          Size    Created

S3-Aufbewahrung

Versionsschranke

Beginnend mit den Versionen v1.34.0+k3s1, v1.33.4+k3s1, v1.32.8+k3s1, v1.31.12+k3s1 enthält K3s ein neues Flag für die S3-Aufbewahrung. Es hat den gleichen Standardwert wie die lokale Snapshot-Aufbewahrung.

Flaggen Beschreibung

--etcd-s3-retention

Anzahl der Snapshots in S3, die aufbewahrt werden sollen. (Standard: 5)

Unterstützung für S3-Konfigurationsgeheimnisse

Versionsschranke

Die Unterstützung für S3-Konfigurationsgeheimnisse ist ab den Veröffentlichungen im August 2024 verfügbar: v1.30.4+k3s1, v1.29.8+k3s1, v1.28.13+k3s1.

K3s unterstützt das Lesen der etcd S3 Snapshot-Konfiguration aus einem Kubernetes-Geheimnis. Dies kann aus Sicherheitsgründen bevorzugt werden, um Anmeldeinformationen nicht in K3s-CLI-Flags oder Konfigurationsdateien fest einzugeben, oder wenn Anmeldeinformationen ohne Neustart von K3s rotiert werden müssen. Um die S3-Snapshot-Konfiguration über ein Geheimnis zu übergeben, starten Sie K3s mit --etcd-s3 und --etcd-s3-config-secret=<SECRET-NAME>. Das Geheimnis muss nicht existieren, wenn K3s gestartet wird, aber es wird bei jedem Snapshot-Speicher-/Liste-/Lösch-/Prune-Vorgang überprüft.

Das S3-Konfigurationsgeheimnis kann beim Wiederherstellen eines Snapshots nicht verwendet werden, da der apiserver nicht verfügbar ist, um das Geheimnis während einer Wiederherstellung bereitzustellen. Die S3-Konfiguration muss über die CLI beim Wiederherstellen eines auf S3 gespeicherten Snapshots übergeben werden.

Übergeben Sie nur die --etcd-s3 und --etcd-s3-config-secret Flags, um das Geheimnis zu aktivieren. Wenn andere S3-Konfigurationsflags festgelegt sind, wird das Geheimnis ignoriert.

Die Schlüssel im Geheimnis entsprechen den oben aufgeführten --etcd-s3-* CLI-Flags. Der etcd-s3-endpoint-ca Schlüssel akzeptiert ein PEM-kodiertes CA-Bundle, oder der etcd-s3-endpoint-ca-name Schlüssel kann verwendet werden, um den Namen einer ConfigMap im kube-system Namespace anzugeben, der ein oder mehrere PEM-kodierte CA-Bundles enthält.

apiVersion: v1
kind: Secret
metadata:
  name: k3s-etcd-snapshot-s3-config
  namespace: kube-system
type: etcd.k3s.cattle.io/s3-config-secret
stringData:
  etcd-s3-endpoint: ""
  etcd-s3-endpoint-ca: ""
  etcd-s3-endpoint-ca-name: ""
  etcd-s3-skip-ssl-verify: "false"
  etcd-s3-access-key: "AWS_ACCESS_KEY_ID"
  etcd-s3-secret-key: "AWS_SECRET_ACCESS_KEY"
  etcd-s3-bucket: "bucket"
  etcd-s3-folder: "folder"
  etcd-s3-region: "us-east-1"
  etcd-s3-insecure: "false"
  etcd-s3-timeout: "5m"
  etcd-s3-proxy: ""

Snapshots wiederherstellen

K3s durchläuft mehrere Schritte, wenn ein Snapshot wiederhergestellt wird:

  1. Wenn der Snapshot auf S3 gespeichert ist, wird die Datei in das Snapshot-Verzeichnis heruntergeladen.

  2. Wenn der Snapshot komprimiert ist, wird er dekomprimiert.

  3. Falls vorhanden, werden die aktuellen etcd-Datenbankdateien nach <data-dir>/server/db/etcd-old-$TIMESTAMP/ verschoben.

  4. Der Inhalt des Snapshots wird auf die Festplatte extrahiert, und die Prüfsumme wird überprüft.

  5. Etcd wird gestartet, und alle etcd-Cluster-Mitglieder außer dem aktuellen Knoten werden aus dem Cluster entfernt.

  6. CA-Zertifikate und andere vertrauliche Daten werden aus dem Datenspeicher extrahiert und auf die Festplatte geschrieben, für eine spätere Verwendung.

  7. Die Wiederherstellung ist abgeschlossen, und K3s kann neu gestartet und normal auf dem Server verwendet werden, auf dem die Wiederherstellung durchgeführt wurde.

  8. (optional) Agenten und Steuerungsserver können normal gestartet werden.

  9. (optional) Etcd-Server können neu gestartet werden, um dem Cluster wieder beizutreten, nachdem alte Datenbankdateien entfernt wurden.

Bei der Wiederherstellung eines Snapshots müssen Sie nicht die gleiche K3s-Version verwenden, die ihn erstellt hat; eine höhere Minor-Version ist ebenfalls akzeptabel.

Schritte zur Snapshot-Wiederherstellung

Wählen Sie die Registerkarte unten aus, die Ihrer Clusterkonfiguration entspricht.

  • Einzelner Server

  • Mehrere Server

  1. Stoppen Sie den K3s-Dienst:

    systemctl stop k3s
  2. Führen Sie k3s server mit dem --cluster-reset Flag aus, und --cluster-reset-restore-path gibt den Pfad zum wiederherzustellenden Snapshot an. Wenn der Snapshot auf S3 gespeichert ist, geben Sie die S3-Konfigurationsflags (--etcd-s3, --etcd-s3-bucket usw.) an und geben Sie nur den Dateinamen des Snapshots als Wiederherstellungspfad an.

    Die Verwendung des --cluster-reset Flags ohne Angabe eines wiederherzustellenden Snapshots setzt einfach das etcd-Cluster auf ein einzelnes Mitglied zurück, ohne einen Snapshot wiederherzustellen.

    k3s server \
      --cluster-reset \
      --cluster-reset-restore-path=<PATH-TO-SNAPSHOT>

    Ergebnis: K3s stellt den Snapshot wieder her und setzt die Cluster-Mitgliedschaft zurück, dann wird eine Nachricht ausgegeben, die anzeigt, dass es bereit ist, neu gestartet zu werden: Managed etcd cluster membership has been reset, restart without --cluster-reset flag now.

  3. Starten Sie K3s erneut:

    systemctl start k3s

Wenn eine etcd-s3 Backup-Konfiguration in der K3s-Konfigurationsdatei definiert ist, versucht die K3s-Wiederherstellung, die Snapshot-Datei aus dem konfigurierten S3-Bucket abzurufen. In diesem Fall sollte nur der Dateiname des Snapshots als Argument --cluster-reset-restore-path übergeben werden. Um von einer lokalen Snapshot-Datei wiederherzustellen, wo eine etcd-s3 Backup-Konfiguration vorhanden ist, fügen Sie das Argument --etcd-s3=false hinzu und übergeben Sie den vollständigen Pfad zur lokalen Snapshot-Datei im Argument --cluster-reset-restore-path.

Als Sicherheitsmechanismus erstellt K3s, wenn es das Cluster zurücksetzt, eine leere Datei unter /var/lib/rancher/k3s/server/db/reset-flag, die verhindert, dass Benutzer versehentlich mehrere Cluster-Rücksetzungen hintereinander ausführen. Diese Datei wird gelöscht, wenn K3s normal startet.

In diesem Beispiel gibt es 3 Server, S1, S2 und S3. Der Snapshot befindet sich auf S1.

  1. Stoppen Sie K3s auf allen Servern:

    systemctl stop k3s
  2. Führen Sie auf S1 k3s server mit der Option --cluster-reset aus und --cluster-reset-restore-path, die den Pfad zum wiederherzustellenden Snapshot angibt. Wenn der Snapshot auf S3 gespeichert ist, geben Sie die S3-Konfigurationsflags (--etcd-s3, --etcd-s3-bucket usw.) an und geben Sie nur den Dateinamen des Snapshots als Wiederherstellungspfad an.

    Die Verwendung des --cluster-reset Flags ohne Angabe eines wiederherzustellenden Snapshots setzt einfach das etcd-Cluster auf ein einzelnes Mitglied zurück, ohne einen Snapshot wiederherzustellen.

    k3s server \
      --cluster-reset \
      --cluster-reset-restore-path=<PATH-TO-SNAPSHOT>

    Ergebnis: K3s stellt den Snapshot wieder her und setzt die Cluster-Mitgliedschaft zurück, dann wird eine Nachricht ausgegeben, die anzeigt, dass es bereit ist, neu gestartet zu werden: Managed etcd cluster membership has been reset, restart without --cluster-reset flag now. Backup and delete ${datadir}/server/db on each peer etcd server and rejoin the nodes.

  3. Starten Sie K3s auf S1 erneut:

    systemctl start k3s
  4. Löschen Sie auf S2 und S3 das Datenverzeichnis /var/lib/rancher/k3s/server/db/:

    rm -rf /var/lib/rancher/k3s/server/db/
  5. Starten Sie K3s auf S2 und S3 erneut, um dem wiederhergestellten Cluster beizutreten:

    systemctl start k3s

Wenn eine etcd-s3 Backup-Konfiguration in der K3s-Konfigurationsdatei definiert ist, versucht die K3s-Wiederherstellung, die Snapshot-Datei aus dem konfigurierten S3-Bucket abzurufen. In diesem Fall sollte nur der Dateiname des Snapshots als Argument --cluster-reset-restore-path übergeben werden. Um von einer lokalen Snapshot-Datei wiederherzustellen, wo eine etcd-s3 Backup-Konfiguration vorhanden ist, fügen Sie das Argument --etcd-s3=false hinzu und übergeben Sie den vollständigen Pfad zur lokalen Snapshot-Datei im Argument --cluster-reset-restore-path.

Als Sicherheitsmechanismus erstellt K3s, wenn es das Cluster zurücksetzt, eine leere Datei unter /var/lib/rancher/k3s/server/db/reset-flag, die verhindert, dass Benutzer versehentlich mehrere Cluster-Rücksetzungen hintereinander ausführen. Diese Datei wird gelöscht, wenn K3s normal startet.

Wiederherstellung auf neuen Hosts

Es ist möglich, einen etcd-Snapshot auf einem anderen Host wiederherzustellen, als er erstellt wurde. Wenn Sie dies tun, müssen Sie das Server-Token übergeben, das ursprünglich beim Erstellen des Snapshots verwendet wurde, da es zur Entschlüsselung der Bootstrap-Daten im Snapshot verwendet wird. Der Prozess ist derselbe wie oben, aber ändern Sie Schritt 2 in:

  1. Im Knoten, der den Snapshot aufgenommen hat, speichern Sie den Wert von: /var/lib/rancher/k3s/server/token. Dies ist <BACKED-UP-TOKEN-VALUE> in Schritt 3.

  2. Kopieren Sie den Snapshot in den neuen Knoten. Der Pfad im Knoten ist <PATH-TO-SNAPSHOT> in Schritt 3.

  3. Initiieren Sie die Wiederherstellung vom Snapshot auf dem ersten Serverknoten mit den folgenden Befehlen:

    k3s server \
      --cluster-reset \
      --cluster-reset-restore-path=<PATH-TO-SNAPSHOT>
      --token=<BACKED-UP-TOKEN-VALUE>

    Der Tokenwert kann auch in der K3s-Konfigurationsdatei festgelegt werden.

  1. Knotenressourcen sind ebenfalls im etcd-Snapshot enthalten. Wenn Sie auf eine neue Gruppe von Knoten wiederherstellen, müssen Sie manuell alle alten Knoten löschen, die nicht mehr im Cluster vorhanden sind.

  2. Wenn ein Token in der K3s-Konfigurationsdatei festgelegt ist, stellen Sie sicher, dass es dasselbe wie das <BACKED-UP-TOKEN-VALUE> ist, andernfalls kann K3s nicht gestartet werden.

ETCDSnapshotFile benutzerdefinierte Ressourcen

Versionsschranke

ETCDSnapshotFiles sind ab den November 2023-Versionen verfügbar: v1.28.4+k3s2, v1.27.8+k3s2, v1.26.11+k3s2, v1.25.16+k3s4.

Snapshots können remote mit jedem Kubernetes-Client angezeigt werden, indem clusterweite ETCDSnapshotFile-Ressourcen aufgelistet oder beschrieben werden. Im Gegensatz zum k3s etcd-snapshot list Befehl, der nur Snapshots anzeigt, die für diesen Knoten sichtbar sind, verfolgen ETCDSnapshotFile Ressourcen alle Snapshots, die auf den Clustermitgliedern vorhanden sind.

$ kubectl get etcdsnapshotfile
NAME                                             SNAPSHOTNAME                        NODE           LOCATION                                                                            SIZE      CREATIONTIME
local-on-demand-k3s-server-1-1730308816-3e9290   on-demand-k3s-server-1-1730308816   k3s-server-1   file:///var/lib/rancher/k3s/server/db/snapshots/on-demand-k3s-server-1-1730308816   2891808   2024-10-30T17:20:16Z
s3-on-demand-k3s-server-1-1730308816-79b15c      on-demand-k3s-server-1-1730308816   s3             s3://etcd/k3s-test/on-demand-k3s-server-1-1730308816                                2891808   2024-10-30T17:20:16Z
$ kubectl describe etcdsnapshotfile s3-on-demand-k3s-server-1-1730308816-79b15c
Name:         s3-on-demand-k3s-server-1-1730308816-79b15c
Namespace:
Labels:       etcd.k3s.cattle.io/snapshot-storage-node=s3
Annotations:  etcd.k3s.cattle.io/snapshot-token-hash: b4b83cda3099
API Version:  k3s.cattle.io/v1
Kind:         ETCDSnapshotFile
Metadata:
  Creation Timestamp:  2024-10-30T17:20:16Z
  Finalizers:
    wrangler.cattle.io/managed-etcd-snapshots-controller
  Generation:        1
  Resource Version:  790
  UID:               bec9a51c-dbbe-4746-922e-a5136bef53fc
Spec:
  Location:   s3://etcd/k3s-test/on-demand-k3s-server-1-1730308816
  Node Name:  s3
  s3:
    Bucket:           etcd
    Endpoint:         s3.example.com
    Prefix:           k3s-test
    Region:           us-east-1
    Skip SSL Verify:  true
  Snapshot Name:      on-demand-k3s-server-1-1730308816
Status:
  Creation Time:  2024-10-30T17:20:16Z
  Ready To Use:   true
  Size:           2891808
Events:
  Type    Reason               Age   From            Message
  ----    ------               ----  ----            -------
  Normal  ETCDSnapshotCreated  113s  k3s-supervisor  Snapshot on-demand-k3s-server-1-1730308816 saved on S3