Garage - Archiviazione oggetti compatibile con S3 Guida rapida

Esegui Garage in Docker in pochi minuti

Indice

Garage è un sistema di storage oggetto open-source, auto-hostato e compatibile con S3, progettato per piccole e medie implementazioni, con un forte enfasi sulla resilienza e sulla distribuzione geografica.

Questo quickstart ti guiderà da un setup singolo nodo copia/incolla fino a modelli pensati per la produzione: layout del cluster, replicazione, TLS tramite reverse proxy, storage backends multi-disco, monitoraggio, riparazioni e backup/restore.

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

Box Garage

Cosa è Garage

Garage è un sistema di storage oggetto distribuito compatibile con S3 destinato all’auto-hosting, mira a rimanere leggero e semplice da gestire, supportando cluster multi-sito/distribuiti geograficamente.
È rilasciato sotto la licenza AGPL v3.

I concetti chiave che definiscono come si esegue:

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 tramite layout versionati e ribilanciamento.
Gli oggetti vengono suddivisi in blocchi di dimensioni fisse (block_size), il 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 sugli endpoint API/web S3: è previsto che si deployi un reverse proxy per HTTPS nelle implementazioni reali.

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 storage che conservano blocchi di dati replicati.

Flusso dati cluster Garage

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

Quickstart copia/incolla

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

Requisiti preliminari

Hai bisogno di docker, openssl e (opzionalmente) un client S3 come awscli. Il CLI di Garage è lo stesso binario utilizzato per amministrare il cluster.

Passo dopo passo

# 0) Spazio di lavoro
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 singolo-nodo per apprendimento (NESSUNA ridondanza). Per 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). Esempi di tag 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) Controlla lo stato del nodo (probabilmente vedrai "NO ROLE ASSIGNED")
garage status

# 6) Assegna un layout (singolo nodo) e applicalo
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) Crea un bucket + chiave e concede i permessi minimi necessari
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 richiede layout” provengono direttamente dal quickstart upstream.

Validazione con AWS CLI

Garage richiede ai client di utilizzare la configurazione s3_region (spesso “garage”); se il tuo client usa 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 del CLI AWS 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 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 userà tipicamente compose (o un orchestratore) per gestire lo storage persistente, il reverse proxy e gli aggiornamenti (riavvii a rotazione). La guida Garage “deployment su cluster” assume Docker su ogni nodo e indica i percorsi host comuni e la raccomandazione di SSD per i metadati.

systemd

I documenti Garage descrivono un deployment systemd rafforzato, incluso i caveat riguardo 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 bootstrap/apply un layout del cluster dopo l’installazione (puoi automatizzarlo con un Job Kubernetes).

Configurazione, sicurezza e TLS

Backend di storage e layout del disco

Garage divide il storage 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ò stare su un HDD più grande.
Per nodi con più unità di dati, 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 politiche S3 bucket

Garage non implementa ACLs o politiche di bucket dello stile AWS; utilizza il proprio sistema di permessi “per access key per bucket” gestito tramite Garage CLI / API amministrativa.
Questo significa che la “politica” che solitamente trasferisci in Garage è: quale access key ha permessi di lettura/scrittura/proprietario 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 in stile DNS vs percorso

Garage può supportare virtual-host (DNS) style se configuri [s3_api].root_domain; lo stile percorso è sempre abilitato.
Se non configuri lo stile vhost (DNS wild-card + TLS wild-card), molti client possono essere fatti 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 raccomanda di posizionare un reverse proxy davanti, spesso Nginx, per servire HTTPS e multiplexare i servizi sulla porta 443.

Un esempio minimo di “forma” 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 a riposo e elimina la chiave dopo la richiesta.
La tabella di compatibilità S3 di Garage nota anche che gli endpoint di configurazione per la 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 log

Garage espone metriche in formato Prometheus e supporta l’esportazione di tracce in formato OpenTelemetry.
Gli endpoint amministrativi e le metriche possono essere protetti da token (admin_token, metrics_token e metrics_require_token), e il tracciamento può essere esportato tramite trace_sink (OTLP).
Per i log, Garage può essere regolato tramite RUST_LOG, e il riferimento alla configurazione documenta le variabili ambiente per inviare i log a syslog/journald invece che a 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 le regolazioni di capacità vengono gestiti tramite la gestione del layout; le operazioni vengono applicate come nuove versioni di layout.

Strategia di backup e ripristino

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

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

Note di risoluzione di errori comuni

NO ROLE ASSIGNED in garage status indica di solito che non hai ancora creato/applied un layout. Correzione: garage layout assign … quindi garage layout apply.
AuthorizationHeaderMalformed indica spesso che il client usa la regione sbagliata; imposta AWS_DEFAULT_REGION (o equivalente) per corrispondere a [s3_api].s3_region.
Fallimenti di firma/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 permesso sono spesso semplicemente “chiave non autorizzata sul bucket”; ispeziona con garage bucket info <bucket> e assicurati che garage bucket allow abbia i flag giusti.

Note di tuning delle prestazioni che contano di più

Mettilo metadata_dir su SSD quando possibile; i documenti Garage evidenziano tempi di risposta migliorati e un potenziale riduzione drastica della latenza.
Tuning block_size e compressione con attenzione: i valori predefiniti di Garage sono intesi per essere sensati, ma il riferimento alla configurazione spiega il trade-off e nota che i cambiamenti si applicano solo ai dati caricati di recente.
Se hai NVMe, aumentare la concorrenza di scrittura dei blocchi potrebbe migliorare la throughput ma aumenta 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 progettazione (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-hostati e geodistribuiti, con semplicità operativa, con alcuni gap di funzionalità S3 deliberati (es. nessun supporto per politiche/ACL S3; limitata supporto per versioning).
MinIO si concentra sulla larghezza dell’API S3 e su deployment enterprise ad alte prestazioni (es. i materiali di MinIO descrivono funzionalità come il blocco degli oggetti, la replicazione e le notifiche degli eventi).
AWS S3 è l’implementazione gestita con forte coerenza, durabilità a 11 nines e obiettivi di disponibilità del 99,99%, e un ampio ecosistema di funzionalità (classi di storage, ciclo di vita, eventi, IAM).

Per maggiori dettagli vedi Confronto Garage vs MinIO vs AWS S3.

Ulteriori informazioni su MinIO: