Garage - S3 compatibele objectopslag Quickstart

Garage in Docker draaien in minuten

Inhoud

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

Deze quickstart leidt je vanaf een eenvoudige copy/paste uninode setup naar productiematige patronen: clusteropstelling, replicatie, TLS via reverse proxy, meervoudige schijf opslag backends, monitoring, reparaties en back-up/restore.

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

Garage Boxes

Wat Garage is

Garage is een S3-compatibele gedistribueerde objectopslag bedoeld voor zelfgehosting, met het doel om lichtgewicht en eenvoudig te opereren, terwijl het ondersteuning biedt voor meervoudige locatie/geo-distribueerde clusters.
Het wordt vrijgegeven onder de AGPL v3 licentie.

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

Garage meet de knooppuntcapaciteit en fysieke locatie (“zones”) om replicaties te plaatsen; veranderingen in cluster topologie (toevoegen/verwijderen van knooppunten) worden afgehandeld via versiebeheerde opstellingen en herverdeling.
Objecten worden opgesplitst in vaste grootte blokken (block_size), wat deduplicatie en optionele Zstandard compressie mogelijk maakt; blok hashes 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 echte wereld implementaties.

Architectuur en data flow

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 dan aangeboden door opslag knooppunten die geredundante data blokken bevatten.

garage- cluster data flow

Knooppunten hebben rollen: opslag knooppunten met capaciteit versus gateway knooppunten die eindpunten onthullen zonder data op te slaan; gateways verminderen latentie door extra netwerk hoppes te vermijden en door te weten welke opslag knooppunten te vragen.
Replicatie wordt beheerd via replication_factor (bijvoorbeeld 3-weg replicatie over zones), met duidelijke beschikbaarheid/fouttolerantie afwegingen beschreven in de configuratie referentie.

Copy/paste quickstart

Dit is opzettelijk een minimale uninode implementatie voor het leren van de workflows: configuratie → start server → definieer opstelling → maak een bucket + sleutel → upload een object.

Voorwaarden

Je hebt docker, openssl, en (optioneel) een S3 client zoals awscli nodig. Garage’s CLI is hetzelfde binaire 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 (persistente paden binnen de container)
cat > ./config/garage.toml <<EOF
metadata_dir = "/var/lib/garage/meta"
data_dir     = "/var/lib/garage/data"
db_engine = "sqlite"

# Uninode 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 beeldtag (tijdelijke waarde). Voorbeelden zijn te vinden 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 opstelling (uninode) 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 toegang
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 overgenomen van 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 AuthorizationHeaderMalformed redirects tegenkomen.

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

# Configuratie (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 de Garage download pagina, het gebruik van distributiepakketten (bijvoorbeeld apk add garage op Alpine), of het bouwen vanaf bron als dat nodig is.

Docker en Docker Compose

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

systemd

Garage documenteert een versterkte systemd implementatie, inclusief waarschuwingen rond systemd’s DynamicUser= en waar persistent state op disk eindigt.
Een minimale eenheid voorbeeld (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 binnen de repo en heeft officiële documentatiepagina’s voor Kubernetes implementatie.
Een algemene valkuil is dat je nog steeds een cluster opstelling moet initialiseren/applyen na installatie (je kunt dit automatiseren met een Kubernetes Job).

Configuratie, beveiliging en TLS

Opslag backends en schijfopstelling

Garage splitst opslag in metadata_dir en data_dir. De configuratie referentie adviseert metadata_dir op een snelle SSD te plaatsen om responsentijden te verbeteren, terwijl data_dir op grotere HDD kan zitten.
Voor knooppunten met meerdere gegevensschijven ondersteunt Garage een meervoudige schijf 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 bucket beleid

Garage implementeert geen AWS-stijl ACLs of bucket beleid; het gebruikt zijn eigen “per access key per bucket” toegangscontrole systeem beheerd via de Garage CLI / admin API.
Dit betekent dat het “beleid” dat je meestal vertaalt naar Garage is: welke access key leest/schrijft/bezit 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 aanbeveling is om een reverse proxy voor te plaatsen, vaak Nginx, om HTTPS te leveren en diensten te multiplexen op poort 443.

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

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

Serverzijde encryptie

Garage ondersteunt S3 SSE-C (“serverzijde 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 compatibiliteits tabel noemt ook dat bucketniveau encryptie configuratie eindpunten niet zijn geïmplementeerd, dus behandel SSE-C als per-object/verzoek gedrag in plaats van bucket standaarden.

Garage opereren in productie

Monitoring en logboekregistratie

Garage exposeert Prometheus-formaat metrieken en ondersteunt het exporteren van traces in OpenTelemetry formaat.
Admin en metriek eindpunten kunnen worden beschermd met tokens (admin_token, metrics_token, en metrics_require_token), en tracing kan worden geëxporteerd via trace_sink (OTLP).
Voor logboekregistratie kan Garage worden afgestemd via RUST_LOG, en de configuratie referentie documenteert omgevingsvariabelen om logboeken naar syslog/journald te sturen in plaats van stderr.

Duurzaamheid, reparaties en algemene onderhoudstaken

Garage bevat achtergrond “scrub” (integriteitsverificatie) en reparatie tools; scrubs kunnen handmatig worden gestart en worden gemonitord via worker/task commando’s, maar zijn schijfintensief en kunnen het cluster vertragen.
Topologieveranderingen 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 migratie gids adviseert expliciet om bepaalde bestanden/mappen van elk knooppunt’s metadata_dir (inclusief snapshots en layoutbestanden) te back-uppen.

Voor objectgegevens, behandel Garage als enig S3 eindpunt: gebruik S3-compatibele back-up tools (bijvoorbeeld restic, duplicity) gericht op een Garage bucket, zoals beschreven op de Garage “Backups” integratiepagina.

Probleemoplossing van veelvoorkomende fouten

NO ROLE ASSIGNED in garage status betekent meestal dat je nog geen opstelling hebt gemaakt/toegepast. Oplossing: garage layout assign … en vervolgens garage layout apply.
AuthorizationHeaderMalformed wijst vaak op een client die de verkeerde regio gebruikt; stel AWS_DEFAULT_REGION (of equivalent) in om overeen te komen met [s3_api].s3_region.
Handtekening / verzoek fouten kunnen worden veroorzaakt door een 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.

Prestatieoptimalisatie die het meeste uitmaakt

Zet metadata_dir op SSD als mogelijk; Garage documentatie noemt verbeterde responsentijden en “drastisch verminderde” latentie mogelijkheden.
Stel block_size en compressie zorgvuldig in: Garage standaarden zijn bedoeld om redelijk te zijn, maar de configuratie referentie legt de afweging uit en noemt dat wijzigingen alleen van toepassing zijn op nieuw geüploade gegevens.
Als je NVMe hebt, kan het verhogen van blok schrijfconcurrentie doorvoer verbeteren maar verhoogt geheugenverbruik; Garage biedt richtlijnen voor block_max_concurrent_writes_per_request.
Garage eigen benchmarks benadrukken de kosten van intra-cluster latentie in geografisch verdeelde opstellingen, en benadrukken ontwerpkeuzes (bijvoorbeeld het vermijden van consensus leiders) die kunnen helpen bij het verminderen van geografische latentie impact.

Korte vergelijking met MinIO en AWS S3

Garage is geoptimaliseerd voor zelfgehoste, geografisch verdeelde clusters en operationele eenvoud, met enkele doelbewuste S3 functie gaps (bijvoorbeeld geen S3 bucket beleid/ACLs; beperkte versiebeheer ondersteuning).
MinIO richt zich op S3 API breedte en hoge prestaties in enterprise implementaties (bijvoorbeeld, de eigen documentatie van MinIO beschrijft functies zoals object lock, replicatie en eventmeldingen).
AWS S3 is de beheerde referentieimplementatie met sterke consistentie, 11 nines duurzaamheid en 99.99% beschikbaarheid doelen, en een brede functie ecosystem (opslagklassen, levenscyclus, eventing, IAM).

Meer over Minio: