55 lines
3.6 KiB
Markdown
55 lines
3.6 KiB
Markdown
# Каталог Grafana в onGuard24
|
||
|
||
Иерархия **инстанс → организация → папки → правила алертинга** подтягивается **по HTTP API** Grafana и сохраняется в PostgreSQL. Вебхук при этом не заменяет синхронизацию: вебхук даёт события, каталог — актуальную структуру правил.
|
||
|
||
## Что нужно
|
||
|
||
1. Миграция **`004_grafana_catalog`** (выполняется при старте контейнера через `alembic upgrade head`).
|
||
2. В `.env` у источника Grafana заданы **`api_url`** и **`api_token`** (service account с правами читать папки и alert rules — обычно роль Viewer/Editor и доступ к Alerting).
|
||
3. Источник попадает в **`iter_grafana_sources`**: `GRAFANA_SOURCES_JSON` или пара `GRAFANA_URL` + `GRAFANA_SERVICE_ACCOUNT_TOKEN` (slug `default`).
|
||
|
||
## API
|
||
|
||
| Метод | Путь | Назначение |
|
||
|--------|------|------------|
|
||
| POST | `/api/v1/modules/grafana-catalog/sync` | Синхронизация. Тело: `{}` — все источники с токеном; `{"instance_slug":"default"}` — один slug. |
|
||
| GET | `/api/v1/modules/grafana-catalog/meta` | Последние метаданные синхронизации по всем slug. |
|
||
| GET | `/api/v1/modules/grafana-catalog/tree?instance_slug=default` | Дерево: папки и правила, сгруппированные по `namespace_uid` (обычно UID папки правил). |
|
||
|
||
## Проверка на https://onguard24.pvenode.ru/
|
||
|
||
1. Убедитесь, что задеплоена версия с модулем **Каталог Grafana** (пункт в боковом меню).
|
||
2. Выполните синхронизацию (с сервера или с машины с доступом к API):
|
||
|
||
```bash
|
||
curl -sS -X POST "https://onguard24.pvenode.ru/api/v1/modules/grafana-catalog/sync" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{}'
|
||
```
|
||
|
||
Ответ: `results[]` с полями `ok`, `folders`, `rules`, при ошибке — `error`.
|
||
|
||
3. Посмотреть дерево:
|
||
|
||
```bash
|
||
curl -sS "https://onguard24.pvenode.ru/api/v1/modules/grafana-catalog/tree?instance_slug=default" | python3 -m json.tool
|
||
```
|
||
|
||
(Если используете только `GRAFANA_URL`, slug источника — **`default`**.)
|
||
|
||
4. В UI: **Каталог Grafana** — таблица последних синхронизаций.
|
||
|
||
## Связь с вебхуком
|
||
|
||
- В инцидентах по-прежнему используется **`externalURL` / лейблы** из тела вебхука.
|
||
- Каталог позволяет в UI/API сопоставлять **`rule_uid`** и папку с сохранённым снимком (после доработок привязки).
|
||
|
||
## Ограничения
|
||
|
||
- Один токен = **одна Grafana-организация** (контекст `GET /api/org`). Обход нескольких org на одном инстансе — отдельные токены или админ-API (не в этой версии).
|
||
- Эндпоинты Ruler: пробуются `/api/ruler/grafana/api/v1/rules` и `/api/ruler/Grafana/api/v1/rules` (зависит от версии Grafana).
|
||
|
||
## Автоматический cron
|
||
|
||
Периодический `POST .../sync` пока не встроен: можно повесить **системный cron**, **Forgejo scheduled workflow** или внешний оркестратор.
|