Garagem - Armazenamento de objetos compatível com S3 Quickstart

Execute o Garage no Docker em minutos

Conteúdo da página

Garage é um sistema de armazenamento de objetos compatível com S3, open-source e auto-hospedado, projetado para implantações pequenas a médias, com uma forte ênfase em resiliência e distribuição geográfica.

Este quickstart guia você desde uma configuração de único nó com cópia/colagem até padrões orientados para produção: layout de cluster, replicação, TLS via proxy reverso, backends de armazenamento com múltiplos discos, monitoramento, reparos e backup/restauração.

Para o quadro geral — armazenamento de objetos, PostgreSQL, Elasticsearch e camadas de dados nativas para IA — veja o artigo Infraestrutura de Dados para Sistemas de IA.

Boxes do Garage

O que é o Garage

O Garage é um armazenamento distribuído de objetos compatível com S3 destinado ao auto-hospedamento, visando permanecer leve e simples de operar, enquanto suporta clusters multi-sítio/distribuídos geograficamente.
É liberado sob a licença AGPL v3.

Ideias-chave que moldam como você o opera:

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

Arquitetura e fluxo de dados

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

fluxo de dados do cluster Garage

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 adicionais e ao “saberem” quais nós de armazenamento consultar.
A replicação é controlada por meio de replication_factor (por exemplo, replicação de 3 vias entre zonas), com trade-offs claros de disponibilidade/tolerância a falhas descritos na referência de configuração.

Quickstart com cópia/colagem

Este é um depósito intencionalmente mínimo de único nó para aprender os fluxos de trabalho: configuração → iniciar servidor → definir layout → criar bucket + chave → carregar um objeto.

Pré-requisitos

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

Passo a passo

# 0) Espaço de trabalho
mkdir -p ~/garage-quickstart/{config,meta,data}
cd ~/garage-quickstart

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

# Implantação de único nó para aprendizado (SEM redundância). Para produção, veja mais tarde.
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. O estilo de caminho está 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) Escolha uma tag de imagem (placeholder). Tags de exemplo aparecem nos documentos do Garage.
GARAGE_IMAGE="dxflrs/garage:TAG_PLACEHOLDER"

# 3) Execute 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) Use o CLI do garage dentro do contêiner
alias garage='docker exec -ti garaged /garage'

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

# 6) Atribua um layout (único nó) e aplique-o
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) Crie um bucket + chave e conceda permissões com o mínimo de privilégios
garage bucket create example-bucket
garage key create example-app-key
garage bucket allow --read --write --owner example-bucket --key example-app-key

# 8) Mostre o material da chave (salve-o de forma segura)
garage key info example-app-key

O padrão de configuração (API S3 no 3900, RPC no 3901, endpoint web no 3902, API de administração no 3903) e o fluxo de trabalho “layout required” são diretos do quickstart upstream.

Valide com o AWS CLI

O Garage exige que os clientes usem a s3_region configurada (muitas vezes “garage”); se o seu cliente usar us-east-1, você poderá encontrar redirecionamentos para AuthorizationHeaderMalformed.

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

# Configure o 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/chaves e nota mínimos de versões do AWS CLI para lidar com endpoints de forma conveniente.

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

Instalações binárias e pacotes

Os documentos do Garage explicitamente suportam: baixar binários da página de download do Garage, usar pacotes de distribuição (por exemplo, apk add garage no Alpine) ou construir a partir da fonte, se necessário.

Docker e Docker Compose

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

systemd

O Garage documenta uma implantação reforçada do systemd, incluindo advertências sobre o DynamicUser= do systemd e onde o estado persistente termina no disco.
Um exemplo de unidade mínima (adapte os caminhos ao seu ambiente):

# /etc/systemd/system/garage.service
[Unit]
Description=Armazenamento de objetos compatível com S3 do 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 e Helm

O Garage inclui um gráfico Helm no repositório e possui páginas oficiais de documentação 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 automatizar isso 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 estar em um HDD maior.
Para nós com múltiplos discos de dados, o Garage suporta uma configuração de data_dir com múltiplos discos 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 versus políticas de bucket S3

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

# Chave de leitura apenas 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 do estilo DNS versus estilo caminho

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

TLS

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

Um formato mínimo de Nginx (“shape”) (veja a documentação oficial do 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 no lado do servidor

O Garage suporta S3 SSE-C (“criptografia no 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 nota que endpoints de configuração de criptografia no nível do bucket não são implementados, então trate SSE-C como comportamento por objeto/solicitação em vez de padrões do bucket.

Operando o Garage em produção

Monitoramento e logs

O Garage expõe métricas no formato Prometheus e suporta exportar rastreamentos no formato OpenTelemetry.
Endpoints de administração 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 de manutenção comuns

O Garage inclui “scrub” de fundo (verificação de integridade) e ferramentas de reparo; os scrubs podem ser iniciados manualmente e monitorados via comandos de trabalhador/tarefa, mas são intensivos em disco e podem desacelerar o cluster.
Mudanças na topologia e ajustes de capacidade são tratadas por meio 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 do metadado, pois ele contém a configuração do cluster, o estado do bucket/chave e os índices. O Garage suporta snapshots periódicos de metadado (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 de cada nó metadata_dir (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 (por exemplo, restic, duplicity) direcionadas a um bucket do Garage, conforme documentado na página de integração “Backups” do Garage.

Notas sobre solução de problemas comuns

NO ROLE ASSIGNED em garage status normalmente significa que você ainda não criou/aplicou um layout. Corrigir: garage layout assign … depois garage layout apply.
AuthorizationHeaderMalformed frequentemente indica que o 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 mismatch entre estilo de caminho e estilo de vhost; configure [s3_api].root_domain para estilo de vhost, ou force o estilo de caminho nos clientes (por exemplo, force_path_style=true no rclone).
Erros de permissão são frequentemente apenas “chave não permitida no bucket”; inspecione com garage bucket info <bucket> e certifique-se de que garage bucket allow tenha as flags certas.

Notas sobre ajustes de desempenho que importam mais

Coloque metadata_dir em um SSD quando possível; os documentos do Garage destacam melhorias nos tempos de resposta e potencial redução drástica da latência.
Ajuste block_size e compressão com cuidado: os valores padrão do Garage são intencionados para serem sensatos, mas a referência de configuração explica o trade-off e nota que as mudanças se aplicam apenas a dados novos carregados.
Se você tiver 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ções para block_max_concurrent_writes_per_request.
Os próprios benchmarks do Garage enfatizam os custos da latência intra-cluster em implantações distribuídas geograficamente e destacam escolhas de design (por exemplo, evitar líderes de consenso) que podem reduzir o impacto da latência geográfica.

Comparação curta com o MinIO e AWS S3

O Garage é otimizado para clusters auto-hospedados, distribuídos geograficamente e simplicidade operacional, com algumas lacunas deliberadas em recursos S3 (por exemplo, nenhuma política de bucket/ACLs de S3; suporte limitado a versionamento).
MinIO se concentra na amplitude da API S3 e em implantações de alta performance para empresas (por exemplo, os próprios materiais do MinIO descrevem recursos como bloqueio de objetos, replicação e notificações de evento).
O AWS S3 é a implementação gerenciada com consistência forte, durabilidade de 11 nines e metas de disponibilidade de 99,99%, e um ecossistema amplo de recursos (classes de armazenamento, ciclo de vida, eventos, IAM).

Mais sobre o MinIO: