Garaje - Almacenamiento de objetos compatible con S3 Guía de inicio rápido

Ejecute Garage en Docker en minutos

Índice

Garage es un sistema de almacenamiento de objetos compatible con S3, de código abierto y autohospedado, diseñado para despliegues pequeños a medianos, con un fuerte énfasis en la resiliencia y la distribución geográfica.

Este tutorial rápido te guiará desde un despliegue de nodo único con copiar/pegar hasta patrones orientados a producción: distribución del clúster, replicación, TLS mediante proxy inverso, almacenamientos de disco múltiples, monitoreo, reparaciones y copia de seguridad/restauración.

Para una visión general—almacenamiento de objetos, PostgreSQL, Elasticsearch y capas de datos nativas para IA—consulta el artículo Infraestructura de datos para sistemas de IA.

Cajas de Garage

¿Qué es Garage

Garage es un almacén distribuido compatible con S3 diseñado para autohospedarse, buscando mantenerse ligero y sencillo de operar, mientras soporta clústeres multisinistro/distribuidos geográficamente.
Se libera bajo la licencia AGPL v3.

Ideas clave que definen cómo se ejecuta:

Garage mide la capacidad del nodo y la ubicación física (“zonas”) para colocar réplicas; los cambios en la topología del clúster (añadir/eliminar nodos) se manejan a través de diseños versionados y reequilibrio.
Los objetos se dividen en bloques de tamaño fijo (block_size), lo que permite la deduplicación y la compresión opcional con Zstandard; los hashes de bloques se utilizan para colocamiento y deduplicación.
Garage no termina el TLS en sus puntos finales de API de S3/web: se espera que despliegues un proxy inverso para HTTPS en despliegues reales.

Arquitectura y flujo de datos

A un alto nivel, interactúas con Garage a través de clientes compatibles con S3; el tráfico generalmente entra a través de un proxy inverso (TLS), llega a uno o más puntos finales de API de Garage (a menudo nodos “gateway”), y luego es servido por nodos de almacenamiento que contienen bloques de datos replicados.

flujo de datos del clúster Garage

Los nodos tienen roles: nodos de almacenamiento con capacidad versus nodos gateway que exponen puntos finales sin almacenar datos; los gateways reducen la latencia evitando saltos de red adicionales y al “conocer” qué nodos de almacenamiento consultar.
La replicación se controla mediante replication_factor (por ejemplo, replicación de 3 vías a través de zonas), con claros intercambios de disponibilidad/ tolerancia a fallos descritos en la referencia de configuración.

Rápido inicio con copiar/pegar

Este es un despliegue intencionalmente mínimo de único nodo para aprender los flujos de trabajo: configuración → iniciar servidor → definir diseño → crear cubo + clave → subir un objeto.

Requisitos previos

Necesitas docker, openssl y (opcionalmente) un cliente S3 como awscli. El CLI de Garage es el mismo binario utilizado para administrar el clúster.

Paso a paso

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

# 1) Crear una configuración inicial (rutas persistentes dentro del contenedor)
cat > ./config/garage.toml <<EOF
metadata_dir = "/var/lib/garage/meta"
data_dir     = "/var/lib/garage/data"
db_engine = "sqlite"

# Despliegue de aprendizaje de único nodo (NINGUNA redundancia). Para producción, ver más adelante.
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"
# Opcional estilo vhost. El estilo de ruta siempre está habilitado.
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) Elegir una etiqueta de imagen (placeholder). Ejemplos de etiquetas aparecen en los documentos de Garage.
GARAGE_IMAGE="dxflrs/garage:TAG_PLACEHOLDER"

# 3) Ejecutar 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) Usar el CLI de garage dentro del contenedor
alias garage='docker exec -ti garaged /garage'

# 5) Verificar el estado del nodo (probablemente verás "NO ROLE ASSIGNED")
garage status

# 6) Asignar un diseño (único nodo) y aplicarlo
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) Crear un cubo + clave y conceder permisos de mínimo 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) Mostrar el material de la clave (guárdalo de forma segura)
garage key info example-app-key

El patrón de configuración (API de S3 en 3900, RPC en 3901, punto final web en 3902, API de administración en 3903) y el flujo de trabajo “requiere diseño” provienen directamente del tutorial rápido de la fuente.

Validar con AWS CLI

Garage requiere que los clientes usen la s3_region configurada (a menudo “garage”); si tu cliente usa us-east-1, podrías obtener redirecciones de AuthorizationHeaderMalformed.

# Instalar (una opción)
python -m pip install --user awscli

# Configurar entorno (ejemplo)
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

El tutorial rápido de la fuente recomienda usar un archivo ~/.awsrc para cambiar entre puntos finales/llaves y menciona las versiones mínimas de AWS CLI para manejar cómodamente los puntos finales.

Opciones de instalación y despliegue

Instalaciones binarias y paquetes

Los documentos de Garage respaldan explícitamente: descargando binarios desde la página de descarga de Garage, usando paquetes de distribución (por ejemplo, apk add garage en Alpine), o construyendo desde la fuente si es necesario.

Docker y Docker Compose

Garage proporciona imágenes de contenedor y documenta un método minimalista docker run para uso rápido.
Para producción, generalmente usarás compose (o un orquestador) para gestionar almacenamiento persistente, proxy inverso y actualizaciones (reinicios suaves). La guía de “despliegue en un clúster” de Garage supone Docker en cada nodo y señala las rutas de host comunes y la recomendación de SSD para metadatos.

systemd

Garage documenta un despliegue reforzado con systemd, incluyendo advertencias sobre DynamicUser= de systemd y dónde termina el estado persistente en el disco.
Un ejemplo mínimo de unidad (ajusta las rutas según tu entorno):

# /etc/systemd/system/garage.service
[Unit]
Description=Almacenamiento de objetos compatible con S3 de Garage
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 y Helm

Garage incluye un gráfico de Helm en el repositorio y tiene páginas oficiales de documentación para despliegues en Kubernetes.
Un error común es que aún debes configurar/ aplicar un diseño de clúster después de instalar (puedes automatizarlo con un trabajo de Kubernetes).

Configuración, seguridad y TLS

Almacenes de backend y disposición de disco

Garage divide el almacenamiento en metadata_dir y data_dir. La referencia de configuración recomienda colocar metadata_dir en un SSD rápido para mejorar los tiempos de respuesta, mientras que data_dir puede estar en un HDD más grande.
Para nodos con múltiples discos de datos, Garage admite una configuración data_dir de múltiples discos con capacidades por ruta y equilibrio automático.

# Ejemplo: múltiples HDDs para bloques de datos
metadata_dir = "/mnt/ssd/garage-meta"
data_dir = [
  { path = "/mnt/hdd1/garage-data", capacity = "8T" },
  { path = "/mnt/hdd2/garage-data", capacity = "8T" },
]

Modelo de control de acceso vs políticas de cubo de S3

Garage no implementa ACLs o políticas de cubo de estilo AWS; utiliza su propio sistema de permisos “por clave de acceso por cubo” gestionado a través del CLI de Garage / API de administración.
Esto significa que la “política” que generalmente traduces a Garage es: ¿qué clave de acceso tiene permiso de lectura/escritura/propietario en qué cubo(s)?.

# Clave de solo lectura para un cubo:
garage key create ro-key
garage bucket allow --read example-bucket --key ro-key

# Eliminar acceso:
garage bucket deny example-bucket --key ro-key

Dirección de cubo de estilo DNS vs estilo de ruta

Garage puede admitir virtual-host (DNS) estilo de acceso a cubos si configuras [s3_api].root_domain; el estilo de ruta siempre está habilitado.
Si no configuras el estilo de vhost (DNS silbante + posiblemente TLS silbante), muchos clientes pueden funcionar forzando el estilo de ruta, y la documentación de Garage muestra ejemplos de clientes con force_path_style = true.

TLS

La API de S3 y los puntos finales web de Garage no admiten directamente TLS; la guía oficial recomienda colocar un proxy inverso delante, comúnmente Nginx, para servir HTTPS y multiplexar servicios en el puerto 443.

Un contorno mínimo de Nginx (ver la guía oficial de proxy inverso para un ejemplo completo):

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

Encriptación del lado del servidor

Garage admite S3 SSE-C (“encriptación del lado del servidor con claves proporcionadas por el cliente”): el cliente envía claves de encriptación en encabezados por solicitud; Garage encripta en reposo y descarta la clave después de la solicitud.
La tabla de compatibilidad de S3 de Garage también señala que no se implementan puntos finales de configuración de encriptación a nivel de cubo, por lo tanto, trate SSE-C como comportamiento por objeto/solicitud en lugar de valores predeterminados de cubo.

Operar Garage en producción

Monitoreo y registro

Garage expone métricas en formato Prometheus y admite la exportación de trazas en formato OpenTelemetry.
Los puntos finales de administración y métricas pueden protegerse mediante tokens (admin_token, metrics_token y metrics_require_token), y la trazabilidad puede exportarse mediante trace_sink (OTLP).
Para el registro, Garage puede ajustarse mediante RUST_LOG, y la referencia de configuración documenta variables de entorno para enviar registros a syslog/journald en lugar de stderr.

Durabilidad, reparaciones y tareas de mantenimiento comunes

Garage incluye “scrub” en segundo plano (verificación de integridad) y herramientas de reparación; los scrubs pueden iniciarse manualmente y monitorearse mediante comandos de trabajador/tarea, pero son intensivos en disco y pueden ralentizar el clúster.
Los cambios en la topología y ajustes de capacidad se manejan mediante gestión de diseño; las operaciones se aplican como nuevas versiones de diseño.

Estrategia de copia de seguridad y restauración

Como mínimo, respalda metadatos, ya que contienen la configuración del clúster, el estado del cubo/clave y los índices. Garage admite copias de seguridad periódicas de metadatos (metadata_auto_snapshot_interval) y copias de seguridad manuales (garage meta snapshot --all).
La guía de migración de Garage recomienda explícitamente respaldar archivos/directorios específicos de cada nodo en metadata_dir (incluyendo copias de seguridad y archivos de diseño).

Para los datos del objeto, trata Garage como cualquier punto final de S3: usa herramientas de copia de seguridad compatibles con S3 (por ejemplo, restic, duplicity) que apunten a un cubo de Garage, como se documenta en la página de integración de “Backups” de Garage.

Notas de solución de problemas comunes

NO ROLE ASSIGNED en garage status generalmente significa que no has creado/aplicado un diseño aún. Solución: garage layout assign … seguido de garage layout apply.
AuthorizationHeaderMalformed suele indicar que el cliente está usando la región equivocada; establece AWS_DEFAULT_REGION (o equivalente) para coincidir con [s3_api].s3_region.
Los errores de firma/solicitud pueden deberse a un desajuste entre estilo de ruta y estilo de vhost; configura [s3_api].root_domain para estilo de vhost, o fuerza el estilo de ruta en los clientes (por ejemplo, force_path_style=true en rclone).
Los errores de permisos suelen ser simplemente “clave no permitida en cubo”; inspecciona con garage bucket info <bucket> y asegúrate de que garage bucket allow tenga las banderas correctas.

Notas de ajuste de rendimiento más importantes

Coloca metadata_dir en un SSD cuando sea posible; los documentos de Garage destacan una mejora en los tiempos de respuesta y un potencial de reducción drástica en la latencia.
Ajusta block_size y compresión con cuidado: los valores predeterminados de Garage están diseñados para ser razonables, pero la referencia de configuración explica el intercambio y señala que los cambios solo se aplican a los datos subidos recientemente.
Si tienes NVMe, aumentar la concurrencia de escritura de bloques puede mejorar el rendimiento pero incrementa el uso de memoria; Garage proporciona orientación para block_max_concurrent_writes_per_request.
Los propios benchmarks de Garage destacan los costos de la latencia intra-clúster en configuraciones distribuidas geográficamente, y resaltan decisiones de diseño (por ejemplo, evitar líderes de consenso) que pueden reducir el impacto de la latencia geográfica.

Comparación breve con MinIO y AWS S3

Garage está optimizado para clústeres autohospedados y distribuidos geográficamente, con simplicidad operativa, con algunas lagunas deliberadas en características de S3 (por ejemplo, no hay políticas/ACLs de cubo de S3; soporte limitado de versiones).
MinIO se centra en el alcance de la API de S3 y en despliegues empresariales de alto rendimiento (por ejemplo, los propios materiales de MinIO describen características como bloqueo de objetos, replicación y notificaciones de eventos).
AWS S3 es la implementación gestionada con consistencia fuerte, durabilidad de 11 nueves y objetivos de disponibilidad del 99,99%, y un ecosistema de características amplio (clases de almacenamiento, ciclo de vida, eventos, IAM).

Más sobre Minio:

Enlaces útiles