---
name: garage-cluster-ops
title: "Garage Cluster Operations (S3, v2.x)"
description: "Кластер Garage S3 в docker: статус, метрики, рестарт нод."
---

## Когда использовать

Кластер Garage (dxflrs/garage:v2.1.0, RF=3) на нескольких нодах. У пользователя:
vps01=10.8.0.1, bigbox=10.8.0.2, vps02=10.8.0.4 (WireGuard 10.8.0.0/24), на bigbox
конфиг и тома в /opt/garage.

## Статус кластера

Контейнер garage — scratch-образ без shell (docker exec невозможен), CLI-бинаря
в /opt/garage/cli/ нет. Рабочий способ — `docker run` с проброшенными томами:

```bash
docker run --rm -v /opt/garage/garage.toml:/etc/garage.toml:ro \
  -v /opt/garage/meta:/var/lib/garage/meta \
  --entrypoint /garage dxflrs/garage:v2.1.0 status
```

Также: `cluster status` / `bucket list` / `stats`, healthz по HTTP: `http://10.8.0.X:3901/healthz`.

## Метрики Prometheus (Garage v2.1+)

Admin API (включая /metrics в Prometheus-формате) живёт на ОТДЕЛЬНОМ порту от S3 (3900).
Без этого Bearer-токен конфликтует с S3-авторизацией на общем порту ("Metrics cannot be
used outside of the HTTP Admin API").

В [admin] секции garage.toml каждой ноды:

```toml
[admin]
metrics_token = "<admin_token>"
api_bind_addr = "10.8.0.X:3903"   # WG-IP ноды, не 0.0.0.0
```

Проверка: `curl -H "Authorization: Bearer <admin_token>" http://10.8.0.X:3903/metrics`
→ HTTP 200, текст в Prometheus-формате (~90-110 KB). Таргет в prometheus.yml:
`http://10.8.0.X:3903/metrics` + bearer_token. Токен admin API отдельно:
`docker run ... --entrypoint /garage dxflrs/garage:v2.1.0 admin token list`.

## Безопасный рестарт нод (кворум RF=3)

По очереди, внешние ноды сначала: vps02 → пауза ~8с → vps01 → пауза → bigbox.
После всех — проверить `status` = HEALTHY. НЕ пересобирать layout.

## Файрвол

На vps01 (UFW) admin-порт резался из WG: открыть только из подсети:
`sudo ufw allow from 10.8.0.0/24 to any port 3903 proto tcp`.
На vps02 (policy ACCEPT) и bigbox дополнительных правил не требуется.

## Мониторинг-стек

Prometheus + Grafana (3001, т.к. 3000 занят gitea) + Loki/Promtail: /opt/monitoring
(docker compose; репозиторий gitverse kpa39l/monitoring, gitea-зеркало estorozhenko/monitoring).
Алерты гаражные: GarageNodeDown (up==0), NoQuorum (<2 нод) — молчат без проблемы.

## Питфоллы

- Не путать порты: 3900 S3, 3901 RPC, 3902 web, 3903 admin/metrics (после патча api_bind_addr).
- admin_token и metrics_token в этой инсталляции одинаковые.
- Образ scratch: все действия с демоном — через docker run --entrypoint, не docker exec.