Garage - Guia Rápido de Armazenamento de Objetos Compatível com S3

Execute o Garage em minutos com Docker

Conteúdo da página

Garage é um sistema de armazenamento de objetos de código aberto, auto-hospedado e compatível com S3, projetado para implantações de pequeno a médio porte, com forte ênfase em resiliência e distribuição geográfica.

Este rápido início o conduz de uma configuração de nó único (copiar/colar) até padrões voltados para produção: layout de cluster, replicação, TLS via proxy reverso, backends de armazenamento multi-disco, monitoramento, reparos e backup/restauração.

Para uma visão mais ampla — armazenamento de objetos, PostgreSQL, Elasticsearch e camadas de dados nativas de IA — veja o artigo Infraestrutura de Dados para Sistemas de IA.

Garage Boxes

O que é o Garage

O Garage é um armazenamento de objetos distribuído compatível com S3 destinado à auto-hospedagem, com o objetivo de manter-se leve e simples de operar, ao mesmo tempo que suporta clusters multi-site/distribuídos geograficamente. É lançado sob a licença AGPL v3.

Ideias-chave que moldam como você o opera:

O Garage mede a capacidade do nó e a localização física (“zonas”) para posicionar réplicas; as mudanças na topologia do cluster (adicionar/remover nós) são tratadas por meio de layouts versionados e rebalanceamento. Os objetos são divididos em blocos de tamanho fixo (block_size), o que permite deduplicação e compressão Zstandard opcional; os hashes dos blocos são usados para posicionamento e deduplicação. O Garage não encerra TLS em suas APIs S3/endpoints web: espera-se que você deploye um proxy reverso para HTTPS em implantações reais.

Arquitetura e fluxo de dados

Em um nível alto, você interage com o Garage através de clientes compatíveis com S3; o tráfego geralmente entra via um proxy reverso (TLS), chega a um ou mais endpoints de API do Garage (frequentemente nós “gateway”) e então é servido por nós de armazenamento que mantêm os blocos de dados replicados.

garage- cluster data flow

Os nós têm papéis: nós de armazenamento com capacidade versus nós gateway que expõem endpoints sem armazenar dados; os gateways reduzem a latência evitando saltos de rede extras e “sabendo” quais nós de armazenamento consultar. A replicação é controlada via replication_factor (por exemplo, replicação tripla entre zonas), com compensações claras de disponibilidade/tolerância a falhas descritas na referência de configuração.

Rápido início copiar/colar

Este é uma implantação de nó único intencionalmente mínima para aprender os fluxos de trabalho: configuração → iniciar servidor → definir layout → criar bucket + chave → fazer upload de um objeto.

Pré-requisitos

Você precisa de docker, openssl e (opcionalmente) um cliente S3 como awscli. A CLI do Garage é o mesmo binário usado para administrar o cluster.

Passo a passo

# 0) Área de trabalho
mkdir -p ~/garage-quickstart/{config,meta,data}
cd ~/garage-quickstart

# 1) Criar uma configuração inicial (caminhos persistentes dentro do container)
cat > ./config/garage.toml <<EOF
metadata_dir = "/var/lib/garage/meta"
data_dir     = "/var/lib/garage/data"
db_engine = "sqlite"

# Implantação de aprendizado de nó único (SEM redundância). Para produção, veja abaixo.
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"
# Estilo vhost opcional. Estilo de caminho sempre 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) Escolher uma tag de imagem (placeholder). Tags de exemplo aparecem na documentação do Garage.
GARAGE_IMAGE="dxflrs/garage:TAG_PLACEHOLDER"

# 3) Executar o 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 a CLI do garage dentro do container
alias garage='docker exec -ti garaged /garage'

# 5) Verificar o status do nó (provavelmente verá "NO ROLE ASSIGNED")
garage status

# 6) Atribuir um layout (nó único) e aplicá-lo
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) Criar um bucket + chave e conceder permissões de menor privilégio
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 o material da chave (salve com segurança)
garage key info example-app-key

O padrão de configuração (API S3 em 3900, RPC em 3901, endpoint web em 3902, API de admin em 3903) e o fluxo de trabalho “layout necessário” vêm diretamente do quickstart upstream.

Validar com AWS CLI

O Garage exige que os clientes usem o s3_region configurado (geralmente “garage”); se o seu cliente usar us-east-1, você pode encontrar redirecionamentos AuthorizationHeaderMalformed.

# Instalar (uma opção)
python -m pip install --user awscli

# Configurar variáveis de ambiente (exemplo)
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

O quickstart upstream recomenda usar um arquivo ~/.awsrc para alternar entre endpoints/keys e observa as versões mínimas do AWS CLI para manipulação conveniente de endpoints.

Opções de instalação e implantação

Instalações de binários e pacotes

A documentação do Garage suporta explicitamente: baixar binários da página de downloads do Garage, usar pacotes de distribuição (ex., apk add garage no Alpine) ou compilar do código-fonte se necessário.

Docker e Docker Compose

O Garage fornece imagens de container e documenta um método docker run mínimo para uso de quickstart. Para produção, você tipicamente usará compose (ou um orquestrador) para gerenciar armazenamento persistente, proxy reverso e atualizações (reinícios rolantes). O guia “implantação em cluster” do Garage assume Docker em cada nó e destaca os caminhos comuns do host e a recomendação de SSD para metadados.

systemd

O Garage documenta uma implantação de systemd endurecida, incluindo advertências sobre DynamicUser= do systemd e onde o estado persistente termina no disco. Um exemplo de unidade mínimo (adapte caminhos ao seu 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

O Garage entrega um chart Helm no repositório e tem páginas de documentação oficial para implantação no Kubernetes. Um problema comum é que você ainda deve inicializar/aplicar um layout de cluster após a instalação (você pode automatizá-lo com um Job do Kubernetes).

Configuração, segurança e TLS

Backends de armazenamento e layout de disco

O Garage divide o armazenamento em metadata_dir e data_dir. A referência de configuração recomenda colocar metadata_dir em um SSD rápido para melhorar os tempos de resposta, enquanto data_dir pode ficar em um HDD maior. Para nós com múltiplos drives de dados, o Garage suporta uma configuração de data_dir multi-disco com capacidades por caminho e balanceamento automático.

# Exemplo: múltiplos HDDs para blocos de dados
metadata_dir = "/mnt/ssd/garage-meta"
data_dir = [
  { path = "/mnt/hdd1/garage-data", capacity = "8T" },
  { path = "/mnt/hdd2/garage-data", capacity = "8T" },
]

Modelo de controle de acesso vs políticas de bucket S3

O Garage não implementa ACLs ou políticas de bucket estilo AWS; ele usa seu próprio sistema de permissões “por chave de acesso por bucket” gerenciado através da CLI do Garage / API de admin. Isso significa que a “política” que você geralmente traduz para o Garage é: qual chave de acesso obtém leitura/escrita/dono em quais bucket(s).

# Chave de apenas leitura para um bucket:
garage key create ro-key
garage bucket allow --read example-bucket --key ro-key

# Remover acesso:
garage bucket deny example-bucket --key ro-key

Endereçamento de bucket estilo DNS vs estilo de caminho

O Garage pode suportar acesso a bucket estilo virtual-host (DNS) se você configurar [s3_api].root_domain; o estilo de caminho sempre está habilitado. Se você não configurar o estilo vhost (DNS wildcard + possivelmente TLS wildcard), muitos clientes podem ser feitos para funcionar forçando o estilo de caminho, e a documentação do Garage mostra exemplos de clientes com force_path_style = true.

TLS

As APIs S3 e endpoints web do Garage não suportam TLS diretamente; a orientação oficial é colocar um proxy reverso na frente, comumente Nginx, para servir HTTPS e multiplexar serviços na porta 443.

Uma forma mínima de Nginx (veja o cookbook oficial de proxy reverso para um exemplo completo):

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

Criptografia do lado do servidor

O Garage suporta S3 SSE-C (“criptografia do lado do servidor com chaves fornecidas pelo cliente”): o cliente envia chaves de criptografia nos cabeçalhos por solicitação; o Garage criptografa em repouso e descarta a chave após a solicitação. A tabela de compatibilidade S3 do Garage também observa que os endpoints de configuração de criptografia de nível de bucket não são implementados, então trate SSE-C como comportamento por objeto/solicitação em vez de padrões de bucket.

Operando o Garage em produção

Monitoramento e logs

O Garage expõe métricas no formato Prometheus e suporta a exportação de rastros no formato OpenTelemetry. Endpoints de admin e métricas podem ser protegidos por tokens (admin_token, metrics_token e metrics_require_token), e o rastreamento pode ser exportado via trace_sink (OTLP). Para logs, o Garage pode ser ajustado via RUST_LOG, e a referência de configuração documenta variáveis de ambiente para enviar logs para syslog/journald em vez de stderr.

Durabilidade, reparos e tarefas comuns de manutenção

O Garage inclui ferramentas de “limpeza” (verificação de integridade) e reparo em segundo plano; limpezas podem ser iniciadas manualmente e monitoradas via comandos de worker/task, mas são intensivas em disco e podem desacelerar o cluster. Mudanças de topologia e ajustes de capacidade são tratados através do gerenciamento de layout; operações são aplicadas como novas versões de layout.

Estratégia de backup e restauração

No mínimo, faça backup dos metadados, pois contêm a configuração do cluster, estado de bucket/chave e índices. O Garage suporta snapshots periódicos de metadados (metadata_auto_snapshot_interval) e snapshots manuais (garage meta snapshot --all). O guia de migração do Garage recomenda explicitamente fazer backup de arquivos/diretórios específicos do metadata_dir de cada nó (incluindo snapshots e arquivos de layout).

Para dados de objetos, trate o Garage como qualquer endpoint S3: use ferramentas de backup compatíveis com S3 (ex., restic, duplicity) direcionadas a um bucket do Garage, conforme documentado na página de integrações de “Backups” do Garage.

Solução de problemas de erros comuns

NO ROLE ASSIGNED em garage status geralmente significa que você ainda não criou/aplicou um layout. Correção: garage layout assign … então garage layout apply. AuthorizationHeaderMalformed muitas vezes indica que um cliente está usando a região errada; defina AWS_DEFAULT_REGION (ou equivalente) para corresponder a [s3_api].s3_region. Falhas de assinatura/solicitação podem ser causadas por incompatibilidade estilo de caminho vs estilo vhost; configure [s3_api].root_domain para estilo vhost, ou force o estilo de caminho nos clientes (ex., force_path_style=true do rclone). Erros de permissão frequentemente são apenas “chave não permitida no bucket”; inspecione com garage bucket info <bucket> e assegure que garage bucket allow tenha as bandeiras corretas.

Notas de ajuste de desempenho que mais importam

Coloque metadata_dir em SSD quando possível; a documentação do Garage destaca tempos de resposta melhorados e potencial de latência “drasticamente reduzida”. Ajuste block_size e compressão cuidadosamente: os padrões do Garage são destinados a ser sensatos, mas a referência de configuração explica o trade-off e observa que as mudanças se aplicam apenas a dados recém-uploadados. Se você tem NVMe, aumentar a concorrência de escrita de blocos pode melhorar a taxa de transferência, mas aumenta o uso de memória; o Garage fornece orientação para block_max_concurrent_writes_per_request. Os próprios benchmarks do Garage enfatizam os custos de latência intra-cluster em configurações geo-distribuídas e destacam escolhas de design (ex., evitar líderes de consenso) que podem reduzir o impacto da latência geo.

Comparação curta com MinIO e AWS S3

O Garage é otimizado para clusters auto-hospedados e geo-distribuídos e simplicidade operacional, com algumas lacunas deliberadas de recursos S3 (ex., sem políticas de bucket/ACLs S3; suporte de versionamento limitado). MinIO foca na amplitude da API S3 e implantações corporativas de alto desempenho (por exemplo, os próprios materiais do MinIO descrevem recursos como bloqueio de objeto, replicação e notificações de eventos). AWS S3 é a implementação de referência gerenciada com forte consistência, 11 noves de durabilidade e metas de disponibilidade de 99.99%, e um amplo ecossistema de recursos (classes de armazenamento, ciclo de vida, eventos, IAM).

Para mais detalhes, veja Comparação Garage vs MinIO vs AWS S3.

Mais sobre Minio: