Garage - S3-kompatibler Objekt-Speicher Schnellstart

Garage in Docker in Minuten ausführen

Inhaltsverzeichnis

Garage ist ein Open-Source, selbstgehosteter, S3-kompatibler Objektspeicher, der für kleine bis mittlere Bereitstellungen konzipiert ist, mit einem starken Fokus auf Resilienz und geografische Verteilung.

Dieser Quickstart führt Sie von einer einfachen Einzelknoten-Setup über Kopieren/Pasten bis hin zu produktionsreifen Mustern: Cluster-Layout, Replikation, TLS über Reverse-Proxy, mehrere Festplatten-Speicher-Backends, Monitoring, Reparaturen und Backup/Wiederherstellung.

Für den umfassenden Überblick – Objektspeicher, PostgreSQL, Elasticsearch und AI-native Datenlagen – siehe den Artikel Data Infrastructure for AI Systems.

Garage Boxes

Was Garage ist

Garage ist ein S3-kompatibler verteilter Objektspeicher, der für Selbsthosting konzipiert ist, mit dem Ziel, leichtgewichtig und einfach zu betreiben zu sein, während er Multi-Site/geo-verteilte Cluster unterstützt.
Er wird unter der AGPL v3 Lizenz veröffentlicht.

Zentrale Ideen, die bestimmen, wie Sie ihn betreiben:

Garage misst die Knotenkapazität und die physische Lage (“Zonen”), um Replikate zu platzieren; Änderungen im Cluster-Topology (Hinzufügen/Entfernen von Knoten) werden über versionierte Layouts und Rebalancing behandelt.
Objekte werden in festgrößige Blöcke (block_size) unterteilt, was Deduplizierung und optional Zstandard-Kompression ermöglicht; Block-Hashes werden zur Platzierung und Deduplizierung verwendet.
Garage terminiert TLS nicht an seinen S3 API/Web-Endpunkten: In realen Bereitstellungen erwarten Sie, einen Reverse-Proxy für HTTPS zu deployen.

Architektur und Datenfluss

Auf der obersten Ebene interagieren Sie mit Garage über S3-kompatible Clients; der Datenverkehr kommt typischerweise über einen Reverse-Proxy (TLS), erreicht einen oder mehrere Garage API-Endpunkte (häufig “Gateway”-Knoten) und wird dann von Speicherknoten bereitgestellt, die replizierte Datenblöcke halten.

garage-Cluster-Datenfluss

Knoten haben Rollen: Speicherknoten mit Kapazität vs. Gateway-Knoten, die Endpunkte exponieren, ohne Daten zu speichern; Gateways reduzieren Latenz, indem sie zusätzliche Netzwerkwege vermeiden und wissen, welche Speicherknoten abgefragt werden sollen.
Replikation wird über replication_factor gesteuert (z. B. 3-fache Replikation über Zonen), mit klaren Verfügbarkeits-/Fehlertoleranz-Handelsabwägungen, die im Konfigurationsreferenz beschrieben werden.

Copy/paste Quickstart

Dies ist eine absichtlich minimale Einzelknoten-Bereitstellung zum Lernen der Workflows: Konfiguration → Server starten → Layout definieren → Bucket + Schlüssel erstellen → Objekt hochladen.

Voraussetzungen

Sie benötigen docker, openssl und (optional) einen S3-Client wie awscli. Garage CLI ist dieselbe Binärdatei, die zur Verwaltung des Clusters verwendet wird.

Schritt für Schritt

# 0) Arbeitsbereich
mkdir -p ~/garage-quickstart/{config,meta,data}
cd ~/garage-quickstart

# 1) Erstellen Sie eine Starter-Konfiguration (persistente Pfade innerhalb des Containers)
cat > ./config/garage.toml <<EOF
metadata_dir = "/var/lib/garage/meta"
data_dir     = "/var/lib/garage/data"
db_engine = "sqlite"

# Einzelknoten-Lernbereitstellung (KEINE Redundanz). Für Produktion siehe später.
replication_factor = 1

rpc_bind_addr   = "[::]:3901"
rpc_public_addr = "127.0.0.1:3901"
rpc_secret      = "$(openssl rand -hex 32)"

[s3_api]
s3_region = "garage"
api_bind_addr = "[::]:3900"
# Optional vhost-style. Path-style ist immer aktiviert.
root_domain = ".s3.garage.localhost"

[s3_web]
bind_addr = "[::]:3902"
root_domain = ".web.garage.localhost"
index = "index.html"

[admin]
api_bind_addr = "[::]:3903"
admin_token   = "$(openssl rand -base64 32)"
metrics_token = "$(openssl rand -base64 32)"
EOF

# 2) Wählen Sie ein Image-Tag (Platzhalter). Beispiel-Tags finden Sie in den Garage-Dokumentationen.
GARAGE_IMAGE="dxflrs/garage:TAG_PLACEHOLDER"

# 3) Führen Sie Garage (Docker) aus
docker run -d --name garaged \
  -p 3900:3900 -p 3901:3901 -p 3902:3902 -p 3903:3903 \
  -v "$PWD/config/garage.toml:/etc/garage.toml:ro" \
  -v "$PWD/meta:/var/lib/garage/meta" \
  -v "$PWD/data:/var/lib/garage/data" \
  "$GARAGE_IMAGE"

# 4) Verwenden Sie den garage CLI innerhalb des Containers
alias garage='docker exec -ti garaged /garage'

# 5) Prüfen Sie den Knotenstatus (Sie werden wahrscheinlich "NO ROLE ASSIGNED" sehen)
garage status

# 6) Weisen Sie ein Layout (Einzelknoten) zu und wenden Sie es an
NODE_ID="$(garage status | awk '/NO ROLE ASSIGNED/{print $1; exit}')"
garage layout assign -z dc1 -c 1G "$NODE_ID"
garage layout apply --version 1

# 7) Erstellen Sie einen Bucket + Schlüssel und gewähren Sie minimale Berechtigungen
garage bucket create example-bucket
garage key create example-app-key
garage bucket allow --read --write --owner example-bucket --key example-app-key

# 8) Zeigen Sie das Schlüsselmaterial an (sichern Sie es sicher)
garage key info example-app-key

Das Konfigurationsmuster (S3 API auf 3900, RPC auf 3901, Web-Endpunkt auf 3902, Admin API auf 3903) und der „Layout erforderlich“-Workflow stammen direkt aus dem upstream Quickstart.

Validierung mit AWS CLI

Garage erfordert, dass Clients den konfigurierten s3_region (oft „garage“) verwenden; wenn Ihr Client „us-east-1“ verwendet, können Sie Umleitungen zu AuthorizationHeaderMalformed erhalten.

# Installieren (eine Option)
python -m pip install --user awscli

# Umgebung konfigurieren (Beispiel)
export AWS_ACCESS_KEY_ID="YOUR_GARAGE_KEY_ID"
export AWS_SECRET_ACCESS_KEY="YOUR_GARAGE_SECRET_KEY"
export AWS_DEFAULT_REGION="garage"
export AWS_ENDPOINT_URL="http://localhost:3900"

aws s3 ls
aws s3 cp /etc/hosts s3://example-bucket/hosts.txt
aws s3 ls s3://example-bucket/
aws s3 cp s3://example-bucket/hosts.txt /tmp/hosts.txt

Der upstream Quickstart empfiehlt, eine ~/.awsrc-Datei zu verwenden, um zwischen Endpunkten/Schlüsseln zu wechseln, und erwähnt die minimalen AWS CLI-Versionen für bequeme Endpunktverwaltung.

Installation und Bereitstellungsoptionen

Binärinstallations- und Pakete

Die Garage-Dokumentation unterstützt explizit: Herunterladen von Binärdateien von der Garage-Downloadseite, Verwenden von Distro-Paketen (z. B. apk add garage auf Alpine) oder Erstellen aus der Quelle, falls erforderlich.

Docker und Docker Compose

Garage bietet Container-Images und dokumentiert eine minimale docker run-Methode für den Quickstart.
Für Produktion verwenden Sie typischerweise Compose (oder einen Orchestrator), um persistente Speicherung, Reverse-Proxy und Upgrades (rolling Restarts) zu verwalten. Der Garage-„Deployment on a Cluster“-Leitfaden setzt Docker auf jedem Knoten voraus und weist auf die gängigen Host-Pfade und SSD-Empfehlung für Metadaten hin.

systemd

Garage dokumentiert eine verstärkte systemd-Bereitstellung, einschließlich Warnungen in Bezug auf systemd’s DynamicUser= und wo persistenter Zustand auf dem Datenträger endet.
Ein minimales Einheitsbeispiel (anpassen Sie die Pfade an Ihre Umgebung):

# /etc/systemd/system/garage.service
[Unit]
Description=Garage S3-kompatibler Objektspeicher
After=network.target

[Service]
ExecStart=/usr/local/bin/garage -c /etc/garage.toml server
Restart=on-failure
Environment=RUST_LOG=garage=info

[Install]
WantedBy=multi-user.target

Kubernetes und Helm

Garage liefert einen Helm-Chart im Repo und hat offizielle Dokumentationsseiten für Kubernetes-Bereitstellung.
Ein häufiger Stolperstein ist, dass Sie nach der Installation immer noch ein Cluster-Layout bootstrappen/applyen müssen (Sie können dies mit einem Kubernetes-Job automatisieren).

Konfiguration, Sicherheit und TLS

Speicher-Backends und Festplattenlayout

Garage teilt den Speicher in metadata_dir und data_dir auf. Die Konfigurationsreferenz empfiehlt, metadata_dir auf einen schnellen SSD zu platzieren, um die Reaktionszeiten zu verbessern, während data_dir auf größeren HDDs sitzen kann.
Für Knoten mit mehreren Datenfestplatten unterstützt Garage eine multi-disk data_dir-Konfiguration mit Kapazitäten pro Pfad und automatischem Ausgleichen.

# Beispiel: mehrere HDDs für Datenblöcke
metadata_dir = "/mnt/ssd/garage-meta"
data_dir = [
  { path = "/mnt/hdd1/garage-data", capacity = "8T" },
  { path = "/mnt/hdd2/garage-data", capacity = "8T" },
]

Zugriffssteuerungsmodell vs. S3-Bucket-Policies

Garage implementiert keine AWS-stilisierten ACLs oder Bucket-Policies; es verwendet ein eigenes „pro Zugriffsschlüssel pro Bucket“-Berechtigungssystem, das über die Garage CLI / Admin API verwaltet wird.
Das bedeutet, dass die „Policy“, die Sie normalerweise in Garage übersetzen, lautet: Welcher Zugriffsschlüssel hat Lese-/Schreib-/Besitzrechte auf welchem Bucket(s).

# Leseschlüssel für einen Bucket:
garage key create ro-key
garage bucket allow --read example-bucket --key ro-key

# Zugriff entfernen:
garage bucket deny example-bucket --key ro-key

DNS-Stil vs. Pfadstil für Bucket-Adressierung

Garage kann virtuell-host (DNS) Stil-Bucketzugriff unterstützen, wenn Sie [s3_api].root_domain konfigurieren; Pfadstil ist immer aktiviert.
Wenn Sie vhost-Stil nicht einrichten (Wildcard DNS + möglicherweise Wildcard TLS), können viele Clients durch Erzwingen von Pfadstil funktionieren, und die Garage-Dokumentation zeigt Clientbeispiele mit force_path_style = true.

TLS

Garage’s S3 API und Web-Endpunkte unterstützen kein TLS direkt; die offizielle Empfehlung ist, einen Reverse-Proxy vorzusehen, häufig Nginx, um HTTPS zu liefern und Dienste auf Port 443 zu multiplexen.

Ein minimales Nginx-„Shape“ (siehe den offiziellen Reverse-Proxy-Kochbuch für ein vollständiges Beispiel):

# /etc/nginx/sites-available/garage.conf (Auszug)
upstream garage_s3 { server 127.0.0.1:3900; }

server {
  listen 443 ssl;
  server_name garage.example.com;

  ssl_certificate     /etc/letsencrypt/live/garage.example.com/fullchain.pem;
  ssl_certificate_key /etc/letsencrypt/live/garage.example.com/privkey.pem;

  location / {
    proxy_pass http://garage_s3;
    proxy_set_header Host $host;
  }
}

Serverseitige Verschlüsselung

Garage unterstützt S3 SSE-C („serverseitige Verschlüsselung mit vom Kunden bereitgestellten Schlüsseln“): Der Client sendet Verschlüsselungsschlüssel in den Header pro Anfrage; Garage verschlüsselt und verwirft den Schlüssel nach der Anfrage.
Garage’s S3-Verträglichkeitstabelle erwähnt auch, dass Endpunkte für Bucketaufschichtverschlüsselungskonfiguration nicht implementiert sind, also behandeln Sie SSE-C als per-Objekt/Anfrage-Verhalten anstelle von Bucketausgangsstandards.

Garage in Produktion betreiben

Monitoring und Logging

Garage stellt Metriken im Prometheus-Format bereit und unterstützt das Exportieren von Traces im OpenTelemetry-Format.
Admin- und Metrics-Endpunkte können durch Tokens (admin_token, metrics_token und metrics_require_token) geschützt werden, und Tracing kann über trace_sink (OTLP) exportiert werden.
Für Logging kann Garage über RUST_LOG abgestimmt werden, und die Konfigurationsreferenz dokumentiert Umgebungsvariablen, um Logs an syslog/journald anstelle von stderr zu senden.

Dauerhaftigkeit, Reparaturen und gängige Wartungsaufgaben

Garage beinhaltet Hintergrund-„scrub“ (Integritätsprüfung) und Reparaturwerkzeuge; Scrubs können manuell gestartet und über Worker/Task-Befehle überwacht werden, sind aber diskintensiv und können den Cluster verlangsamen.
Topologieänderungen und Kapazitätsanpassungen werden über Layout-Management behandelt; Operationen werden als neue Layoutversionen angewendet.

Backup- und Wiederherstellungstrategie

Mindestens das Metadata muss gesichert werden, da es den Clusterkonfiguration, Bucket/Schlüsselstatus und Indizes enthält. Garage unterstützt periodische Metadata-Snapshots (metadata_auto_snapshot_interval) und manuelle Snapshots (garage meta snapshot --all).
Der Garage-Migration-Leitfaden empfiehlt explizit, bestimmte Dateien/Verzeichnisse aus jedem Knotens metadata_dir (einschließlich Snapshots und Layoutdateien) zu sichern.

Für Objektdaten behandeln Sie Garage wie jeden S3-Endpunkt: Verwenden Sie S3-kompatible Backup-Tools (z. B. restic, duplicity), die auf einen Garage-Bucket abzielen, wie in der Garage-„Backups“-Integrationseite dokumentiert.

Fehlerbehebung bei häufigen Fehlern

NO ROLE ASSIGNED in garage status bedeutet in der Regel, dass Sie noch keine Layout erstellt/angewendet haben. Lösung: garage layout assign … und dann garage layout apply.
AuthorizationHeaderMalformed weist häufig darauf hin, dass ein Client die falsche Region verwendet; setzen Sie AWS_DEFAULT_REGION (oder Äquivalent) so ein, dass er mit [s3_api].s3_region übereinstimmt.
Signatur-/Anfragefehler können durch einen Konflikt zwischen Pfadstil und vhost-Stil verursacht werden; konfigurieren Sie [s3_api].root_domain für vhost-Stil, oder erzwingen Sie Pfadstil in Clients (z. B. force_path_style=true bei rclone).
Berechtigungsfehler sind häufig einfach „Schlüssel nicht auf Bucket erlaubt“; prüfen Sie mit garage bucket info <bucket> und stellen Sie sicher, dass garage bucket allow die richtigen Flags hat.

Leistungsoptimierungen, die am wichtigsten sind

Wenn möglich, platzieren Sie metadata_dir auf einem SSD; die Garage-Dokumentation weist auf verbesserte Reaktionszeiten und „drastisch reduzierte“ Latenzpotential hin.
Stellen Sie block_size und Kompression sorgfältig ein: Die Standardwerte von Garage sind so konzipiert, um sinnvoll zu sein, aber die Konfigurationsreferenz erklärt den Trade-off und erwähnt, dass Änderungen nur auf neu hochgeladene Daten anwenden.
Wenn Sie NVMe verwenden, kann die Erhöhung der Block-Schreibkonkurrenz die Durchsatzmenge verbessern, erhöht aber den Speicherverbrauch; Garage bietet Anleitungen für block_max_concurrent_writes_per_request.
Die eigenen Benchmarks von Garage betonen die Kosten der Intra-Cluster-Latenz in geo-verteilten Einrichtungen und betonen Designentscheidungen (z. B. Vermeidung von Konsensleitern), die den Einfluss der geo-Latenz reduzieren können.

Kurze Vergleichsanalyse mit MinIO und AWS S3

Garage ist für selbstgehostete, geo-verteilte Cluster und operativen Einfachheit optimiert, mit bewussten S3-Funktionslücken (z. B. keine S3-Bucket-Policies/ACLs; begrenzte Versionierungssupport).
MinIO konzentriert sich auf die Breite der S3-API und hochleistungsfähige Unternehmensbereitstellungen (z. B. beschreibt die eigene Dokumentation von MinIO Features wie Objekt-Sperre, Replikation und Ereigniserkennung).
AWS S3 ist die verwaltete Referenzimplementierung mit starker Konsistenz, 11 nines Dauerhaftigkeit und 99,99 % Verfügbarkeit, und einem breiten Funktionsökosystem (Speicherklassen, Lebenszyklus, Ereignisse, IAM).

Mehr über MinIO: