Garage - Archiviazione oggetti compatibile con S3 Guida rapida

Esegui Garage in Docker in pochi minuti

Indice

Garage è un sistema open source, self-hosted, compatibile con S3, per l’archiviazione di oggetti progettato per piccole e medie installazioni, con una forte enfasi sulla resilienza e sulla distribuzione geografica.

Questo quickstart ti guiderà da un setup a singolo nodo copia/incolla fino a pattern orientati alla produzione: layout del cluster, replicazione, TLS tramite reverse proxy, backend di archiviazione su più dischi, monitoraggio, riparazioni e backup/restore.

Per il quadro generale — archiviazione oggetti, PostgreSQL, Elasticsearch e strati di dati nativi per l’AI — vedi l’articolo Infrastruttura dati per sistemi AI.

Garage Boxes

Cosa è Garage

Garage è un archivio oggetti distribuito compatibile con S3 destinato all’hosting self-hosted, mira a rimanere leggero e semplice da gestire, supportando cluster multi-sito/distribuiti geograficamente.
Viene rilasciato sotto la licenza AGPL v3.

Le idee chiave che definiscono il modo in cui lo si utilizza:

Garage misura la capacità del nodo e la posizione fisica (“zone”) per posizionare le repliche; i cambiamenti nella topologia del cluster (aggiunta/rimozione di nodi) vengono gestiti attraverso layout versionati e ribilanciamento.
Gli oggetti vengono suddivisi in blocchi di dimensione fissa (block_size), che consente la deduplicazione e una compressione opzionale con Zstandard; gli hash dei blocchi vengono utilizzati per il posizionamento e la deduplicazione.
Garage non termina il TLS sui propri endpoint API/web S3: si prevede di installare un reverse proxy per HTTPS nelle reali implementazioni.

Architettura e flusso dei dati

Al livello più alto interagisci con Garage tramite client compatibili con S3; il traffico entra tipicamente tramite un reverse proxy (TLS), raggiunge uno o più endpoint API Garage (spesso nodi “gateway”) e viene servito da nodi di archiviazione che contengono blocchi di dati replicati.

garage- cluster data flow

I nodi hanno ruoli: nodi di archiviazione con capacità vs gateway nodi che espongono endpoint senza archiviare dati; i gateway riducono la latenza evitando ulteriori salti di rete e “sapendo” quali nodi di archiviazione interrogare.
La replicazione è controllata tramite replication_factor (ad esempio, replicazione a 3 vie tra zone), con chiare trade-off tra disponibilità e tolleranza al guasto descritti nel riferimento alla configurazione.

Quickstart copia/incolla

Questo è un deployment a singolo nodo intenzionalmente minimal per imparare i flussi di lavoro: configurazione → avvia server → definisci layout → crea bucket + chiave → carica un oggetto.

Prerequisiti

Hai bisogno di docker, openssl e (opzionalmente) un client S3 come awscli. L’interfaccia CLI di Garage è la stessa binaria utilizzata per amministrare il cluster.

Passo passo

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

# 1) Crea una configurazione iniziale (percorsi persistenti all'interno del container)
cat > ./config/garage.toml <<EOF
metadata_dir = "/var/lib/garage/meta"
data_dir     = "/var/lib/garage/data"
db_engine = "sqlite"

# Deployment a singolo nodo per apprendimento (NESSUNA ridondanza). Per la produzione, vedi più avanti.
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"
# Opzionale stile vhost. Lo stile percorso è sempre abilitato.
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) Scegli un tag immagine (placeholder). I tag di esempio appaiono nei documenti Garage.
GARAGE_IMAGE="dxflrs/garage:TAG_PLACEHOLDER"

# 3) Esegui 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) Usa il CLI garage all'interno del container
alias garage='docker exec -ti garaged /garage'

# 5) Verifica lo stato del nodo (probabilmente vedrai "NESSUN RUOLO ASSEGNATO")
garage status

# 6) Assegna un layout (singolo nodo) e applicalo
NODE_ID="$(garage status | awk '/NESSUN RUOLO ASSEGNATO/{print $1; exit}')"
garage layout assign -z dc1 -c 1G "$NODE_ID"
garage layout apply --version 1

# 7) Crea un bucket + chiave e concede i permessi di minimo privilegio
garage bucket create example-bucket
garage key create example-app-key
garage bucket allow --read --write --owner example-bucket --key example-app-key

# 8) Mostra il materiale della chiave (salvalo in modo sicuro)
garage key info example-app-key

Il modello di configurazione (API S3 su 3900, RPC su 3901, endpoint web su 3902, API amministrativa su 3903) e il flusso di lavoro “layout richiesto” provengono direttamente dal quickstart upstream.

Validazione con AWS CLI

Garage richiede ai client di utilizzare la s3_region configurata (spesso “garage”); se il tuo client utilizza us-east-1, potresti incontrare reindirizzamenti AuthorizationHeaderMalformed.

# Installa (un'opzione)
python -m pip install --user awscli

# Configura l'ambiente (esempio)
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

Il quickstart upstream raccomanda l’uso di un file ~/.awsrc per passare tra endpoint/chiavi e nota le versioni minime di AWS CLI per un gestione comoda degli endpoint.

Opzioni di installazione e deployment

Installazioni binarie e pacchetti

I documenti Garage supportano esplicitamente: il download di binari dalla pagina di download di Garage, l’uso di pacchetti distro (es. apk add garage su Alpine), o la compilazione da sorgente se necessario.

Docker e Docker Compose

Garage fornisce immagini container e documenta un metodo docker run minimo per l’uso nel quickstart.
Per la produzione si utilizzerà tipicamente compose (o un orchestratore) per gestire l’archiviazione persistente, il reverse proxy e gli aggiornamenti (riavvii rolling). La guida Garage “deployment su cluster” assume Docker su ogni nodo e segnala i percorsi host comuni e la raccomandazione di utilizzare SSD per i metadati.

systemd

I documenti Garage descrivono un deployment systemd rafforzato, incluso i caveat intorno a DynamicUser= di systemd e dove finisce lo stato persistente sul disco.
Un esempio di unità minima (adatta i percorsi al tuo ambiente):

# /etc/systemd/system/garage.service
[Unit]
Description=Garage S3-compatible object storage
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 e Helm

Garage include un chart Helm in repo e ha pagine di documentazione ufficiali per il deployment su Kubernetes.
Un comune problema è che devi comunque avviare/aggiornare un layout del cluster dopo l’installazione (puoi automatizzarlo con un Job Kubernetes).

Configurazione, sicurezza e TLS

Backend di archiviazione e layout dei dischi

Garage divide l’archiviazione in metadata_dir e data_dir. Il riferimento alla configurazione raccomanda di posizionare metadata_dir su un SSD veloce per migliorare i tempi di risposta, mentre data_dir può trovarsi su HDD più grandi.
Per nodi con più dischi di archiviazione, Garage supporta una configurazione data_dir multi-disco con capacità per percorso e bilanciamento automatico.

# Esempio: più HDD per blocchi di dati
metadata_dir = "/mnt/ssd/garage-meta"
data_dir = [
  { path = "/mnt/hdd1/garage-data", capacity = "8T" },
  { path = "/mnt/hdd2/garage-data", capacity = "8T" },
]

Modello di controllo degli accessi vs policy S3 bucket

Garage non implementa ACL o policy bucket nello stile AWS; utilizza il proprio sistema di controllo degli accessi “per chiave di accesso per bucket” gestito tramite CLI Garage / API amministrativa.
Questo significa che la “policy” che di solito traduci in Garage è: quale chiave di accesso ha letttura/scrittura/proprietà su quali bucket.

# Chiave di sola lettura per un bucket:
garage key create ro-key
garage bucket allow --read example-bucket --key ro-key

# Rimuovi l'accesso:
garage bucket deny example-bucket --key ro-key

Indirizzamento bucket stile DNS vs stile percorso

Garage può supportare virtual-host (stile DNS) se configuri [s3_api].root_domain; lo stile percorso è sempre abilitato.
Se non configuri lo stile vhost (DNS wildcard + TLS wildcard), molti client possono funzionare forzando lo stile percorso, e i documenti Garage mostrano esempi client con force_path_style = true.

TLS

L’API S3 e gli endpoint web di Garage non supportano direttamente TLS; la guida ufficiale consiglia di posizionare un reverse proxy davanti, comunemente Nginx, per servire HTTPS e multiplexare i servizi sulla porta 443.

Una forma minima di Nginx (vedi la guida ufficiale per il reverse proxy completo):

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

Crittografia lato server

Garage supporta S3 SSE-C (“crittografia lato server con chiavi fornite dagli utenti”): il client invia le chiavi di crittografia negli header per richiesta; Garage crittografa i dati a riposo e elimina la chiave dopo la richiesta.
La tabella di compatibilità S3 di Garage nota anche che gli endpoint di configurazione della crittografia a livello di bucket non sono implementati, quindi considera SSE-C come comportamento per oggetto/richiesta piuttosto che predefinito per bucket.

Operare Garage in produzione

Monitoraggio e logging

Garage espone metriche in formato Prometheus e supporta l’esportazione di tracce in formato OpenTelemetry.
Gli endpoint amministrativi e di metriche possono essere protetti da token (admin_token, metrics_token e metrics_require_token), e le tracce possono essere esportate tramite trace_sink (OTLP).
Per il logging, Garage può essere regolato tramite RUST_LOG, e il riferimento alla configurazione documenta le variabili ambiente per inviare i log a syslog/journald invece di stderr.

Durabilità, riparazioni e compiti di manutenzione comuni

Garage include uno “scrub” in background (verifica dell’integrità) e strumenti di riparazione; gli scrub possono essere avviati manualmente e monitorati tramite comandi worker/task, ma sono intensivi per i dischi e possono rallentare il cluster.
I cambiamenti di topologia e di capacità vengono gestiti tramite la gestione del layout; le operazioni vengono applicate come nuove versioni del layout.

Strategia di backup e ripristino

Al minimo, fai un backup dei metadati, poiché contengono la configurazione del cluster, lo stato dei bucket/chiavi e gli indici. Garage supporta backup periodici dei metadati (metadata_auto_snapshot_interval) e backup manuali (garage meta snapshot --all).
La guida di migrazione Garage raccomanda esplicitamente di fare backup di file/cartelle specifici da ogni nodo metadata_dir (inclusi snapshot e file di layout).

Per i dati degli oggetti, considera Garage come qualsiasi endpoint S3: utilizza strumenti di backup S3-compatibili (es. restic, duplicity) mirati a un bucket Garage, come documentato nella pagina “Backups” di Garage.

Note di risoluzione dei problemi comuni

NO ROLE ASSIGNED in garage status significa generalmente che non hai creato/applato un layout. Correzione: garage layout assign … quindi garage layout apply.
AuthorizationHeaderMalformed indica spesso che il client utilizza la regione errata; imposta AWS_DEFAULT_REGION (o equivalente) per corrispondere a [s3_api].s3_region.
Fallimenti di firma o richiesta possono essere causati da mismatch tra stile percorso e stile vhost; configura [s3_api].root_domain per stile vhost, o forza lo stile percorso nei client (es. rclone’s force_path_style=true).
Errori di autorizzazione sono spesso solo “chiave non autorizzata sul bucket”; ispeziona con garage bucket info <bucket> e assicurati che garage bucket allow abbia i flag corretti.

Note di tuning che contano di più

Metti metadata_dir su un SSD quando possibile; i documenti Garage sottolineano tempi di risposta migliorati e potenziale riduzione drastica della latenza.
Regola block_size e compressione con attenzione: i valori predefiniti di Garage sono pensati per essere sensati, ma il riferimento alla configurazione spiega il trade-off e nota che i cambiamenti si applicano solo ai dati caricati recentemente.
Se hai NVMe, aumentare la concorrenza di scrittura per blocco potrebbe migliorare la throughput ma aumentare l’uso della memoria; Garage fornisce linee guida per block_max_concurrent_writes_per_request.
I propri benchmark di Garage sottolineano i costi della latenza intra-cluster in configurazioni geodistribuite e evidenziano le scelte di design (es. evitare leader di consenso) che possono ridurre l’impatto della latenza geografica.

Breve confronto con MinIO e AWS S3

Garage è ottimizzato per cluster auto-hosted, geodistribuiti e semplicità operativa, con alcune lacune deliberate rispetto alle funzionalità S3 (es. nessun supporto per policy/ACL di bucket S3; limitato supporto per la versione).
MinIO si concentra sulla vastità dell’API S3 e su deployment ad alte prestazioni per aziende (ad esempio, i materiali di MinIO descrivono funzionalità come lock sugli oggetti, replicazione e notifiche agli eventi).
AWS S3 è l’implementazione gestita con forte coerenza, durabilità a 11 ninen e obiettivi di disponibilità del 99,99%, e un ampio ecosistema di funzionalità (classi di archiviazione, ciclo di vita, eventi, IAM).

Informazioni su Minio: