Garage - S3-kompatible Objektstorage Quickstart

Garage in Docker in Minuten laufen lassen

Inhaltsverzeichnis

Garage ist ein quelloffenes, selbstgehostetes, S3-kompatibles Objekt-Speichersystem, das für kleine bis mittlere Bereitstellungen konzipiert wurde, mit einem starken Fokus auf Ausfallsicherheit und geografische Verteilung.

Dieser Quickstart führt Sie von einer einfachen Kopie/Paste-Einzelknoten-Bereitstellung zu produktionsreifen Mustern: Cluster-Layout, Replikation, TLS über Reverse Proxy, mehrere Festplatten-Speicher-Backends, Überwachung, Reparatur und Backup/Wiederherstellung.

Für den breiteren Überblick – Objekt-Speicher, PostgreSQL, Elasticsearch und AI-native Daten-Schichten – siehe den Artikel Data Infrastructure for AI Systems.

Garage Boxes

Was Garage ist

Garage ist ein S3-kompatibler verteilter Objekt-Speicher, der für die Selbst-Hosting konzipiert wurde, mit dem Ziel, leichtgewichtig und einfach zu betreiben zu sein, während er Unterstützung für mehrere Standorte/geografisch verteilte Cluster bietet.
Es wird unter der AGPL v3 Lizenz veröffentlicht.

Schlüsselideen, die bestimmen, wie Sie es betreiben:

Garage misst die Kapazität der Knoten und ihre physische Lage (“Zonen”), um Replikate zu platzieren; Änderungen im Cluster-Topologie (Hinzufügen/Entfernen von Knoten) werden über versionierte Layouts und Rebalancing behandelt.
Objekte werden in Blöcke fester Größe (block_size) unterteilt, was Deduplizierung und optionalen Zstandard-Compression ermöglicht; Block-Hashes werden für die Platzierung und Deduplizierung verwendet.
Garage terminiert TLS nicht an seinen S3-API/Web-Endpunkten: in echten 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 gelangt typischerweise über einen Reverse Proxy (TLS), erreicht einen oder mehrere Garage API-Endpunkte (häufig “Gateway”-Knoten) und wird dann von Speicherknoten bedient, die replizierte Datenblöcke halten.

garage- cluster data flow

Knoten haben Rollen: Speicherknoten mit Kapazität vs. Gateway-Knoten, die Endpunkte ohne Daten zu speichern exponieren; Gateways reduzieren Latenz, indem sie zusätzliche Netzwerk-Hops 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-Kompromissen, die im Konfigurationsreferenz beschrieben werden.

Copy/paste Quickstart

Dies ist absichtlich minimal 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. Garages CLI ist die gleiche 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 Startkonfiguration (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-stil. Path-stil 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 Bildtag (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 den Schlüsselinhalt an (sichern Sie ihn 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 von Clients, die konfigurierte s3_region (häufig „garage“) zu 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 die Verwendung einer ~/.awsrc-Datei, um zwischen Endpunkten/Schlüsseln zu wechseln und erwähnt die Mindestversionen des AWS CLI für eine bequeme Endpunktverwaltung.

Installations- und Bereitstellungsoptionen

Binärinstallationen und Pakete

Die Garage-Dokumentation unterstützt explizit: Herunterladen von Binärbefehlen von der Garage-Downloadseite, Verwendung von Distro-Paketen (z. B. apk add garage auf Alpine) oder Bau aus der Quelle, wenn nötig.

Docker und Docker Compose

Garage stellt Container-Images bereit und dokumentiert eine minimale docker run-Methode für Quickstart-Zwecke.
Für Produktion verwenden Sie typischerweise Compose (oder einen Orchestrierer), um persistenten Speicher, Reverse Proxy und Upgrades (rolling Restarts) zu verwalten. Die Garage-„Bereitstellung auf einem Cluster“-Anleitung setzt Docker auf jedem Knoten voraus und weist auf die gängigen Hostpfade und SSD-Empfehlung für Metadaten hin.

systemd

Garage dokumentiert eine verstärkte systemd-Bereitstellung, einschließlich Hinweisen zu systemd’s DynamicUser= und wo persistenter Zustand auf der Festplatte endet.
Ein minimales Einheitsexemplar (Pfade anpassen):

# /etc/systemd/system/garage.service
[Unit]
Description=Garage S3-kompatibler Objekt-Speicher
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 Fehler 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 Festplatten-Layout

Garage teilt den Speicher in metadata_dir und data_dir auf. Die Konfigurationsreferenz empfiehlt, metadata_dir auf einem schnellen SSD zu platzieren, um die Antwortzeiten zu verbessern, während data_dir auf einem größeren HDD liegen kann.
Für Knoten mit mehreren Datenspeicherlaufwerken unterstützt Garage eine mehrfache Festplattenkonfiguration für data_dir 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-Policen

Garage implementiert keine AWS-stiligen ACLs oder Bucket-Policen; es verwendet sein 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).

# Lesenur-Schlü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-stilige vs. Pfadstilige Bucket-Adressierung

Garage kann virtuelle-Host (DNS)-stilige Bucket-Adressierung 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 des Pfadstils funktionieren, und die Garage-Dokumentation zeigt Client-Beispiele mit force_path_style = true.

TLS

Garages S3-API und Web-Endpunkte unterstützen kein TLS direkt; die offizielle Anleitung empfiehlt, einen Reverse Proxy vorzusehen, häufig Nginx, um HTTPS zu servieren und Dienste auf Port 443 zu multiplexen.

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

# /etc/nginx/sites-available/garage.conf (Excerpt)
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 Header pro Anfrage; Garage verschlüsselt im Ruhezustand und verwirft den Schlüssel nach der Anfrage.
Garages S3-Kompatibilitäts-Tabelle erwähnt auch, dass Endpunkte für Bucketaufschichtverschlüsselungskonfiguration nicht implementiert sind, also behandeln Sie SSE-C als pro Objekt/Anfrage Verhalten anstelle von Bucketausgangsstandards.

Garage in Produktion betreiben

Überwachung und Logging

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

Ausfallsicherheit, Reparatur und gängige Wartungsaufgaben

Garage beinhaltet Hintergrund-„scrub“ (Integritätsprüfung) und Reparatur-Tools; 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-Verwaltung behandelt; Operationen werden als neue Layoutversionen angewendet.

Backup- und Wiederherstellungstrategie

Mindestens Metadaten sollten gesichert werden, da sie den Clusterkonfiguration, Bucket/Key-Zustand und Indizes enthalten. Garage unterstützt periodische Metadatensnapshots (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 Layout-Dateien) 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.

Lösung von häufigen Fehlern

NO ROLE ASSIGNED in garage status bedeutet normalerweise, dass Sie noch kein Layout erstellt/angewendet haben. Lösung: garage layout assign … dann garage layout apply.
AuthorizationHeaderMalformed deutet oft darauf hin, dass ein Client die falsche Region verwendet; setzen Sie AWS_DEFAULT_REGION (oder Äquivalent) auf [s3_api].s3_region.
Signatur-/Anfragefehler können durch Unterschiede 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. rclone’s force_path_style=true).
Berechtigungsfehler sind häufig einfach „Schlüssel nicht erlaubt auf Bucket“; prüfen Sie mit garage bucket info <bucket> und stellen Sie sicher, dass garage bucket allow die richtigen Flags hat.

Leistungsanpassungshinweise, die am wichtigsten sind

Setzen Sie metadata_dir auf SSD, wenn möglich; die Garage-Dokumentation weist auf verbesserte Antwortzeiten und „drastisch reduzierte“ Latenz hin.
Stellen Sie block_size und Kompression sorgfältig ein: Die Garage-Standardwerte sind vorgesehen, um vernünftig zu sein, aber die Konfigurationsreferenz erklärt den Kompromiss und erwähnt, dass Änderungen nur auf neu hochgeladene Daten angewendet werden.
Wenn Sie NVMe haben, könnte das Erhöhen der Block-Schreibkonkurrenz die Durchsatzrate verbessern, erhöht aber den Speicherverbrauch; Garage bietet Anleitungen für block_max_concurrent_writes_per_request.
Garages eigene Benchmarks betonen die Kosten der intra-Cluster-Latenz in geo-verteilten Setup und betonen Designentscheidungen (z. B. Vermeidung von Konsensführer), die die Auswirkungen der geo-Latenz reduzieren können.

Kurze Vergleichsanalyse mit MinIO und AWS S3

Garage ist optimiert für selbstgehostete, geo-verteilte Cluster und operativen Einfachheit, mit einigen bewussten S3-Funktionslücken (z. B. keine S3-Bucket-Policen/ACLs; begrenzte Versionierungssupport).
MinIO konzentriert sich auf die Breite der S3-API und Hochleistungs-Unternehmensbereitstellungen (z. B. MinIOs eigene Materialien beschreiben Funktionen wie Objekt-Sperre, Replikation und Ereignisbenachrichtigungen).
AWS S3 ist die verwaltete Referenzimplementierung mit starken Konsistenz, 11 nines Ausfallsicherheit und 99,99% Verfügbarkeit, und ein breites Funktionsökosystem (Speicherklassen, Lebenszyklus, Ereignis, IAM).

Für weitere Details siehe Garage vs MinIO vs AWS S3 Vergleich.

Mehr über MinIO: