Garage : stockage objet S3 léger et géo-distribué

Garage est un stockage objet S3 auto-hébergé conçu pour être simple, léger et géo-distribué. Un seul binaire Rust de ~25 Mo, ~50 Mo de RAM par nœud, aucune dépendance externe : c'est l'alternative idéale à MinIO ou Ceph RGW quand vous avez besoin de S3 sans la complexité. Ce guide déploie un cluster 3 nœuds avec réplication en 3 zones, teste l'API S3 et l'hébergement web statique, avec toutes les commandes vérifiées sur Ubuntu 24.04.

Ce que vous allez apprendre

• Architecture Garage : hash ring, zones, CRDT, quorum
• Lab complet : cluster 3 nœuds avec KVM et systemd
• API S3 : buckets, clés, upload/download avec AWS CLI
• Site web statique : héberger un site directement depuis un bucket
• Administration : layout, clés, monitoring, dépannage

Version actuelle

Ce guide utilise Garage v2.2.0 (stable, 24 janvier 2026). La v2.0.0 sortie en juin 2025 a introduit des changements majeurs : nouvelle API d'administration v2, amélioration du protocole RPC et du garbage collector. Les versions 2.1 et 2.2 sont des releases de stabilisation. Toutes les releases : git.deuxfleurs.fr/Deuxfleurs/garage/releases.

Qu'est-ce que Garage ?

Garage est un système de stockage objet distribué open source créé par l'association française Deuxfleurs. Il fournit une API compatible S3 et un module d'hébergement web statique, le tout dans un unique binaire Rust sans dépendance.

Ce qui distingue Garage

Le tableau réunit les traits qui séparent Garage des autres moteurs S3 auto-hébergés. La ligne CRDT est la plus structurante : c'est elle qui explique pourquoi Garage supporte des liaisons lentes entre sites distants, là où la plupart des systèmes distribués exigent un réseau local à faible latence.

Caractéristique	Description
Ultra-léger	Un seul binaire (~25 Mo), ~50 Mo de RAM par nœud. Tourne sur un Raspberry Pi
Géo-distribué	Conçu nativement pour répartir les données sur plusieurs sites (zones)
S3 compatible	API S3 standard, fonctionne avec AWS CLI, MinIO Client, Rclone, Restic
Web statique	Héberge des sites directement depuis les buckets (port dédié)
Sans dépendance	Pas de Docker, pas de base de données externe, pas de JVM
CRDT	Résolution de conflits sans coordination centrale
Quotas par bucket	Limite de taille et de nombre d'objets par bucket
Open source	Licence AGPLv3, développé par Deuxfleurs

Glissez pour voir

Le positionnement de Garage

Garage vise le stockage S3 auto-hébergé léger et géo-distribué : quelques dizaines de Mo de RAM par nœud, un binaire sans dépendance, et une réplication native sur plusieurs zones géographiques. Ses cas d'usage de prédilection : sauvegardes Restic/Borg, stockage Nextcloud, hébergement de sites statiques, artefacts CI/CD, sur un ou plusieurs sites. Garage assume un périmètre volontairement restreint (pas de versioning, d'Object Lock ni de politiques IAM avancées) au profit de la simplicité et de la robustesse multi-site. Pour situer Garage parmi les autres solutions de stockage objet auto-hébergées, voir la vue d'ensemble du stockage.

Architecture et concepts clés

Trois notions suffisent pour exploiter Garage : comment les données sont réparties (le hash ring), où les copies sont placées (les zones), et comment les nœuds se mettent d'accord (CRDT et quorum). Ces choix expliquent autant ses qualités, comme la tolérance à la perte d'un site entier, que ses limites fonctionnelles.

Fonctionnement interne

Garage utilise un hash ring (anneau de hachage) pour distribuer les données entre les nœuds. Chaque objet est découpé en blocs de 1 Mo (par défaut), chaque bloc est répliqué selon le replication_factor (typiquement 3).

Les composants clés :

• Nœud : une instance Garage (un binaire, un fichier de config). Tous les nœuds sont égaux, il n'y a pas de maître.

• Zone : un regroupement logique de nœuds (datacenter, rack, site géographique). Garage garantit que chaque copie d'un objet est stockée dans une zone différente.

• Layout : la carte du cluster qui définit la capacité et la zone de chaque nœud. Doit être appliqué explicitement après modification.

• Partition : subdivision du hash ring. Les données sont assignées aux partitions, elles-mêmes assignées aux nœuds selon le layout.

Modèle de cohérence

Garage utilise des CRDT (Conflict-free Replicated Data Types) pour les métadonnées et un quorum pour les opérations de données :

• Écriture : réussit quand une majorité de nœuds (2/3 en replication_factor=3) confirment
• Lecture : renvoie la donnée dès qu'un nœud répond (mode consistent : vérifie le quorum)
• Cohérence : read-after-write garantie en mode consistent

Ports réseau

Garage ouvre quatre ports, chacun avec un rôle distinct. Un seul, le 3900, a vocation à être joignable par vos applications. Les trois autres sont internes ou réservés à l'administration : ils n'ont rien à faire sur Internet.

Port	Protocole	Usage
3900	HTTP	API S3 (accès client)
3901	TCP	RPC inter-nœuds (protocole interne)
3902	HTTP	Hébergement web statique
3903	HTTP	API d'administration + métriques Prometheus

Glissez pour voir

Lab : déployer un cluster Garage 3 nœuds

Le lab monte un cluster complet réparti sur trois zones, avec trois machines virtuelles KVM. Toutes les sorties reproduites ci-dessous ont été relevées sur Ubuntu 24.04 avec Garage v2.2.0. L'étape qui pose le plus de difficultés n'est pas l'installation mais le layout, la carte de capacités que Garage ignore tant qu'elle n'a pas été explicitement appliquée.

Prérequis

• 3 machines (VMs, serveurs physiques ou même Raspberry Pi)
• Ubuntu 24.04 (ou toute distro Linux)
• 512 Mo de RAM et 1 vCPU minimum par nœud
• Connectivité réseau entre les 3 nœuds (port 3901)

Ressources minimales

Garage est remarquablement léger : 3 Go de RAM au total (3 × 1 Go) suffisent pour un cluster de test avec réplication 3. En production, comptez ~100-200 Mo de RAM par nœud plus la mémoire pour le cache LMDB.

Créer les VMs avec KVM

Les deux onglets se complètent : le script virt-install crée les machines, le fichier cloud-init prépare l'accès SSH et installe chrony. Cette dernière ligne n'est pas cosmétique, Garage s'appuie sur des horodatages pour départager les écritures concurrentes entre nœuds.

Script automatisé

Le script suivant crée 3 VMs légères avec cloud-init :

#!/bin/bash
# Créer 3 VMs pour le lab Garage (1 Go RAM, 1 vCPU, 10 Go disque)
for i in 1 2 3; do
  sudo qemu-img create -f qcow2 \
    -b /var/lib/libvirt/images/ubuntu-24.04-cloud.img -F qcow2 \
    /var/lib/libvirt/images/garage${i}.qcow2 10G

  sudo virt-install --name garage${i} \
    --ram 1024 --vcpus 1 \
    --disk /var/lib/libvirt/images/garage${i}.qcow2 \
    --os-variant ubuntu24.04 \
    --cloud-init user-data=cloud-init-garage${i}.yaml \
    --network network=default \
    --graphics none --noautoconsole --import
done

Cloud-init

Chaque VM utilise un fichier cloud-init (adapter le hostname) :

#cloud-config
hostname: garage1
users:
  - name: bob
    groups: sudo
    shell: /bin/bash
    sudo: ALL=(ALL) NOPASSWD:ALL
    ssh_authorized_keys:
      - ssh-ed25519 AAAA... votre-clé-publique
packages:
  - chrony

Installer et configurer Garage

Les étapes 1, 3 et 4 sont à répéter sur chacun des trois nœuds ; le secret RPC de l'étape 2 se génère une seule fois puis se recopie à l'identique partout. Les étapes 5 et 6 se lancent au contraire depuis une seule machine : elles agissent sur le cluster entier, pas sur le nœud local.

1. Télécharger le binaire sur chaque nœud

   Garage est un binaire statique unique. Le chemin de téléchargement utilise un répertoire x86_64-unknown-linux-musl : c'est un binaire compilé avec musl, compatible avec toutes les distributions Linux sans dépendance :

   curl -fsSL -o /usr/local/bin/garage \
     https://garagehq.deuxfleurs.fr/_releases/v2.2.0/x86_64-unknown-linux-musl/garage
   chmod +x /usr/local/bin/garage

   Vérification :

   garage --version
   # garage v2.2.0 [features: bundled-libs, consul-discovery, lmdb, ...]

   Architectures ARM

   Pour un Raspberry Pi ou une machine ARM64, remplacez x86_64-unknown-linux-musl par aarch64-unknown-linux-musl dans l'URL.

2. Générer le secret RPC partagé

   Tous les nœuds du cluster doivent partager le même secret RPC pour s'authentifier mutuellement :

   openssl rand -hex 32
   # 22c9b4a6b8225ee259298ee643512676e956a2e50702a18bc9a68141c3625e28

   Conservez cette valeur : elle sera identique dans la configuration de chaque nœud.

3. Créer le fichier de configuration

   Sur chaque nœud, créez /etc/garage.toml (adapter rpc_public_addr à l'IP du nœud) :

   metadata_dir = "/var/lib/garage/meta"
   data_dir = "/var/lib/garage/data"
   db_engine = "lmdb"
   metadata_auto_snapshot_interval = "6h"
   
   replication_factor = 3
   consistency_mode = "consistent"
   
   compression_level = 1
   
   rpc_secret = "22c9b4a6b8225ee259298ee643512676e956a2e50702a18bc9a68141c3625e28"
   rpc_bind_addr = "[::]:3901"
   rpc_public_addr = "192.168.122.236:3901"
   
   [s3_api]
   api_bind_addr = "[::]:3900"
   s3_region = "garage"
   root_domain = ".s3.garage"
   
   [s3_web]
   bind_addr = "[::]:3902"
   root_domain = ".web.garage"
   
   [admin]
   api_bind_addr = "0.0.0.0:3903"

   Les paramètres essentiels :

   Paramètre	Rôle
   replication_factor	Nombre de copies de chaque objet (3 = tolérance 1 panne)
   consistency_mode	consistent garantit read-after-write, degraded privilégie la disponibilité
   db_engine	lmdb est le plus rapide et le plus testé
   compression_level	1 = compression zstd légère, 0 = désactivée
   rpc_secret	Clé partagée entre tous les nœuds (identique partout)
   rpc_public_addr	Adresse IP accessible par les autres nœuds

   Glissez pour voir

4. Créer le service systemd

   sudo mkdir -p /var/lib/garage/meta /var/lib/garage/data
   
   sudo tee /etc/systemd/system/garage.service << 'EOF'
   [Unit]
   Description=Garage S3-compatible object store
   After=network-online.target
   Wants=network-online.target
   
   [Service]
   Type=simple
   ExecStart=/usr/local/bin/garage server
   Restart=always
   RestartSec=5
   StateDirectory=garage
   ProtectSystem=full
   
   [Install]
   WantedBy=multi-user.target
   EOF
   
   sudo systemctl daemon-reload
   sudo systemctl enable --now garage

   Vérification :

   sudo systemctl status garage
   # ● garage.service - Garage S3-compatible object store
   #   Active: active (running) since ...

5. Connecter les nœuds entre eux

   Chaque nœud possède un identifiant unique généré automatiquement au premier démarrage. Récupérez-le :

   garage node id
   # 794367e3ef23feb8...@192.168.122.236:3901

   Depuis n'importe quel nœud, connectez les autres :

   garage node connect <ID_NOEUD2>@192.168.122.115:3901
   # Success.
   garage node connect <ID_NOEUD3>@192.168.122.5:3901
   # Success.

   Vérification :

   garage status

   ==== HEALTHY NODES ====
   ID                Hostname  Address               Tags  Zone  Capacity          DataAvail  Version
   794367e3ef23feb8  garage1   192.168.122.236:3901              NO ROLE ASSIGNED             v2.2.0
   d0fb5d2f74e66c45  garage2   192.168.122.115:3901              NO ROLE ASSIGNED             v2.2.0
   79ab760dda72a403  garage3   192.168.122.5:3901                NO ROLE ASSIGNED             v2.2.0

   Bootstrap automatique

   Pour automatiser la découverte en production, ajoutez les adresses des nœuds dans bootstrap_peers du fichier garage.toml, ou utilisez la découverte via Consul ou Kubernetes (voir la doc officielle).

6. Assigner les rôles (layout)

   Informez Garage de la capacité et de la zone de chaque nœud. Les zones garantissent que les 3 copies d'un objet sont stockées sur 3 sites différents :

   garage layout assign 794367e3 -z dc1 -c 5G -t garage1
   garage layout assign d0fb5d2f -z dc2 -c 5G -t garage2
   garage layout assign 79ab760d -z dc3 -c 5G -t garage3

   Prévisualisez puis appliquez :

   garage layout show
   garage layout apply --version 1

   Partitions are replicated 3 times on at least 3 distinct zones.
   
   Optimal partition size:                     19.5 MB
   Usable capacity / total cluster capacity:   15.0 GB / 15.0 GB (100.0 %)
   Effective capacity (replication factor 3):  5.0 GB

   Vérification finale :

   garage status

   ==== HEALTHY NODES ====
   ID                Hostname  Address               Tags       Zone  Capacity  DataAvail       Version
   794367e3ef23feb8  garage1   192.168.122.236:3901  [garage1]  dc1   5.0 GB    7.2 GB (77.6%)  v2.2.0
   d0fb5d2f74e66c45  garage2   192.168.122.115:3901  [garage2]  dc2   5.0 GB    7.2 GB (77.6%)  v2.2.0
   79ab760dda72a403  garage3   192.168.122.5:3901    [garage3]  dc3   5.0 GB    7.2 GB (77.6%)  v2.2.0

Utiliser l'API S3

Le cluster tourne, mais il est vide et aucun identifiant ne permet encore d'y accéder. Cette partie crée les deux objets indispensables, une clé API et un bucket, puis valide la chaîne complète avec l'AWS CLI : envoi d'un fichier, lecture, lien de partage temporaire, et relecture depuis une autre zone pour vérifier la réplication.

Créer un bucket et une clé API

Garage sépare les concepts de bucket (espace de stockage) et de clé API (identifiant d'accès). Une clé peut avoir accès à plusieurs buckets avec des permissions différentes.

# Créer une clé API
garage key create demo-app-key

==== ACCESS KEY INFORMATION ====
Key ID:              GK54fbf9edf0f36dda7eeb5162
Key name:            demo-app-key
Secret key:          0b2d21f3b2911a8b084a81a65ed9cf1e6ef52bf5ead54cba8a5a0c76d869113a

# Créer un bucket
garage bucket create demo-bucket

# Autoriser la clé sur le bucket (read + write + owner)
garage bucket allow --read --write --owner demo-bucket --key demo-app-key

Vérification :

garage bucket info demo-bucket

==== BUCKET INFORMATION ====
Bucket:          37c984b2c7c9944fa9218b0d3b413d7c671b1a81eab8c9e0389bf4a5e9a29aa3
Global alias:    demo-bucket
Objects:         0

==== KEYS FOR THIS BUCKET ====
Permissions  Access key                                Local aliases
RWO          GK54fbf9edf0f36dda7eeb5162  demo-app-key

Conservez la Secret key

La Secret key n'est affichée qu'une seule fois à la création de la clé. Notez-la immédiatement. Vous pouvez la retrouver avec garage key info --show-secret demo-app-key, mais uniquement depuis un nœud du cluster.

Opérations S3 avec AWS CLI

Configurez AWS CLI pour pointer vers votre cluster Garage :

export AWS_ACCESS_KEY_ID="GK54fbf9edf0f36dda7eeb5162"
export AWS_SECRET_ACCESS_KEY="0b2d21f3b2911a8b084a81a65ed9cf1e6ef52bf5ead54cba8a5a0c76d869113a"
export AWS_DEFAULT_REGION="garage"

# Lister les buckets
aws --endpoint-url http://192.168.122.236:3900 s3 ls
# 2026-03-01 10:35:11 demo-bucket

# Uploader un fichier
echo 'Bonjour depuis le cluster Garage !' > test.txt
aws --endpoint-url http://192.168.122.236:3900 s3 cp test.txt s3://demo-bucket/test.txt
# upload: ./test.txt to s3://demo-bucket/test.txt

# Lister les objets d'un bucket
aws --endpoint-url http://192.168.122.236:3900 s3 ls s3://demo-bucket/
# 2026-03-01 10:36:16         35 test.txt

# Télécharger un objet
aws --endpoint-url http://192.168.122.236:3900 s3 cp s3://demo-bucket/test.txt -
# Bonjour depuis le cluster Garage !

# Supprimer un objet
aws --endpoint-url http://192.168.122.236:3900 s3 rm s3://demo-bucket/test.txt
# delete: s3://demo-bucket/test.txt

Générer une URL de téléchargement temporaire

Les presigned URLs permettent de partager un objet sans exposer les identifiants S3 :

aws --endpoint-url http://192.168.122.236:3900 \
  s3 presign s3://demo-bucket/test.txt --expires-in 3600
# http://192.168.122.236:3900/demo-bucket/test.txt?X-Amz-Algorithm=...

Le lien est valide 1 heure (3600 secondes). N'importe qui peut le télécharger sans clé API.

Vérifier la réplication

L'un des atouts de Garage : les données sont accessibles depuis n'importe quel nœud du cluster, quelle que soit la zone d'upload :

# Upload via garage1
aws --endpoint-url http://192.168.122.236:3900 \
  s3 cp test.txt s3://demo-bucket/test.txt

# Lecture via garage2 (autre zone)
aws --endpoint-url http://192.168.122.115:3900 \
  s3 cp s3://demo-bucket/test.txt -
# Bonjour depuis le cluster Garage !

# Lecture via garage3 (encore une autre zone)
aws --endpoint-url http://192.168.122.5:3900 \
  s3 cp s3://demo-bucket/test.txt -
# Bonjour depuis le cluster Garage !

Héberger un site web statique

Garage peut servir un site directement depuis un bucket, sans reverse proxy supplémentaire. Le module web écoute sur le port 3902 et route les requêtes via l'en-tête Host.

1. Créer le bucket et activer le mode web

   garage bucket create mon-site
   garage bucket allow --read --write --owner mon-site --key demo-app-key
   garage bucket website --allow mon-site

   Vérification :

   garage bucket info mon-site

   Website access:    true
     index document:  index.html
     error document:  (not defined)

2. Uploader le contenu

   cat > index.html << 'HTML'
   <!DOCTYPE html>
   <html>
   <head><title>Mon site sur Garage</title></head>
   <body>
     <h1>Site hébergé sur Garage</h1>
     <p>Stockage S3 distribué, servi directement.</p>
   </body>
   </html>
   HTML
   
   aws --endpoint-url http://192.168.122.236:3900 \
     s3 cp index.html s3://mon-site/index.html --content-type text/html

3. Tester l'accès

   Le module web utilise l'en-tête Host pour identifier le bucket :

   curl -H 'Host: mon-site.web.garage' http://192.168.122.236:3902/

   <!DOCTYPE html>
   <html>
   <head><title>Mon site sur Garage</title></head>
   <body>
     <h1>Site hébergé sur Garage</h1>
     <p>Stockage S3 distribué, servi directement.</p>
   </body>
   </html>

DNS + reverse proxy en production

En production, configurez un enregistrement DNS wildcard (*.web.garage → IP du nœud) et un reverse proxy (Nginx, Traefik, Caddy) devant le port 3902 pour gérer le TLS. Garage peut aussi servir directement si vous configurez root_domain avec votre vrai domaine.

Commandes essentielles

Voici les commandes utiles au quotidien, regroupées par objet manipulé. Toutes s'exécutent depuis un nœud du cluster : la CLI garage lit le fichier /etc/garage.toml local pour joindre l'API d'administration, elle ne fonctionne pas depuis un poste extérieur sans configuration supplémentaire.

Cluster et nœuds

Ces commandes portent sur la topologie. Retenez que layout assign n'a aucun effet tant que layout apply n'a pas été lancé avec le bon numéro de version.

# Statut du cluster (commande la plus utilisée)
garage status

# Identifiant du nœud local
garage node id

# Connecter un nœud
garage node connect <ID>@<IP>:3901

# Afficher le layout actuel
garage layout show

# Modifier la capacité d'un nœud
garage layout assign <ID> -z <zone> -c <capacité> -t <tag>

# Appliquer les changements de layout
garage layout apply --version <N>

# Annuler les changements en attente
garage layout revert

Buckets

Un bucket ne se supprime que s'il est vide, et l'opération est définitive : --yes supprime la demande de confirmation, pas la possibilité d'erreur.

# Lister les buckets
garage bucket list

# Créer un bucket
garage bucket create mon-bucket

# Infos détaillées
garage bucket info mon-bucket

# Activer l'hébergement web
garage bucket website --allow mon-bucket

# Poser des quotas (taille et nombre d'objets)
garage bucket set-quotas mon-bucket --max-size 10G --max-objects 100000

# Supprimer un bucket (doit être vide)
garage bucket delete --yes mon-bucket

Clés API

Les autorisations se posent sur un couple clé/bucket. Révoquer un accès avec deny ne supprime donc pas la clé, qui reste utilisable sur ses autres buckets.

# Lister les clés
garage key list

# Créer une clé
garage key create ma-cle

# Afficher les infos (avec secret)
garage key info --show-secret ma-cle

# Autoriser une clé sur un bucket
garage bucket allow --read --write mon-bucket --key ma-cle

# Révoquer l'accès
garage bucket deny --read --write mon-bucket --key ma-cle

# Supprimer une clé
garage key delete --yes ma-cle

Maintenance

Le scrub relit les blocs stockés sur disque pour détecter une corruption silencieuse. Il s'exécute en tâche de fond et peut durer plusieurs heures sur un volume important, d'où la commande de suivi dédiée.

# Lancer un scrub de vérification des données
garage repair scrub start

# Vérifier le statut du scrub
garage repair scrub status

# Snapshot des métadonnées
garage meta snapshot

Sécurité

La sécurité d'un cluster Garage repose sur deux éléments : le secret RPC que partagent les nœuds, et la segmentation réseau des quatre ports. Les clés API protègent l'accès S3, mais elles ne servent plus à rien dès qu'un attaquant peut se présenter comme un nœud légitime du cluster.

Clé RPC partagée

Le rpc_secret dans garage.toml est la seule barrière d'authentification entre les nœuds du cluster. Si cette clé est compromise, un attaquant peut rejoindre le cluster.

Pratique	Description
Secret RPC fort	Générer avec openssl rand -hex 32 (256 bits)
Fichier protégé	chmod 600 /etc/garage.toml, seul root doit le lire
Réseau dédié	Isoler le port RPC (3901) sur un VLAN interne
Pare-feu	Exposer uniquement 3900 (S3) aux clients, bloquer 3901/3903 de l'extérieur
TLS	Placer un reverse proxy TLS devant le port 3900 pour les clients
Clés API	Créer une clé par application avec les droits minimaux

Glissez pour voir

Port admin (3903)

Le port 3903 expose l'API d'administration et les métriques Prometheus. Ne l'exposez jamais sur Internet. En production, limitez l'écoute à 127.0.0.1:3903 ou filtrez via le pare-feu.

Dépannage

Les incidents se répartissent en deux familles : le cluster ne se forme pas (secret RPC divergent, port bloqué, layout jamais appliqué), ou l'accès aux données échoue (permissions de clé, nombre de nœuds insuffisant). Le tableau donne la correction, les commandes qui suivent servent à confirmer le diagnostic.

Problèmes courants et solutions

Les deux premières lignes couvrent l'essentiel des blocages rencontrés au premier déploiement : un service qui ne démarre pas, ou un layout resté à l'état de proposition.

Symptôme	Cause probable	Solution
garage status affiche 0 nœuds	Le service ne tourne pas	sudo systemctl status garage puis vérifier les logs : journalctl -u garage
Nœud visible mais NO ROLE ASSIGNED	Layout non appliqué	garage layout assign + garage layout apply --version N
Connection refused sur le port 3901	Pare-feu ou mauvaise IP	Vérifier rpc_public_addr et ufw allow 3901/tcp
Unauthorized sur l'API S3	Clé API incorrecte ou pas de permission	Vérifier garage key info et garage bucket allow
Upload OK mais lecture échoue	replication_factor=3 avec moins de 3 nœuds up	Vérifier garage status, attendre la re-synchronisation
rpc_secret mismatch dans les logs	Secrets RPC différents entre nœuds	Vérifier que /etc/garage.toml a le même rpc_secret partout
Layout version mismatch	Layout non propagé	Relancer garage layout apply --version N
Site web renvoie 404	Pas de fichier index.html ou web non activé	garage bucket website --allow et vérifier le upload

Glissez pour voir

Commandes de diagnostic

Lancez-les dans cet ordre : les logs du service donnent la cause immédiate, garage status montre le cluster tel que ce nœud le perçoit, le scrub vérifie l'intégrité des blocs, et l'endpoint /metrics expose les compteurs au format Prometheus.

# Logs du service
sudo journalctl -u garage -f --no-pager

# Statut détaillé du cluster
garage status

# Vérifier l'intégrité des données
garage repair scrub start
garage repair scrub status

# Vérifier les métriques (si admin API activée)
curl http://localhost:3903/metrics

Bonnes pratiques

Les recommandations qui suivent traitent trois sujets distincts qu'on confond souvent : le dimensionnement matériel, l'organisation du cluster et le réglage des performances. Elles supposent un cluster déjà fonctionnel ; appliquées trop tôt, elles compliquent le diagnostic en cas de problème.

Dimensionnement

La colonne « minimum » suffit largement pour le lab. En production, c'est le débit entre les zones qui limite le plus souvent, rarement le processeur : chaque écriture doit être confirmée par une majorité de nœuds avant d'être acquittée.

Composant	Minimum (test)	Recommandé (production)
Nœuds	3	3+ (au moins 3 zones)
RAM par nœud	512 Mo	1-2 Go
CPU	1 vCPU	2+ vCPU
Réseau	100 Mbps	1 Gbps+ entre zones
Disque	HDD	SSD pour les métadonnées, HDD pour les données

Glissez pour voir

Organisation

Ces cinq règles portent sur la structure du cluster. Les deux premières touchent au stockage physique et aux identités : les corriger après coup impose une migration de données ou une rotation de clés.

• Séparer métadonnées et données sur des disques différents en production : SSD pour metadata_dir (accès aléatoire intense), HDD pour data_dir (accès séquentiel).
• Une clé API par application : ne pas partager les clés entre services.
• Nommer les tags pour identifier les nœuds : garage layout assign <ID> -t "paris-srv01".
• 3 zones minimum avec replication_factor = 3 pour une vraie tolérance aux pannes de site.
• Snapshots automatiques des métadonnées : metadata_auto_snapshot_interval (6h par défaut) crée des sauvegardes du fichier LMDB.

Performance

Trois paramètres du garage.toml ont un effet mesurable. Ils se modifient sur chaque nœud puis exigent un redémarrage du service. Attention au block_size : il s'applique aux nouveaux envois seulement, les objets déjà stockés conservent leur découpage d'origine.

• compression_level = 1 (zstd rapide) est un bon compromis. Passez à 0 pour du contenu déjà compressé (images, vidéos, archives).
• block_size = "1M" (défaut) convient à la plupart des workloads. Augmentez à 4M ou 64M pour des fichiers volumineux.
• consistency_mode = "degraded" si la disponibilité prime sur la cohérence stricte (lectures servies même si un nœud est down, sans vérifier le quorum).

À retenir

• Garage = stockage S3 ultra-léger : un seul binaire Rust, ~50 Mo de RAM, aucune dépendance.
• Géo-distribution native : les zones garantissent que chaque copie est stockée sur un site différent.
• Pas de maître : tous les nœuds sont égaux, le hash ring distribue les données.
• 3 commandes suffisent pour un cluster : node connect, layout assign, layout apply.
• API S3 standard : fonctionne avec AWS CLI, MinIO Client, Rclone, Restic.
• Hébergement web intégré : servez un site statique directement depuis un bucket.
• Idéal pour : sauvegardes, stockage Nextcloud, artefacts CI/CD, sites statiques, partage de fichiers.
• Pas adapté pour : stockage bloc (VM), systèmes de fichiers POSIX, workloads haute performance à faible latence.

Prochaines étapes

MinIO : stockage objet haute performance Alternative plus performante pour du S3 sur un seul site

Ceph : stockage distribué unifié Pour du stockage objet, bloc ET fichier dans un même cluster

GlusterFS : stockage fichier distribué Stockage fichier partagé en réseau avec réplication

NFS : partage de fichiers réseau Partage simple pour les environnements locaux

Comparatif des alternatives S3 Garage face aux autres moteurs S3 : où placer un store léger géo-distribué

Ressources

• Site officiel : garagehq.deuxfleurs.fr
• Documentation : garagehq.deuxfleurs.fr/documentation
• Releases : git.deuxfleurs.fr/Deuxfleurs/garage/releases
• Code source : git.deuxfleurs.fr/Deuxfleurs/garage
• Matrix : #garage:deuxfleurs.fr

×

📖 Voir la documentation →