Garage - S3 compatibele objectopslag Quickstart

Garage in Docker draaien in minuten

Inhoud

Garage is een open-source, zelfgehost, S3-compatibele objectopslag die is ontworpen voor kleine tot middelgrote implementaties, met een sterke nadruk op duurzaamheid en geografische verspreiding.

Deze quickstart leidt je vanaf een eenvoudige copy/paste-standaardconfiguratie naar productie-gerichte patronen: clusteropstelling, replicatie, TLS via reverse proxy, meerdisk opslagbackends, monitoring, reparaties en back-up/restore.

Voor een overzicht van het bredere beeld – objectopslag, PostgreSQL, Elasticsearch en AI-native data layers – zie het artikel Data Infrastructure for AI Systems.

Garage Boxes

Wat Garage is

Garage is een S3-compatibele gedistribueerde objectopslag die is bedoeld voor zelfgehosting, met als doel om lichtgewicht en eenvoudig te blijven terwijl het ondersteuning biedt voor meerdere locaties/geografisch verspreide clusters.
Het wordt vrijgegeven onder de AGPL v3 licentie.

Belangrijke ideeën die bepalen hoe je het moet draaien:

Garage meet knooppuntcapaciteit en fysieke locatie (“zones”) om replicaties te plaatsen; veranderingen in clusteropstelling (toevoegen/verwijderen van knooppunten) worden afgehandeld via versiebeheer en herverdeling.
Objecten worden in vaste grootteblokken (block_size) opgesplitst, wat deduplicatie en optionele Zstandard compressie mogelijk maakt; blokhashes worden gebruikt voor plaatsing en deduplicatie.
Garage beëindigt geen TLS op zijn S3 API/web eindpunten: je wordt verwacht om een reverse proxy in te stellen voor HTTPS in reële implementaties.

Architectuur en dataflow

Op een hoog niveau interactieer je met Garage via S3-compatibele clients; verkeer komt meestal binnen via een reverse proxy (TLS), bereikt één of meer Garage API eindpunten (vaak “gateway” knooppunten), en wordt vervolgens aangeboden door opslagknooppunten die gerepliceerde datablokken bevatten.

garage- cluster data flow

Knooppunten hebben rollen: opslagknooppunten met capaciteit versus gatewayknooppunten die eindpunten blootgeven zonder data op te slaan; gateways verminderen latentie door extra netwerkhops te vermijden en door te weten welke opslagknooppunten ze moeten vragen.
Replicatie wordt beheerd via replication_factor (bijvoorbeeld 3-richting replicatie over zones), met duidelijke beschikbaarheid/fouttolerantie afwegingen beschreven in de configuratieverwijzing.

Copy/paste quickstart

Dit is opzettelijk een minimale één-knooppunt implementatie voor het leren van de workflows: configuratie → server starten → layout definiëren → bucket + sleutel aanmaken → object uploaden.

Voorwaarden

Je hebt docker, openssl en (optioneel) een S3 client zoals awscli nodig. Garage’s CLI is hetzelfde bestand dat wordt gebruikt om het cluster te beheren.

Stap voor stap

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

# 1) Maak een starter configuratie aan (persistentie binnen de container)
cat > ./config/garage.toml <<EOF
metadata_dir = "/var/lib/garage/meta"
data_dir     = "/var/lib/garage/data"
db_engine = "sqlite"

# Één-knooppunt leerimplementatie (GEEN redundantie). Voor productie, zie later.
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"
# Optionele vhost-stijl. Path-stijl is altijd ingeschakeld.
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) Kies een image tag (tijdelijke placeholder). Voorbeelden zijn in de Garage documentatie.
GARAGE_IMAGE="dxflrs/garage:TAG_PLACEHOLDER"

# 3) Start Garage (Docker)
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) Gebruik de garage CLI binnen de container
alias garage='docker exec -ti garaged /garage'

# 5) Controleer knooppuntstatus (je zult waarschijnlijk "NO ROLE ASSIGNED" zien)
garage status

# 6) Toekennen van een layout (één knooppunt) en toepassen
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) Maak een bucket + sleutel en geef minimale bevoegdheden
garage bucket create example-bucket
garage key create example-app-key
garage bucket allow --read --write --owner example-bucket --key example-app-key

# 8) Toon de sleutelgegevens (bewaar deze veilig)
garage key info example-app-key

Het configuratiepatroon (S3 API op 3900, RPC op 3901, web eindpunt op 3902, admin API op 3903) en de “layout vereist” workflow zijn rechtstreeks uit de upstream quickstart.

Valideer met AWS CLI

Garage vereist dat clients de ingestelde s3_region (vaak “garage”) gebruiken; als je client us-east-1 gebruikt, kan je op AuthorizationHeaderMalformed redirects stuiten.

# Installatie (één optie)
python -m pip install --user awscli

# Configuratie van omgeving (voorbeeld)
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

De upstream quickstart raadt aan om een ~/.awsrc bestand te gebruiken om tussen eindpunten/sleutels te schakelen en noemt minimale AWS CLI versies voor handige eindpuntbeheer.

Installatie- en implementatieopties

Binair installeren en pakketten

De Garage documentatie ondersteunt expliciet: het downloaden van binaire bestanden van Garage’s downloadpagina, het gebruik van distro-pakketten (bijvoorbeeld apk add garage op Alpine), of het bouwen vanuit de bron als nodig.

Docker en Docker Compose

Garage biedt containerbeelden en documenteert een minimale docker run methode voor quickstartgebruik.
Voor productie gebruik je meestal compose (of een orchestrator) om persistentie, reverse proxy en upgrades (rolling restarts) te beheren. De Garage “implementatie op een cluster” gids veronderstelt Docker op elk knooppunt en noemt de gebruikelijke hostpaden en SSD aanbeveling voor metadata.

systemd

Garage documenteert een beveiligde systemd-implementatie, inclusief opmerkingen over systemd’s DynamicUser= en waar persistentie op schijf eindigt.
Een minimale eenheidvoorbeeld (pas paden aan naar je omgeving):

# /etc/systemd/system/garage.service
[Unit]
Description=Garage S3-compatibele objectopslag
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 en Helm

Garage levert een Helm chart in de repo en heeft officiële documentatiepagina’s voor Kubernetes-implementatie.
Een veelvoorkomend valkuil is dat je nog steeds een clusterlayout moet bootstrappen/applyen na installatie (je kunt dit automatiseren met een Kubernetes Job).

Configuratie, beveiliging en TLS

Opslagbackends en schijfopstelling

Garage splitst opslag in metadata_dir en data_dir. De configuratieverwijzing raadt aan om metadata_dir op een snelle SSD te plaatsen om responsentijd te verbeteren, terwijl data_dir op een grotere HDD kan zitten.
Voor knooppunten met meerdere data-schijven ondersteunt Garage een meerdisk data_dir configuratie met per-pad capaciteiten en automatische balansering.

# Voorbeeld: meerdere HDDs voor data blokken
metadata_dir = "/mnt/ssd/garage-meta"
data_dir = [
  { path = "/mnt/hdd1/garage-data", capacity = "8T" },
  { path = "/mnt/hdd2/garage-data", capacity = "8T" },
]

Toegangscontrolemodel versus S3 bucketbeleid

Garage implementeert geen AWS-stijl ACLs of bucketbeleid; het gebruikt zijn eigen “per accesskey per bucket” toegangsmodel dat wordt beheerd via de Garage CLI / admin API.
Dit betekent dat het “beleid” dat je meestal naar Garage vertaalt is: welke accesskey lees-/schrijfrechten heeft op welke bucket(s).

# Alleen-lezen sleutel voor een bucket:
garage key create ro-key
garage bucket allow --read example-bucket --key ro-key

# Toegang verwijderen:
garage bucket deny example-bucket --key ro-key

DNS-stijl versus padstijl bucketadressering

Garage kan virtueel-host (DNS) stijl buckettoegang ondersteunen als je [s3_api].root_domain configureert; padstijl is altijd ingeschakeld.
Als je vhost-stijl niet instelt (wildcard DNS + mogelijk wildcard TLS), kunnen veel clients worden gemaakt om padstijl te forceren, en de Garage documentatie toont clientvoorbeelden met force_path_style = true.

TLS

Garage’s S3 API en web eindpunten ondersteunen geen TLS direct; de officiële richtlijnen zijn om een reverse proxy voor te zetten, vaak Nginx, om HTTPS te leveren en diensten op poort 443 te multiplexen.

Een minimale Nginx “vorm” (zie de officiële reverse proxy gids voor een volledig voorbeeld):

# /etc/nginx/sites-available/garage.conf (afsnittelijk)
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;
  }
}

Server-side encryptie

Garage ondersteunt S3 SSE-C (“server-side encryptie met door gebruiker geleverde sleutels”): de client stuurt encryptiesleutels in headers per verzoek; Garage encrypteert op schijf en verwijdert de sleutel na het verzoek.
Garage’s S3 compatibiliteitstabel noemt ook dat bucketniveau encryptieconfiguratie eindpunten niet zijn geïmplementeerd, dus behandel SSE-C als per-object/verzoek gedrag in plaats van standaardwaarden per bucket.

