Garage - Stockage d'objets compatible S3 Quickstart
Exécuter Garage avec Docker en quelques minutes
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 démarrage rapide vous mène d’une configuration simple à copier-coller à des modèles adaptés à la production : mise en œuvre de cluster, réplication, TLS via un proxy inverse, stockages arrière-plan multi-disk, 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.
Ce que Garage est
Garage est un stockage objet distribué compatible S3 destiné à l’hébergement local, visant à rester léger et simple à opérer tout en supportant des clusters multi-site/géodistribués.
Il est publié sous la licence AGPL v3.
Les idées clés qui façonnent la manière dont vous l’exploitez :
Garage mesure la capacité des nœuds et leur localisation 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 forme versionnées et un 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 blocs sont utilisés pour le placement 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 »), et est ensuite servi par des nœuds de stockage qui contiennent des blocs de données répliqués.
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 (ex. : réplication à 3 voies à travers les zones), avec des compromis clairs en termes d’accessibilité/résilience décrits dans la référence de configuration.
Démarrage rapide copier-coller
Il s’agit d’un déploiement intentionnellement minimal unique-nœud pour apprendre les workflows : configuration → démarrer le serveur → définir la mise en forme → créer un bucket + une 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 unique-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 de 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). Des 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 l'interface 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 "AUCUN RÔLE ASSIGNÉ")
garage status
# 6) Assigner une mise en forme (unique nœud) et l'appliquer
NODE_ID="$(garage status | awk '/AUCUN RÔLE ASSIGNÉ/{print $1; exit}')"
garage layout assign -z dc1 -c 1G "$NODE_ID"
garage layout apply --version 1
# 7) Créer un bucket + une clé et accorder les autorisations 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é (sauvegardez-le 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 d’administration sur 3903) et le workflow « mise en forme requise » proviennent directement du guide de démarrage rapide upstream.
Valider avec AWS CLI
Garage exige que les clients utilisent la région configurée (s3_region, 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 démarrage rapide upstream recommande d’utiliser un fichier ~/.awsrc pour basculer entre les points de terminaison/clés et note les versions minimales de 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 : le téléchargement de binaires depuis la page de téléchargement de Garage, l’utilisation de paquets de distribution (ex. : apk add garage sur Alpine), ou la construction depuis la source si nécessaire.
Docker et Docker Compose
Garage fournit des images conteneur et documente une méthode minimale docker run pour les utilisations de démarrage 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 progressifs). Le guide « déploiement sur un cluster » de Garage suppose Docker sur chaque nœud et indique les chemins d’hôte courants et la recommandation de SSD pour les métadonnées.
systemd
Garage documente un déploiement renforcé avec systemd, y compris les précautions autour de DynamicUser= de systemd et l’emplacement des états persistants sur le disque.
Un exemple minimal de fichier unité (adaptez les chemins à votre environnement) :
# /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 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 forme 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 forme 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 situer sur un HDD plus grand.
Pour les nœuds avec plusieurs disques de données, Garage supporte une configuration multi-disk data_dir 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 ne met pas en œuvre des ACLs ou des politiques de bucket du style AWS ; il utilise son propre système de permissions « par clé d’accès par bucket » géré via l’interface CLI Garage / API d’administration.
Cela signifie que la « politique » que vous traduisez généralement en Garage est : quelle clé d’accès a les autorisations de lecture/écriture/propriétaire sur quels 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 en style chemin
Garage peut supporter l’accès en style hôte virtuel (DNS) aux buckets si vous configurez [s3_api].root_domain ; le style de chemin est toujours activé.
Si vous ne configurez pas le style hôte virtuel (DNS sauvage + éventuellement TLS sauvage), beaucoup de clients peuvent fonctionner en forçant le style de chemin, et la documentation Garage montre des exemples de clients avec force_path_style = true.
TLS
Les points de terminaison API S3 et web de Garage ne supportent pas directement le TLS ; la recommandation officielle est de placer un proxy inverse devant, généralement Nginx, pour servir 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 les clés de chiffrement dans les en-têtes par demande ; Garage chiffre en place et supprime la clé après la demande.
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/demande plutôt que par défaut de bucket.
Opération de Garage en production
Surveillance et journalisation
Garage expose des métriques au format Prometheus et supporte l’exportation des traces au format OpenTelemetry.
Les points de terminaison d’administration et de 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 un « nettoyage » en arrière-plan (vérification d’intégrité) et des outils de réparation ; les nettoyages peuvent être lancés manuellement et surveillés via les commandes worker/task, mais ils sont intensifs en disque et peuvent ralentir le cluster.
Les changements de topologie et d’ajustements de capacité sont gérés via la gestion de mise en forme ; les opérations sont appliquées comme nouvelles versions de mise en forme.
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/dossiers spécifiques de chaque nœud metadata_dir (y compris les sauvegardes et les fichiers de mise en forme).
Pour les données d’objets, traitez Garage comme tout point de terminaison S3 : utilisez des outils de sauvegarde compatibles S3 (ex. : restic, duplicity) ciblant un bucket Garage, comme documenté sur la page « Sauvegardes » d’intégration de Garage.
Notes de dépannage pour les erreurs courantes
AUCUN RÔLE ASSIGNÉ dans garage status signifie généralement que vous n’avez pas encore créé/appliqué une mise en forme. 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/demande peuvent être causés par un désaccord entre le style de chemin et le style d’hôte virtuel ; configurez [s3_api].root_domain pour le style d’hôte virtuel, ou forcez le style de chemin dans les clients (ex. : force_path_style=true avec rclone).
Les erreurs de permission sont fréquemment simplement « clé non autorisée sur bucket » ; inspectez avec garage bucket info <bucket> et assurez-vous que garage bucket allow a les bonnes options.
Notes de réglage des performances qui comptent le plus
Placez metadata_dir sur un SSD si possible ; la documentation Garage mentionne des temps de réponse améliorés et un 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 rationnelles, mais la référence de configuration explique les 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 en évidence les coûts de la latence inter-cluster dans les configurations géodistribuées et soulignent les choix de conception (ex. : éviter les chefs 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 quelques lacunes délibérées en matière de fonctionnalités S3 (ex. : 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 verrouillage des objets, 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 objectifs de disponibilité de 99,99 %, ainsi qu’un écosystème de fonctionnalités large (classes de stockage, cycle de vie, événement, IAM).
Pour plus de détails, veuillez consulter Comparaison Garage vs MinIO vs AWS S3.
En savoir plus sur MinIO :
- MinIO en tant qu’alternative à AWS S3. Aperçu et installation de MinIO
- Fiche de raccourcis des paramètres en ligne de commande MinIO
