Update (2026-09-05): Der Cluster hat Garages Storage inzwischen von Longhorn auf ein statisches, Host-NFS-basiertes PV/PVC-Paar umgezogen. Den Umzug und die Gründe dafür beschreibt ein eigener Artikel (Englisch). Am Velero/Garage-Setup unten (Architektur, replication_factor = 1, das Deployment selbst) ändert das nichts, nur die storageClassName der beiden PVCs ist eine andere.
Jeder Kubernetes-Cluster braucht eine Backup-Strategie. In einem Homelab auf Bare Metal mit Longhorn als verteiltem Storage sind die Optionen überschaubar. etcd-Snapshots sichern den Cluster-Zustand, aber keine Persistent Volumes. MinIO ist das übliche S3-Ziel für Velero, für ein Single-Node-Homelab aber groß, eigenwillig und schlicht überdimensioniert.
Garage ist ein schlanker, quelloffener, S3-kompatibler Object Store in Rust. Er kommt als einzelnes Binary, die Konfiguration ist eine TOML-Datei, und er funktioniert mit jedem S3-Client, auch mit dem AWS-Plugin von Velero. Fürs Homelab passt das deutlich besser als MinIO.
View the complete homelab infrastructure source on GitHub
Die Architektur
🇬🇧 English: Die englische Fassung dieses Artikels: k3s Backup Without the Complexity: Velero + Garage S3 on Longhorn →.
Velero (tägliches Backup um 03:00)
│
├── Cluster-Ressourcen → Garage-S3-Bucket (velero)
│ (Deployments, Services, ConfigMaps, Secrets, CRDs…)
│
└── Persistent Volumes → Volume-Daten
│
└── nach Garage S3 exportiert
Sowohl die Kubernetes-API-Objekte als auch die eigentlichen Volume-Daten landen in Garage. Ein vollständiger Restore stellt den Cluster so wieder her, wie er war.
Schritt 1: Garage auf k3s deployen
Garage braucht zwei Storage-Verzeichnisse: eins für Metadaten (klein, schnell) und eins für die Objektdaten (größer). Zwei getrennte Longhorn-PVCs halten sie auf verschiedenen Volumes.
# kubernetes/apps/garage/pvc.yaml
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
name: garage-data
namespace: apps
spec:
accessModes:
- ReadWriteOnce
storageClassName: longhorn
resources:
requests:
storage: 10Gi
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
name: garage-meta
namespace: apps
spec:
accessModes:
- ReadWriteOnce
storageClassName: longhorn
resources:
requests:
storage: 2Gi
Die Garage-Konfiguration liegt in einer ConfigMap:
# kubernetes/apps/garage/configmap.yaml
apiVersion: v1
kind: ConfigMap
metadata:
name: garage-config
namespace: apps
data:
config.toml: |
metadata_dir = "/var/lib/garage/meta"
data_dir = "/var/lib/garage/data"
db_engine = "lmdb"
replication_factor = 1 # single node, no replication
rpc_bind_addr = "[::]:3901"
rpc_public_addr = "127.0.0.1:3901"
rpc_secret_file = "/etc/garage/secrets/rpc_secret"
[s3_api]
s3_region = "homelab"
api_bind_addr = "[::]:3900"
root_domain = ".s3.yourdomain.com"
[admin]
admin_bind_addr = "[::]:3903"
admin_token_file = "/etc/garage/secrets/admin_token"
replication_factor = 1 ist für ein Single-Node-Setup richtig. Garage kann über mehrere Nodes replizieren, das braucht es hier aber nicht: Die Redundanz übernimmt Longhorn auf der Storage-Ebene.
RPC-Secret und Admin-Token kommen aus einem Kubernetes-Secret:
# kubernetes/apps/garage/secrets.yaml
apiVersion: v1
kind: Secret
metadata:
name: garage-secrets
namespace: apps
type: Opaque
stringData:
rpc_secret: "<64-char-hex-string>"
admin_token: "<random-token>"
Erzeugen lassen sich beide mit openssl rand -hex 32. Deployment und Service sind in der englischen Fassung vollständig abgedruckt: eine Replica mit dem Image dxflrs/garage:v2.3.0, die Konfiguration per subPath nach /etc/garage.toml gemountet, die Secrets mit defaultMode: 0600, dazu ein Service für die Ports 3900 (S3) und 3903 (Admin).
Schritt 2: Den Garage-Cluster initialisieren
Sobald der Pod läuft, braucht Garage eine einmalige Initialisierung. Zuerst die Node-ID holen:
kubectl exec -it -n apps deploy/garage -- /garage status
Dann das Layout zuweisen und anwenden:
# Replace <node-id> with the ID from the status output
kubectl exec -it -n apps deploy/garage -- \
/garage layout assign -z homelab -c 1G <node-id>
kubectl exec -it -n apps deploy/garage -- \
/garage layout apply --version 1
Bucket und Zugangsdaten für Velero anlegen:
kubectl exec -it -n apps deploy/garage -- \
/garage bucket create velero
kubectl exec -it -n apps deploy/garage -- \
/garage key create velero-key
# Grant the key access to the bucket
kubectl exec -it -n apps deploy/garage -- \
/garage bucket allow velero --read --write --owner --key velero-key
Key ID und Secret key aus der Ausgabe notieren, Velero braucht beide.
Schritt 3: Velero per ArgoCD deployen
Velero läuft als Helm-Chart, das AWS-Plugin zeigt auf den S3-Endpunkt von Garage. Die komplette ArgoCD-Application steht in der englischen Fassung, die entscheidenden Werte sind diese:
configuration:
backupStorageLocation:
- name: default
provider: aws
bucket: velero
default: true
config:
region: homelab
s3ForcePathStyle: true
s3Url: http://garage.apps.svc.cluster.local:3900
credentials:
useSecret: true
existingSecret: velero-s3-credentials
snapshotsEnabled: true
deployNodeAgent: true
Zwei Einstellungen sind wichtig:
s3ForcePathStyle: true: Velero spricht Garage mit Path-Style-URLs an (http://endpoint/bucket/key), nicht im Virtual-Hosted-Style (http://bucket.endpoint/key). Virtual-Hosted-Anfragen bedient Garage nur unter seiner root_domain, und der clusterinterne Service-Name garage.apps.svc.cluster.local hat kein DNS pro Bucket. Ohne das Flag baut das AWS-SDK Hostnamen wie velero.garage.apps..., die nie auflösen.
deployNodeAgent: true: Der Node Agent läuft als DaemonSet und schiebt die PVC-Daten ins Backup-Ziel, entweder als File-System-Backup (Kopia) oder per CSI-Snapshot-Data-Movement. Ohne ihn sichert Velero zwar die Kubernetes-Objekte, aber nicht die Daten in den PVCs.
Das Secret mit den Zugangsdaten:
# kubernetes/system/velero/secrets.yaml
apiVersion: v1
kind: Secret
metadata:
name: velero-s3-credentials
namespace: velero
type: Opaque
stringData:
cloud: |
[default]
aws_access_key_id = <your-garage-key-id>
aws_secret_access_key = <your-garage-secret-key>
Schritt 4: Täglicher Backup-Schedule
# kubernetes/system/velero/schedule.yaml
apiVersion: velero.io/v1
kind: Schedule
metadata:
name: daily-backup
namespace: velero
spec:
schedule: "0 3 * * *" # 03:00 every night
template:
ttl: 720h0m0s # keep backups for 30 days
includedNamespaces:
- "*"
excludedNamespaces:
- kube-system
- kube-public
- kube-node-lease
storageLocation: default
volumeSnapshotLocations:
- default
Das ergibt 30 Tage tägliche Backups. Über die TTL löscht Velero Backups, die älter als 720 Stunden sind, selbst. Manuelles Aufräumen entfällt.
Backups prüfen
Landen die Backups wirklich in Garage?
# List backups
kubectl get backups -n velero
# Describe a specific backup
kubectl describe backup -n velero daily-backup-<timestamp>
# Trigger a manual backup
velero backup create manual-test --include-namespaces apps
Ob Garage die Daten tatsächlich bekommt, zeigt die Bucket-Größe:
kubectl exec -it -n apps deploy/garage -- \
/garage bucket info velero
Restore
# List available backups
velero backup get
# Restore everything
velero restore create --from-backup daily-backup-<timestamp>
# Restore a single namespace
velero restore create --from-backup daily-backup-<timestamp> \
--include-namespaces apps
Velero legt PVCs und PVs neu an, der Node Agent spielt die Daten zurück, und die Workloads starten mit den wiederhergestellten PVCs.
Warum Garage statt MinIO
| Garage | MinIO | |
|---|---|---|
| Binary-Größe | ~50MB | ~400MB |
| Speicher (idle) | ~20MB | ~200MB+ |
| Konfiguration | Eine TOML-Datei | Env-Variablen + Web-UI |
| S3-Kompatibilität | Voll (Path-Style) | Voll |
| Cluster-Modus | Optional | Erfordert verteiltes Setup |
Als Velero-Ziel im Homelab kann Garage alles, was MinIO kann, bei einem Bruchteil des Ressourcenbedarfs. Verzichten muss man nur auf die MinIO-Webkonsole, und garage bucket info plus garage key list decken auf der CLI alles Nötige ab.
Mit diesem Setup dauert ein kompletter Neuaufbau des Clusters (frische k3s-Installation, ArgoCD, dann velero restore) unter 30 Minuten. Erst dieser Neuaufbau zeigt, ob die Backup-Strategie funktioniert. Ich habe genau diesen Test (Englisch) auf einer Wegwerf-VM durchgespielt und dabei einen Netzwerkkonflikt gefunden, den keine Dokumentation erwähnt.
Ein „Completed” in velero backup get beweist dabei noch nichts. Wie mein tägliches Backup wochenlang erfolgreich meldete, ohne je PVC-Daten zu enthalten, steht in Velero Said Backups Succeeded. The Data Was Never There. (Englisch).