Initial commit: Hermes skill garage-cluster-ops

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 = "<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.