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, de código aberto e auto-hospedado, projetado para implantações de pequeno a médio porte, com um forte ênfase em resiliência e distribuição geográfica.

Este quickstart leva você desde uma configuração de único nó copiar/colar até padrões orientados para produção: layout do cluster, replicação, TLS via proxy reverso, armazenamentos de backend com múltiplos discos, monitoramento, reparos e backup/restauração.

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

Boxes do Garage

O que é o Garage

O Garage é um armazenamento de objetos distribuído compatível com S3 destinado ao auto-hospedamento, visando permanecer leve e simples de operar, enquanto suporta clusters multi-sítio/distribuídos geograficamente.
Ele é 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 colocar réplicas; alterações 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 a deduplicação e a compressão opcional com Zstandard; os hashes dos blocos são usados para colocação e deduplicação.
O Garage não encerra o TLS em seus endpoints de API de S3/web; espera-se que você implante um proxy reverso para HTTPS em implantações reais.

Arquitetura e fluxo de dados

Em nível geral, 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 “sabendo” quais nós de armazenamento consultar.
A replicação é controlada via replication_factor (exemplo: replicação de 3 vias entre zonas), com clara descrição de trade-offs de disponibilidade/tolerância a falhas no referência de configuração.

Quickstart copiar/colar

Este é um depósito intencionalmente mínimo ú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 (NENHUMa 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 sempre 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) Escolha uma tag da 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á "NENHUMA FUNÇÃO ATRIBUÍDA")
garage status

# 6) Atribua um layout (único nó) e aplique-o
NODE_ID="$(garage status | awk '/NENHUMA FUNÇÃO ATRIBUÍDA/{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 de mínimo 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) Mostre o material da chave (salve-o com segurança)
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 necessário” são diretos do quickstart upstream.

Valide com 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ê pode ser redirecionado para AuthorizationHeaderMalformed.

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

# Configurar o ambiente (exemplo)
export AWS_ACCESS_KEY_ID="SEU_ID_DA_CHAVE_GARAGE"
export AWS_SECRET_ACCESS_KEY="SEU_SEGredo_DA_CHAVE_GARAGE"
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 as versões mínimas do AWS CLI para manipulação conveniente de endpoints.

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

Instalações binárias e pacotes

Os documentos do Garage suportam explicitamente: baixar binários da página de download do Garage, usar pacotes de distribuição (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 menciona os caminhos comuns de host e recomendação de SSD para metadados.

systemd

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

# /etc/systemd/system/garage.service
[Unit]
Descrição=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 do 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 vs políticas de bucket S3

O Garage não implementa ACLs ou políticas de bucket do estilo AWS; ele usa seu próprio sistema de permissão “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 vs estilo caminho

O Garage pode suportar virtual-host (DNS) estilo de acesso a bucket se você configurar [s3_api].root_domain; o estilo de caminho sempre está 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 em frente, comumente Nginx, para servir HTTPS e multiplexar serviços na porta 443.

Um formato mínimo de Nginx (“shape”) (veja a cozinheira 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 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, e não como padrão de bucket.

Operar o Garage em produção

Monitoramento e logs

O Garage expõe métricas no formato Prometheus e suporta exportação de 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.
Alterações 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 metadata, pois ele contém a configuração do cluster, o estado do bucket/chave e os índices. O Garage suporta snapshots periódicos de metadata (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ó em metadata_dir (incluindo snapshots e arquivos de layout).

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

Notas de 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 (exemplo, rclone’s force_path_style=true).
Erros de permissão são frequentemente apenas “chave não permitida no bucket”; inspecione com garage bucket info <bucket> e garanta que garage bucket allow tenha as flags certas.

Notas de ajuste 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 de redução drástica de latência.
Ajuste block_size e compressão com cuidado: os valores padrão do Garage são intencionados para serem razoáveis, mas a referência de configuração explica o trade-off e nota que as alterações se aplicam apenas a dados novos.
Se você tiver NVMe, aumentar a concorrência de escrita de blocos pode melhorar a throughput, 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 geodistribuídas, e destacam escolhas de design (exemplo, evitar líderes de consenso) que podem reduzir o impacto da latência geográfica.

Comparação breve com MinIO e AWS S3

O Garage é otimizado para clusters auto-hospedados e geodistribuídos, com simplicidade operacional, com algumas lacunas deliberadas em recursos S3 (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 empresariais de alto desempenho (por exemplo, os próprios materiais do MinIO descrevem recursos como bloqueio de objeto, replicação e notificações de evento).
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).

Para mais detalhes, consulte Comparação entre Garage, MinIO e AWS S3.

Mais sobre MinIO: