Опыт эксплуатации: мониторинг Garage v2.1 через Prometheus

Дата: 2026-08-30 Ситуация: кластер Garage v2.1 (RF=3) на vps01 + bigbox + vps02, WireGuard 10.8.0.0/24. Задача: вывести статус кластера в браузер (Grafana + Prometheus + Loki).

Ключевые находки / грабли

1. Admin API Garage v2.1 слушает ОТДЕЛЬНЫЙ порт (`[admin] api_bind_addr`)

Самое важное. Если api_bind_addr НЕ задан в [admin], Garage слушает admin (включая /metrics) на том же порту, что S3 API (3900). В этом случае Authorization: Bearer <token> к /metrics на 3900 отвечает 400 Bad request: Unsupported authorization method — авторизация S3 не понимает Bearer, а admin-роутер не подключён.

Решение: добавить в [admin] отдельный адрес:

[admin]
api_bind_addr = "10.8.0.2:3903"  # свой WG-IP на каждой ноде
metrics_token = "..."
admin_token   = "..."

После рестарта ноды /metrics и /health доступны на :3903.

2. `metrics_token` НЕ обязателен

Если metrics_token не задан — /metrics доступен без авторизации. Если задан — используется как обычный Bearer token:

curl -H "Authorization: Bearer <metrics_token>" http://node:3903/metrics

(совпадает с синтаксисом admin_token; для метрик достаточно metrics_token).

3. Docker-образ `dxflrs/garage:v2.1.0` — scratch без shell

Нет /bin/sh, нет ls, docker exec garage ls — не работает.
CLI-бинарь лежит по пути /garage внутри образа, а НЕ в PATH.
Поэтому проверка статуса через docker run:

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

(без монтирования meta будет ошибка "Unable to read node key").

4. Перезапуск нод кластера — безопасно, но по очереди

docker compose restart garage на всех трёх нодах прошёл без потери кворума и без пересборки layout — кластер остался HEALTHY (layout version 1 сохранился). Порядок: внешние (vps02, vps01) → bigbox. Пауза ~8с между рестартами.

5. UFW на vps01 режет новые порты

Порт 3903 на vps01 был закрыт UFW (в отличие от 3901, открытого для Anywhere). Пришлось:

sudo ufw allow from 10.8.0.0/24 to any port 3903 proto tcp comment "garage admin metrics"

На vps02 файрвол — nftables с policy ACCEPT, порт не блокировался.

6. Конфиг garage.toml на vps01/vps02 принадлежит root

Правка через SSH требует sudo (python не может писать напрямую):

ssh vps01 'sudo sed -i "s|^\[admin\]$|[admin]\napi_bind_addr = \"10.8.0.1:3903\"|" /opt/garage/garage.toml'

7. Авторизация в веб-поиске не работает напрямую с bigbox

SearXNG (127.0.0.1:11436) возвращает пустые результаты из-за блокировок движков (brave rate-limit, duckduckgo CAPTCHA, startpage timeout). Документация Garage достаётся напрямую с git.deuxfleurs.fr:

https://git.deuxfleurs.fr/Deuxfleurs/garage/raw/branch/main-v1/doc/book/reference-manual/configuration.md
https://git.deuxfleurs.fr/Deuxfleurs/garage/raw/branch/main-v1/doc/book/reference-manual/admin-api.md

Ветка по умолчанию для v2.x — main-v1 (не main).

Проверка результата

# все три ноды отдают метрики:
curl -s -H "Authorization: Bearer <token>" http://10.8.0.1:3903/metrics | head
curl -s -H "Authorization: Bearer <token>" http://10.8.0.2:3903/metrics | head
curl -s -H "Authorization: Bearer <token>" http://10.8.0.4:3903/metrics | head
# → HTTP 200, ~90-110 КБ текста в Prometheus-формате

# кластер HEALTHY:
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

Что осталось сделать / TODO

Поднять docker compose up -d в /opt/monitoring (после первого коммита)
Node-exporter на всех 3 хостах (10.8.0.x:9100)
Дашборд Garage в Grafana (provisioning уже настроен, нужен JSON)
Проверить up{job="garage"} в Prometheus и открыть Grafana :3001
Логи garage через promtail → Loki → Grafana
Сделать разные admin_token / metrics_token (сейчас совпадают)

5.1 KiB Raw Blame History Unescape Escape