K3s Backup: etcd-Snapshots erstellen und wiederherstellen

Stand: 10.10.2026

Ein K3s Backup für einen Cluster mit eingebettetem etcd erstellst du mit k3s etcd-snapshot. K3s plant lokale Snapshots standardmäßig bereits zweimal täglich ein. Für einen belastbaren Notfallplan prüfst du sie jedoch, kopierst sie in einen S3-kompatiblen Speicher und sicherst den Server-Token getrennt.

Auf einen Blick

• Die K3s-Snapshot-Befehle gelten für eingebettetes etcd, nicht pauschal für SQLite oder externe Datenbanken.
• Standardmäßig entstehen lokale Snapshots um 00:00 und 12:00 Uhr; pro Server bleiben fünf erhalten.
• On-demand-Snapshots haben keine automatische Aufbewahrung und müssen deshalb bereinigt werden.
• Der Server-Token gehört zwingend in das Backup-Konzept, weil er vertrauliche Daten im Datastore absichert.
• Ein Restore setzt die Cluster-Mitgliedschaft zurück; teste ihn daher zuerst in einer passenden Umgebung.

Wann ist ein K3s Backup mit etcd-Snapshot richtig?

Ein K3s Backup per Snapshot ist der vorgesehene Weg, wenn dein K3s-Server den eingebetteten etcd-Datastore nutzt. K3s speichert dabei den Zustand des Datastores. Damit sicherst du Kubernetes-Objekte und die darin liegenden Daten, die etcd verwaltet.

Prüfe zuerst den Datastore-Typ. Laut der K3s-Dokumentation zu Backup und Restore wird SQLite anders behandelt: Dort sicherst du das Verzeichnis /var/lib/rancher/k3s/server/db/. Bei einer externen Datenbank liegt Backup und Wiederherstellung dagegen bei deren Betrieb. Ein etcd-Snapshot ist deshalb kein universeller Ersatz für jedes K3s-Setup.

Auch Persistenzdaten deiner Anwendungen sind ein eigener Baustein. Ein Snapshot ersetzt weder ein Backup von Daten in Persistent Volumes noch die Wiederherstellungsplanung für externe Dienste. Für die Überwachung des Clusters kannst du außerdem Kubernetes-Monitoring mit Grafana und Prometheus einsetzen.

Wie erstellst und prüfst du ein K3s Backup?

Erstelle zunächst einen manuellen Snapshot. Das ist sinnvoll vor einem Upgrade oder einer größeren Änderung. Der Befehl stammt aus der offiziellen K3s-Referenz für etcd-Snapshots:

k3s etcd-snapshot save

Danach listest du die für diesen Node sichtbaren Snapshots auf. So siehst du Namen, Speicherort und Erstellungszeit, statt dich allein auf einen erfolgreichen Cron-Lauf zu verlassen.

k3s etcd-snapshot ls

Geplante Snapshots sind bei K3s standardmäßig aktiv. Sie laufen laut Dokumentation um 00:00 und 12:00 Uhr der Systemzeit. Lokal bewahrt K3s fünf Snapshots je Server-Node auf. Der Standardpfad ist ${data-dir}/db/snapshots; mit dem Standard-Data-Dir entspricht das /var/lib/rancher/k3s/server/db/snapshots.

Manuell erzeugte Snapshots beginnen standardmäßig mit on-demand. Für sie gibt es keine automatische Aufbewahrung. Begrenze sie daher bewusst, zum Beispiel auf sieben Exemplare:

k3s etcd-snapshot prune --snapshot-retention 7

Das Kommando bereinigt On-demand-Snapshots anhand ihres Namenspräfixes. Geplante Snapshots steuerst du dagegen über --etcd-snapshot-retention. Dadurch vermeidest du, dass ein selten benutzter manueller Sicherungslauf still Speicherplatz belegt.

Warum sollte das K3s Backup außerhalb des Nodes liegen?

Lokale Snapshots helfen nicht, wenn der Server oder sein Datenträger ausfällt. K3s kann etcd-Snapshots deshalb in einen S3-kompatiblen Object Store replizieren und von dort wiederherstellen. Aktiviere dafür in der Server-Konfiguration --etcd-s3 und hinterlege Endpoint, Bucket und gegebenenfalls Region passend zu deinem Speicher.

Lege Zugangsdaten nicht unüberlegt in Befehlszeilen oder Konfigurationsdateien ab. Die K3s-Dokumentation unterstützt stattdessen ein Secret im Namespace kube-system: Starte K3s mit --etcd-s3 und --etcd-s3-config-secret=<SECRET-NAME>. Bei einem Restore steht der API-Server jedoch nicht zur Verfügung. Deshalb kann dieses Secret beim Wiederherstellen nicht genutzt werden; die S3-Konfiguration muss dann über die Kommandozeile bereitstehen.

Beachte außerdem die unterschiedliche Aufbewahrung. Lokal gilt --etcd-snapshot-retention pro Server-Node. --etcd-s3-retention gilt dagegen clusterweit für Bucket und Präfix. Bei mehreren etcd-Servern musst du den Wert deshalb für die gewünschte Zahl an Sicherungszyklen dimensionieren. Die K3s-Referenz nennt als Faustformel: Anzahl der etcd-Nodes mal gewünschte Zyklen.

Was musst du zusätzlich zum Snapshot sichern?

Sichere den Server-Token getrennt und geschützt. K3s weist ausdrücklich darauf hin, dass die Datei /var/lib/rancher/k3s/server/token beim Wiederherstellen nötig ist. Ohne denselben Token kann ein Snapshot unbrauchbar sein, weil der Token die vertraulichen Daten im Datastore absichert.

Behandle Snapshot und Token wie besonders schützenswerte Zugangsdaten. Laut K3s enthalten Snapshots die Cluster-CA-Zertifikate und private Schlüssel. Wenn Secret-Verschlüsselung aktiv ist, enthalten sie zudem deren Konfiguration und Schlüssel. Ein Object Store braucht also eng begrenzte Berechtigungen, Verschlüsselung und eine nachvollziehbare Aufbewahrung.

Dokumentiere daneben deine Anwendungskonfiguration und die Datenstrategie für Volumes. Wer Anwendungen von Compose nach Kubernetes überführt hat, findet dazu auch die Anleitung zur Migration von Docker Compose zu Kubernetes. Helm-Releases lassen sich zusätzlich über Helm Charts nachvollziehbar verwalten; das ersetzt den etcd-Snapshot aber nicht.

Wie läuft die Wiederherstellung eines einzelnen K3s-Servers ab?

Ein Restore stellt nicht nur Daten zurück, sondern setzt auch die etcd-Cluster-Mitgliedschaft zurück. Führe ihn deshalb nur mit einem geprüften Snapshot und einem dokumentierten Wartungsfenster aus. Für einen einzelnen Server beschreibt K3s diese Reihenfolge:

1. Stoppe den Dienst: systemctl stop k3s.
2. Starte den Restore mit Reset und dem vollständigen Snapshot-Pfad.
3. Warte auf die K3s-Meldung, dass der Cluster-Reset abgeschlossen ist.
4. Starte K3s ohne Reset-Flag wieder normal.

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

systemctl start k3s

Liegt der Snapshot in S3, gibst du laut K3s die S3-Optionen an und übergibst nur den Dateinamen als Restore-Pfad. Ist S3 in der K3s-Konfiguration aktiv, du willst aber einen lokalen Snapshot nutzen, ergänzt du --etcd-s3=false und übergibst den vollständigen lokalen Pfad.

Bei mehreren Servern stoppst du K3s zuerst auf allen Servern. Den Reset führst du auf dem Server mit dem Snapshot aus. Nach dessen normalem Start sicherst und löschst du auf den übrigen etcd-Servern deren altes Datenbankverzeichnis, bevor sie wieder beitreten. K3s warnt außerdem: Beim Restore auf neue Hosts musst du den ursprünglichen Server-Token mit --token verwenden und alte Node-Objekte bei Bedarf manuell entfernen.

Welche Fehler vermeiden ein K3s Backup nicht?

Ein vorhandener Snapshot ist erst dann ein belastbares K3s Backup, wenn der Wiederherstellungsweg bekannt ist. Teste deshalb regelmäßig, ob Snapshot, Token, S3-Zugriff und die dokumentierte K3s-Version zusammenpassen. K3s erlaubt beim Restore eine höhere Patch- oder Minor-Version, sofern die Kubernetes-Version-Skew-Policy eingehalten wird. Einen Snapshot aus einer älteren K3s-Version, von der du nicht direkt upgraden könntest, sollst du jedoch nicht einspielen.

Prüfe auch die Grenzen deiner eingesetzten Version. Die Option etcd-snapshot-restrictions ist laut K3s ab den Oktober-2026-Releases v1.37.2+k3s1, v1.36.6+k3s1, v1.35.10+k3s1 und v1.34.13+k3s1 verfügbar. Sie kann unter anderem verhindern, dass CLI-Flags Snapshot-Verzeichnis, S3-Endpoint, Bucket oder Ordner überschreiben.

Fazit

Ein K3s Backup mit etcd-Snapshots ist schnell erstellt, aber erst mit einem geschützten Server-Token und einer Kopie außerhalb des Hosts wirklich für den Notfall geeignet. Prüfe geplante und manuelle Snapshots, definiere die Aufbewahrung passend zu deinem Cluster und übe den Restore. So wird aus einem vorhandenen Backup ein nutzbarer Wiederherstellungsplan.

Quellen

• K3s: etcd-Snapshot CLI
• K3s: Backup and Restore
• Kubernetes: Version Skew Policy

Häufige Fragen