Garage in productiebedrijf draaien

Monitoring en logboekregistratie

Garage biedt Prometheus-formaat metrieken en ondersteunt het exporteren van traceringen in OpenTelemetry formaat.
Admin en metriekseindpunten kunnen worden beveiligd met tokens (admin_token, metrics_token, en metrics_require_token), en traceringen kunnen worden geëxporteerd via trace_sink (OTLP).
Voor logboekregistratie kan Garage worden afgestemd via RUST_LOG, en de configuratieverwijzing documenteert omgevingsvariabelen om logboeken naar syslog/journald te sturen in plaats van stderr.

Duurzaamheid, reparaties en veelvoorkomende onderhoudstaken

Garage bevat achtergrond “scrub” (integriteitsverificatie) en reparatietools; scrubs kunnen handmatig worden gestart en worden gevolgd via worker/task commando’s, maar zijn schijfintensief en kunnen het cluster vertragen.
Veranderingen in topologie en capaciteitsaanpassingen worden afgehandeld via layoutbeheer; operaties worden toegepast als nieuwe layoutversies.

Back-up- en herstelstrategie

Minimaal back-up metadata, omdat het clusterconfiguratie, bucket/sleutelstatus en indices bevat. Garage ondersteunt periodieke metadata snapshots (metadata_auto_snapshot_interval) en handmatige snapshots (garage meta snapshot --all).
De Garage migratiegids adviseert expliciet om specifieke bestanden/mapstructuren van elke knooppunt’s metadata_dir (inclusief snapshots en layoutbestanden) te back-uppen.

Voor objectdata behandel Garage zoals elk S3-eindpunt: gebruik S3-compatibele back-uptools (bijvoorbeeld restic, duplicity) gericht op een Garage-bucket, zoals beschreven in de Garage “Backups” integratiepagina.

Probleemoplossing van veelvoorkomende fouten

NO ROLE ASSIGNED in garage status betekent meestal dat je nog geen layout hebt gemaakt/toegepast. Oplossing: garage layout assign … gevolgd door garage layout apply.
AuthorizationHeaderMalformed geeft vaak aan dat een client de verkeerde regio gebruikt; stel AWS_DEFAULT_REGION (of equivalent) in om overeen te komen met [s3_api].s3_region.
Signature / verzoekfouten kunnen worden veroorzaakt door onovereenstemming tussen padstijl en vhoststijl; configureer [s3_api].root_domain voor vhoststijl, of forceer padstijl in clients (bijvoorbeeld rclone’s force_path_style=true).
Toegangsrechtenfouten zijn vaak gewoon “sleutel niet toegestaan op bucket”; inspecteer met garage bucket info <bucket> en zorg dat garage bucket allow de juiste vlaggen heeft.

Belangrijke prestatieoptimalisatiepunten

Plaats metadata_dir op een SSD wanneer mogelijk; Garage documentatie benadrukt verbeterde responsentijd en “drastisch verminderde” latentiepotentie.
Stel block_size en compressie zorgvuldig in: Garage standaarden zijn bedoeld om redelijk te zijn, maar de configuratieverwijzing legt de afweging uit en noemt dat veranderingen alleen van toepassing zijn op nieuw geüploade data.
Als je NVMe hebt, kan het verhogen van blockwriteconcurrentie doorvoer verbeteren, maar verhoogt het geheugenverbruik; Garage biedt richtlijnen voor block_max_concurrent_writes_per_request.
Garage eigen benchmarks benadrukken de kosten van intra-cluster latentie in geografisch verspreide opstellingen, en benadrukken ontwerpkeuzes (bijvoorbeeld het vermijden van consensusleiders) die kunnen bijdragen aan het verminderen van geografische latentieimpact.

Korte vergelijking met MinIO en AWS S3

Garage is geoptimaliseerd voor zelfgehoste, geografisch verspreide clusters en operationele eenvoud, met enkele bewuste S3 functie-tekortkomingen (bijvoorbeeld geen S3 bucketbeleid/ACLs; beperkte versieondersteuning).
MinIO richt zich op S3 API breedte en hoge prestaties in enterprise-implementaties (bijvoorbeeld, de eigen materialen van MinIO beschrijven functies zoals objectlock, replicatie en gebeurtenismeldingen).
AWS S3 is de beheerde referentieimplementatie met sterke consistentie, 11 nines duurzaamheid en 99,99% beschikbaarheid doelen, en een brede functieecosysteem (opslagklassen, levensloop, gebeurtenissen, IAM).

Voor meer details zie Garage vs MinIO vs AWS S3 Vergelijking.

Meer over Minio: