From 07fd8d82ad1862255dfb9f35c23bd5e1904897d9 Mon Sep 17 00:00:00 2001 From: estorozhenko Date: Sun, 6 Sep 2026 13:50:52 +0000 Subject: [PATCH] Initial commit: Hermes skill garage-cluster-ops --- SKILL.md | 66 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 66 insertions(+) create mode 100644 SKILL.md diff --git a/SKILL.md b/SKILL.md new file mode 100644 index 0000000..3f754e4 --- /dev/null +++ b/SKILL.md @@ -0,0 +1,66 @@ +--- +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 = "" +api_bind_addr = "10.8.0.X:3903" # WG-IP ноды, не 0.0.0.0 +``` + +Проверка: `curl -H "Authorization: Bearer " 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. \ No newline at end of file