admin control features and admin dashboard

docs/SETUP.md

@@ -21,6 +21,7 @@
 - [Развёртывание control-api](#развёртывание-control-api)
 - [Развёртывание validator-agent на ВМ-валидаторах](#развёртывание-validator-agent-на-вм-валидаторах)
 - [Развёртывание prober на внешних площадках](#развёртывание-prober-на-внешних-площадках)
+- [Развёртывание admin-dashboard](#развёртывание-admin-dashboard)
 - [Проверка после запуска](#проверка-после-запуска)
 - [Сетевые доступы](#сетевые-доступы)
 
@@ -31,10 +32,13 @@
 | `control-api` | Отдельная управляющая машина/ВМ с доступом к OpenStack API | 1 (без HA) |
 | `validator-agent` | Каждая ВМ-валидатор в сервисном проекте облака | по числу валидаторов |
 | `prober` | По одному на каждой из внешних тестовых площадок | 3 (по числу площадок) |
+| `admin-dashboard` | Любая машина с сетевым доступом до `control-api` (опционально) | 0 или 1 |
 
-`control-api` — единственный компонент с состоянием (SQLite). Валидаторы и
-проберы не хранят локального состояния и полностью управляются через опрос
-control-api (см. [API.md](API.md)).
+`control-api` — единственный компонент с состоянием (SQLite). Валидаторы,
+проберы и `admin-dashboard` не хранят локального состояния и полностью
+управляются через опрос control-api (см. [API.md](API.md),
+[DASHBOARD.md](DASHBOARD.md)). `admin-dashboard` не обязателен — вся его
+функциональность доступна и через `curl` напрямую по API.
 
 ## Требования
 
@@ -58,7 +62,7 @@ control-api (см. [API.md](API.md)).
 
 ### Вариант A: готовые бинарники из репозитория (рекомендуется)
 
-В директории `bin/` репозитория уже лежат три готовых бинарника —
+В директории `bin/` репозитория уже лежат четыре готовых бинарника —
 собирать их на целевых серверах не нужно, разворачивание сразу
 начинается с копирования и запуска (раздел
 [«Развёртывание control-api»](#развёртывание-control-api) и далее).
@@ -68,6 +72,7 @@ bin/
 ├── control-api        # ~11 МБ
 ├── validator-agent     # ~7 МБ
 ├── prober               # ~7 МБ
+├── admin-dashboard      # ~9 МБ (опционален, см. DASHBOARD.md)
 └── SHA256SUMS
 ```
 
@@ -97,6 +102,7 @@ sha256sum -c bin/SHA256SUMS
 scp bin/control-api     control-api-host:/tmp/
 scp bin/validator-agent validator-host-01:/tmp/
 scp bin/prober           probe-site-1:/tmp/
+scp bin/admin-dashboard  dashboard-host:/tmp/   # опционально
 ```
 
 > Если целевая платформа отличается от linux/amd64 (например, ВМ на
@@ -113,11 +119,13 @@ export CGO_ENABLED=0 GOOS=linux GOARCH=amd64   # поменяйте GOARCH дл
 go build -trimpath -ldflags="-s -w" -o bin/control-api     ./cmd/control-api
 go build -trimpath -ldflags="-s -w" -o bin/validator-agent ./cmd/validator-agent
 go build -trimpath -ldflags="-s -w" -o bin/prober          ./cmd/prober
+go build -trimpath -ldflags="-s -w" -o bin/admin-dashboard ./cmd/admin-dashboard
 ```
 
 Каждый бинарник самодостаточен — скопируйте нужный файл на
 соответствующую машину (control-api → управляющая машина, validator-agent
-→ каждый валидатор, prober → каждая площадка).
+→ каждый валидатор, prober → каждая площадка, admin-dashboard →
+опционально, любая машина с доступом до control-api).
 
 Убедиться, что всё собирается и юнит-тесты проходят:
 
@@ -130,7 +138,7 @@ go build ./... && go test ./...
 обновляются автоматически**:
 
 ```bash
-sha256sum bin/control-api bin/validator-agent bin/prober | sed 's#bin/##' > bin/SHA256SUMS
+sha256sum bin/control-api bin/validator-agent bin/prober bin/admin-dashboard | sed 's#bin/##' > bin/SHA256SUMS
 ```
 
 ## Быстрая проверка без OpenStack (offline-режим)
@@ -181,6 +189,15 @@ cp configs/control-api.example.yaml /etc/cloud-ip-validator/control-api.yaml
   целей для egress-проверок (по умолчанию — hub.docker.com, github.com,
   packages.ubuntu.com) или включите `ssh` (по умолчанию выключен).
 
+> `validators`, `sites`, `targets` и `check_types` читаются из этого файла
+> только один раз — при самом первом старте против пустой базы данных
+> (bootstrap). После этого все последующие изменения этих четырёх секций
+> вносятся через `/api/v1/admin/config/*`, а не правкой YAML — см.
+> [API.md](API.md#управление-очередью-и-конфигурацией) и
+> [USAGE.md](USAGE.md#управление-валидаторами). `ip_addresses` — исключение,
+> он остаётся YAML + аддитивным добавлением при каждом старте (плюс
+> `POST /api/v1/admin/ips` для управления очередью без рестарта).
+
 ### 2. Переменные окружения для OpenStack
 
 Учётные данные передаются **только** через переменные окружения — никогда
@@ -276,15 +293,29 @@ systemctl enable --now control-api
 
 **Первичная инициализация базы данных происходит автоматически** — при
 первом старте `control-api` создаёт файл SQLite по пути `database.path`
-из конфига (миграция схемы применяется один раз, повторные запуски —
-no-op). Отдельной команды "init db" не требуется.
+из конфига (миграции схемы применяются один раз каждая, повторные запуски
+— no-op). Отдельной команды "init db" не требуется.
 
 При каждом старте control-api также:
-1. Регистрирует в БД всех валидаторов из `validators` конфига (если их
-   там ещё нет).
-2. Добавляет в очередь все адреса из `ip_addresses`, которых там ещё нет
-   (уже обработанные ранее адреса повторно не добавляются и не
-   сбрасываются — см. [USAGE.md](USAGE.md#добавление-новых-ip-в-очередь)).
+1. **Bootstrap-once для `validators`/`sites`/`targets`/`check_types`.**
+   YAML применяется **только если соответствующая таблица в БД сейчас
+   пуста** — то есть только на самом первом старте против чистой базы.
+   Как только в таблице появилась хотя бы одна строка (через этот
+   bootstrap либо через `/api/v1/admin/config/*`, см.
+   [API.md](API.md#управление-очередью-и-конфигурацией)), YAML для этой
+   секции больше не перечитывается ни при одном последующем рестарте —
+   источник истины переключается на БД. Это осознанное отличие от более
+   ранних версий, где `validators` из YAML переприменялись при каждом
+   рестарте: теперь правки, сделанные через admin API (например, смена
+   `os_port_id` валидатора), переживают рестарт вместо того, чтобы
+   тихо откатываться.
+2. **Всегда аддитивно** добавляет в очередь все адреса из
+   `ip_addresses`, которых там ещё нет (уже обработанные ранее адреса
+   повторно не добавляются и не сбрасываются — см.
+   [USAGE.md](USAGE.md#добавление-новых-ip-в-очередь)). Это отдельный,
+   не завязанный на bootstrap-once путь — не путайте с
+   `POST /api/v1/admin/ips`, который умеет то же самое (и ещё
+   принудительный повтор уже проверенных адресов) без перезапуска.
 
 Проверить, что процесс поднялся:
 
@@ -327,6 +358,28 @@ systemctl enable --now prober
 journalctl -u prober -f
 ```
 
+## Развёртывание admin-dashboard
+
+Опционально — вся его функциональность доступна и через `curl` напрямую
+по API (см. [API.md](API.md)). На любой машине с сетевым доступом до
+`control-api`:
+
+```bash
+cp bin/admin-dashboard /usr/local/bin/admin-dashboard
+cp deploy/systemd/admin-dashboard.service /etc/systemd/system/
+mkdir -p /etc/cloud-ip-validator
+cp configs/admin-dashboard.example.yaml /etc/cloud-ip-validator/admin-dashboard.yaml
+# отредактировать control_api.base_url под ваш стенд
+
+systemctl daemon-reload
+systemctl enable --now admin-dashboard
+journalctl -u admin-dashboard -f
+```
+
+Открыть `http://<admin-dashboard>:8090/` в браузере. Подробнее о
+страницах и о том, что дашборд может (и не может) — в
+[DASHBOARD.md](DASHBOARD.md).
+
 ## Проверка после запуска
 
 После того как control-api, все валидаторы и все три пробера запущены:
@@ -376,7 +429,14 @@ curl -s http://<control-api>:8080/api/v1/admin/validators | python3 -m json.tool
   очередь — см. [USAGE.md](USAGE.md#частые-проблемы-и-что-с-ними-делать).
 - `control-api` → OpenStack Keystone/Neutron API (`OS_AUTH_URL` и далее по
   каталогу сервисов).
+- `admin-dashboard` → `control-api`: тот же порт (`server.listen_addr`),
+  адрес задаётся в `control_api.base_url` конфига дашборда.
+- Оператор (браузер) → `admin-dashboard`: порт из `server.listen_addr`
+  дашборда (по умолчанию 8090).
 
 API control-api сейчас не аутентифицирован (см. предупреждение в начале
-[API.md](API.md)) — ограничивайте доступ к порту control-api на уровне
-сети/firewall теми хостами, где реально работают валидаторы и проберы.
+[API.md](API.md)) — то же самое верно и для `admin-dashboard`, который
+это API оборачивает. Ограничивайте доступ к обоим портам на уровне
+сети/firewall: к control-api — теми хостами, где реально работают
+валидаторы, проберы и сам дашборд; к дашборду — теми, кому разрешено
+администрировать стенд.