Garage - Stockage d'objets compatible S3 - Démarrage rapide

Exécuter Garage avec Docker en quelques minutes

Sommaire

Garage est un système de stockage objet open source, auto-hébergé et compatible S3, conçu pour les déploiements de petite à moyenne envergure, avec une forte emphasis sur la résilience et la géodistribution.

Ce guide de mise en route vous mène du setup à copier-coller à un seul nœud jusqu’aux modèles adaptés à la production : mise en page du cluster, réplication, TLS via un proxy inverse, stockages arrière-plan multi-disques, surveillance, réparations et sauvegarde/restauration.

Pour avoir une vision d’ensemble — stockage objet, PostgreSQL, Elasticsearch et couches de données natives pour l’IA — consultez l’article Infrastructure de données pour les systèmes d’IA.

Boîtes Garage

Ce que Garage est

Garage est un stockage objet distribué compatible S3 conçu pour l’auto-hébergement, visant à rester léger et simple à gérer tout en prenant en charge les clusters multi-site/géodistribués.
Il est publié sous la licence AGPL v3.

Des idées clés qui façonnent la manière dont vous le faites fonctionner :

Garage mesure la capacité des nœuds et leur emplacement physique (“zones”) pour placer les réplicas ; les changements de topologie de cluster (ajout/suppression de nœuds) sont gérés via des mises en page versionnées et du rééquilibrage.
Les objets sont divisés en blocs de taille fixe (block_size), ce qui permet la déduplication et une compression optionnelle avec Zstandard ; les hachages de bloc sont utilisés pour le positionnement et la déduplication.
Garage ne termine pas le TLS sur ses points de terminaison S3/web : vous êtes censé déployer un proxy inverse pour le HTTPS dans les déploiements réels.

Architecture et flux de données

Au niveau global, vous interagissez avec Garage via des clients compatibles S3 ; le trafic entre généralement via un proxy inverse (TLS), atteint un ou plusieurs points de terminaison API Garage (souvent des nœuds “passerelle”), puis est servi par des nœuds de stockage qui contiennent les blocs de données répliqués.

flux de données du cluster Garage

Les nœuds ont des rôles : des nœuds de stockage avec capacité vs des nœuds passerelle qui exposent des points de terminaison sans stocker de données ; les passerelles réduisent la latence en évitant les sauts réseau supplémentaires et en “connaissant” lesquels nœuds de stockage interroger.
La réplication est contrôlée via replication_factor (par exemple, une réplication 3 voies à travers les zones), avec des compromis clairs entre disponibilité et tolérance aux pannes décrits dans la référence de configuration.

Mise en route rapide à copier-coller

C’est un déploiement intentionnellement minimal à un seul nœud pour apprendre les workflows : configuration → démarrer le serveur → définir la mise en page → créer un bucket + clé → télécharger un objet.

Prérequis

Vous avez besoin de docker, openssl et (facultativement) un client S3 comme awscli. L’interface CLI de Garage est le même binaire utilisé pour administrer le cluster.

Étapes par étapes

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

# 1) Créer une configuration de départ (chemins persistants à l'intérieur du conteneur)
cat > ./config/garage.toml <<EOF
metadata_dir = "/var/lib/garage/meta"
data_dir     = "/var/lib/garage/data"
db_engine = "sqlite"

# Déploiement à un seul nœud pour apprendre (AUCUNE redondance). Pour la production, voir plus loin.
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"
# Style vhost optionnel. Le style par chemin est toujours activé.
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) Choisir une étiquette d'image (placeholder). Les exemples d'étiquettes apparaissent dans la documentation Garage.
GARAGE_IMAGE="dxflrs/garage:TAG_PLACEHOLDER"

# 3) Exécuter 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) Utiliser le CLI garage à l'intérieur du conteneur
alias garage='docker exec -ti garaged /garage'

# 5) Vérifier l'état du nœud (vous verrez probablement "NO ROLE ASSIGNED")
garage status

# 6) Assigner une mise en page (un seul nœud) et l'appliquer
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) Créer un bucket + clé et accorder des permissions minimales
garage bucket create example-bucket
garage key create example-app-key
garage bucket allow --read --write --owner example-bucket --key example-app-key

# 8) Afficher le matériel de la clé (sauvegarder sécurisément)
garage key info example-app-key

Le modèle de configuration (API S3 sur 3900, RPC sur 3901, point de terminaison web sur 3902, API admin sur 3903) et le workflow “mise en page requise” proviennent directement du guide de mise en route upstream.

Valider avec AWS CLI

Garage exige que les clients utilisent la s3_region configurée (souvent “garage”) ; si votre client utilise us-east-1, vous pouvez rencontrer des redirections AuthorizationHeaderMalformed.

# Installation (une option)
python -m pip install --user awscli

# Configuration de l'environnement (exemple)
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

Le guide de mise en route upstream recommande d’utiliser un fichier ~/.awsrc pour basculer entre les points de terminaison/clés et note les versions minimales d’AWS CLI pour un traitement pratique des points de terminaison.

Options d’installation et de déploiement

Installations binaires et paquets

La documentation Garage supporte explicitement : télécharger des binaires depuis la page de téléchargement de Garage, utiliser des paquets de distribution (par exemple, apk add garage sur Alpine), ou compiler depuis la source si nécessaire.

Docker et Docker Compose

Garage fournit des images conteneur et documente une méthode minimale docker run pour un usage de mise en route rapide.
Pour la production, vous utiliserez généralement compose (ou un orchestrateur) pour gérer le stockage persistant, le proxy inverse et les mises à jour (redémarrages en roue libre). Le guide de déploiement de Garage sur un cluster suppose Docker sur chaque nœud et mentionne les chemins d’hôte communs et la recommandation de SSD pour les métadonnées.

systemd

Garage documente un déploiement renforcé avec systemd, y compris les avertissements concernant DynamicUser= de systemd et l’endroit où se trouve l’état persistant sur le disque.
Un exemple minimal d’unité (adaptez les chemins à votre environnement) :

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

Garage fournit un chart Helm en interne et a des pages de documentation officielles pour le déploiement sur Kubernetes.
Un point commun est que vous devez toujours initialiser/appliquer une mise en page de cluster après l’installation (vous pouvez l’automatiser avec un Job Kubernetes).

Configuration, sécurité et TLS

Stockages arrière-plan et mise en page du disque

Garage sépare le stockage en metadata_dir et data_dir. La référence de configuration recommande de placer metadata_dir sur un SSD rapide pour améliorer les temps de réponse, tandis que data_dir peut se trouver sur un HDD plus grand.
Pour les nœuds avec plusieurs disques de données, Garage prend en charge une configuration data_dir multi-disque avec des capacités par chemin et un équilibrage automatique.

# Exemple : plusieurs HDD pour les blocs de données
metadata_dir = "/mnt/ssd/garage-meta"
data_dir = [
  { path = "/mnt/hdd1/garage-data", capacity = "8T" },
  { path = "/mnt/hdd2/garage-data", capacity = "8T" },
]

Modèle de contrôle d’accès vs politiques de bucket S3

Garage n’implémente pas les ACLs ou politiques de bucket du style AWS ; il utilise son propre système de permission “par clé d’accès par bucket” géré via le CLI Garage / API admin.
Cela signifie que la “politique” que vous traduisez généralement en Garage est : quelle clé d’accès a le droit de lecture/écriture/propriétaire sur quel bucket(s).

# Clé en lecture seule pour un bucket :
garage key create ro-key
garage bucket allow --read example-bucket --key ro-key

# Retirer l'accès :
garage bucket deny example-bucket --key ro-key

Adressage de bucket en style DNS vs par chemin

Garage peut supporter l’accès en style hôte virtuel (DNS) si vous configurez [s3_api].root_domain ; le style par chemin est toujours activé.
Si vous ne configurez pas le style vhost (DNS sauvage + éventuellement TLS sauvage), de nombreux clients peuvent être faits fonctionner en forçant le style par chemin, et la documentation Garage montre des exemples clients avec force_path_style = true.

TLS

L’API S3 et les points de terminaison web de Garage ne supportent pas directement le TLS ; la recommandation officielle est de placer un proxy inverse devant, souvent Nginx, pour servir le HTTPS et multiplexer les services sur le port 443.

Un exemple minimal de forme Nginx (voir la recette officielle du proxy inverse pour un exemple complet) :

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

Chiffrement côté serveur

Garage supporte S3 SSE-C (“chiffrement côté serveur avec des clés fournies par le client”) : le client envoie des clés de chiffrement dans les en-têtes par requête ; Garage chiffre au repos et supprime la clé après la requête.
Le tableau de compatibilité S3 de Garage note également que les points de configuration de chiffrement au niveau du bucket ne sont pas implémentés, donc traitez SSE-C comme un comportement par objet/requête plutôt que comme des paramètres par défaut de bucket.

Opération de Garage en production

Surveillance et journalisation

Garage expose des métriques au format Prometheus et prend en charge l’exportation de traces au format OpenTelemetry.
Les points de terminaison admin et métriques peuvent être protégés par des tokens (admin_token, metrics_token, et metrics_require_token), et le traçage peut être exporté via trace_sink (OTLP).
Pour la journalisation, Garage peut être ajusté via RUST_LOG, et la référence de configuration documente les variables d’environnement pour envoyer les journaux vers syslog/journald au lieu de stderr.

Durabilité, réparations et tâches de maintenance courantes

Garage inclut des “scrubs” en arrière-plan (vérification d’intégrité) et des outils de réparation ; les scrubs peuvent être lancés manuellement et surveillés via les commandes worker/task, mais ils sont disque-intensifs et peuvent ralentir le cluster.
Les changements de topologie et d’ajustements de capacité sont gérés via la gestion de mise en page ; les opérations sont appliquées comme nouvelles versions de mise en page.

Stratégie de sauvegarde et restauration

Au minimum, sauvegardez les métadonnées, car elles contiennent la configuration du cluster, l’état des buckets/clés et les index. Garage supporte des sauvegardes périodiques des métadonnées (metadata_auto_snapshot_interval) et des sauvegardes manuelles (garage meta snapshot --all).
Le guide de migration de Garage recommande explicitement de sauvegarder certains fichiers/répertoires spécifiques de chaque nœud dans metadata_dir (y compris les sauvegardes et les fichiers de mise en page).

Pour les données d’objets, traitez Garage comme tout point de terminaison S3 : utilisez des outils de sauvegarde compatibles S3 (par exemple, restic, duplicity) ciblant un bucket Garage, comme documenté sur la page de l’intégration “Backups” de Garage.

Notes de débogage des erreurs courantes

NO ROLE ASSIGNED dans garage status indique généralement que vous n’avez pas encore créé/appliqué de mise en page. Solution : garage layout assign … puis garage layout apply.
AuthorizationHeaderMalformed indique souvent qu’un client utilise la mauvaise région ; définissez AWS_DEFAULT_REGION (ou équivalent) pour correspondre à [s3_api].s3_region.
Les échecs de signature ou de requête peuvent être causés par un désaccord entre style par chemin et style vhost ; configurez [s3_api].root_domain pour le style vhost, ou forcez le style par chemin dans les clients (par exemple, force_path_style=true dans rclone).
Les erreurs de permission sont souvent simplement “clé non autorisée sur le bucket” ; inspectez avec garage bucket info <bucket> et assurez-vous que garage bucket allow a les bonnes options.

Notes de réglage de performance qui comptent le plus

Mettez metadata_dir sur un SSD si possible ; les documents Garage soulignent les temps de réponse améliorés et le potentiel de réduction drastique de la latence.
Réglez block_size et la compression avec soin : les valeurs par défaut de Garage sont conçues pour être raisonnables, mais la référence de configuration explique le compromis et note que les changements ne s’appliquent qu’aux données nouvellement téléchargées.
Si vous avez des NVMe, augmenter la concurrence d’écriture des blocs peut améliorer le débit mais augmente l’utilisation de la mémoire ; Garage fournit des conseils pour block_max_concurrent_writes_per_request.
Les propres benchmarks de Garage mettent l’accent sur les coûts de la latence intra-cluster dans les configurations géodistribuées, et soulignent les choix de conception (par exemple, éviter les leaders de consensus) qui peuvent réduire l’impact de la latence géographique.

Comparaison courte avec MinIO et AWS S3

Garage est optimisé pour les clusters auto-hébergés et géodistribués, ainsi que pour la simplicité opérationnelle, avec certains écarts délibérés aux fonctionnalités S3 (par exemple, pas de politiques de bucket/ACLs S3 ; support limité de la versioning).
MinIO se concentre sur la largeur de l’API S3 et les déploiements d’entreprise à haute performance (par exemple, les propres matériaux de MinIO décrivent des fonctionnalités comme le verrou d’objet, la réplication et les notifications d’événement).
AWS S3 est l’implémentation gérée de référence avec une forte cohérence, une durabilité de 11 nines et des cibles d’accessibilité de 99,99 %, ainsi qu’un écosystème de fonctionnalités large (classes de stockage, cycle de vie, événement, IAM).

Plus d’informations sur MinIO :

Liens utiles