New external site management. New external prober heartbeat feature.

docs/API.md

@@ -209,7 +209,12 @@ target)` в рамках текущей попытки — безопасна и
 ### `POST /api/v1/probers/register`
 
 Регистрация пробера. `site_id` должен присутствовать в конфиге control-api
-(`sites[].site_id`), иначе — `400`.
+(`sites[].site_id`), иначе — `400`. Помимо привычной проверки, запоминает
+`hostname` и переводит площадку в состояние `idle` (если она была
+`unregistered`/`unreachable`) — то же самое, что делает `validator-agent`
+при своей регистрации (см.
+[«Управление площадками»](USAGE.md#управление-площадками-проберами) в
+USAGE.md про состояния площадки).
 
 Запрос:
 ```json
@@ -218,6 +223,17 @@ target)` в рамках текущей попытки — безопасна и
 
 Ответ: `{"ok": true, "poll_interval_seconds": 5}`.
 
+### `POST /api/v1/probers/{site_id}/heartbeat`
+
+«Я жив». Обновляет `last_heartbeat_at` площадки. Если площадка не
+присылает heartbeat дольше `orchestrator.heartbeat_timeout_seconds`
+(тот же параметр, что и для валидаторов), она помечается `unreachable`.
+Полный аналог `POST /api/v1/agents/{id}/heartbeat` для пробера.
+
+Запрос: тело не требуется.
+
+Ответ: `{"ok": true}`. `404`, если `site_id` не сконфигурирован.
+
 ### `GET /api/v1/probers/{site_id}/assignments`
 
 Список всех IP, которые сейчас находятся в состоянии `checking` — то есть
@@ -424,15 +440,23 @@ curl -s -X POST "$BASE/api/v1/admin/ips/clear"
 
 ### Площадки: `/api/v1/admin/config/sites`
 
-Слотов ровно три (`index` ∈ {1, 2, 3}) — это ограничение схемы БД
-(`ip_queue.site{1,2,3}_complete`), а не искусственное. Пустой список слотов
-— штатный сценарий, отключающий inbound-проверки целиком (см.
+Число слотов не ограничено — `index` может быть любым целым `>= 1`,
+столько площадок, сколько нужно оператору. Пустой список слотов — штатный
+сценарий, отключающий inbound-проверки целиком (см.
 [USAGE.md](USAGE.md#управление-площадками-проберами)).
 
+Помимо `index`/`site_id`, объект площадки несёт состояние подключения
+пробера — `hostname`/`state`/`last_heartbeat_at`, тот же смысл, что у
+аналогичных полей валидатора (`unregistered`/`idle`/`unreachable`,
+обновляются через `POST /api/v1/probers/register` и `POST
+/api/v1/probers/{site_id}/heartbeat`, см. выше). `PUT` на слот всегда
+сбрасывает эти три поля к значениям «ещё не подключался» — новый (или
+даже тот же) `site_id` трактуется как новая идентичность пробера.
+
 | Метод | Путь | Тело | Успех | Ошибки |
 |---|---|---|---|---|
-| GET | `/api/v1/admin/config/sites` | — | `[{"index","site_id"}]` (до 3 строк) | |
-| PUT | `/api/v1/admin/config/sites/{index}` | `{"site_id"}` | `200` | `400`, если `index` не 1..3; `409`, если `site_id` уже занят другим слотом |
+| GET | `/api/v1/admin/config/sites` | — | `[{"index","site_id","hostname","state","last_heartbeat_at"}]` | |
+| PUT | `/api/v1/admin/config/sites/{index}` | `{"site_id"}` | `200` | `400`, если `index < 1`; `409`, если `site_id` уже занят другим слотом |
 | DELETE | `/api/v1/admin/config/sites/{index}` | — | `200` | `404` |
 
 ### Группы целей: `/api/v1/admin/config/targets`
@@ -570,8 +594,8 @@ queued ──(control-api сам, без вызова API)──▶ assigning_fi
 в БД при этом уже `awaiting_self_check`.
 
 Площадки (`siteN_complete`) — опциональны: сколько их учитывается,
-целиком определяется текущим списком `sites` (0–3 записи, управляется
-через `/api/v1/admin/config/sites` — см.
+целиком определяется текущим списком `sites` (без ограничения по числу
+записей, управляется через `/api/v1/admin/config/sites` — см.
 [выше](#управление-очередью-и-конфигурацией)). Пустой список — агрегация
 ждёт только `egress_complete`, ни одна площадка не требуется. Подробнее —
 [USAGE.md](USAGE.md#управление-площадками-проберами).

docs/DASHBOARD.md

@@ -52,7 +52,7 @@ admin-dashboard -config /etc/cloud-ip-validator/admin-dashboard.yaml
 | `/ips` | Полная очередь. Форма сверху принимает список адресов (по одному на строке или через запятую) и отправляет их в `POST /api/v1/admin/ips` — **один и тот же вызов** добавляет новые адреса и принудительно перезапускает уже завершённые (см. ниже). У каждого адреса — кнопка «Перепроверить» (для `done`/`failed`) или «Отменить» (для активных состояний), и всегда — «Удалить» (безвозвратно, в отличие от «Отменить», см. ниже). Чекбоксы у строк + кнопка «Удалить выбранные» удаляют список одним вызовом; «Очистить всё» удаляет вообще всё, включая активные проверки — обе операции требуют явного подтверждения. Пока не истекла настроенная на `/settings` пауза (`fip_settle_seconds`), только что привязавший Floating IP адрес показывает отдельный бейдж «прогрев FIP» вместо обычного статуса. |
 | `/ips/{ip}` | Детали одного адреса: все проверки текущей попытки и вся история событий. |
 | `/validators` | Список валидаторов + создание/изменение `os_port_id`/удаление. |
-| `/sites` | Три фиксированных слота площадок (1/2/3) — назначить/сменить/освободить `site_id`. |
+| `/sites` | Площадки — число слотов не ограничено, форма сверху добавляет новый слот, назначить/сменить/освободить `site_id` в каждой строке; колонка «Статус» показывает бейдж подключения пробера (`unregistered`/`idle`/`unreachable`, по аналогии с `/validators`), см. [USAGE.md](USAGE.md#состояния-площадки). |
 | `/targets` | Группы целей для egress-проверок — создание/редактирование/удаление. |
 | `/check-types` | Типы проверок (`https`/`icmp`/`ssh`/...), включение/выключение, привязка к группам целей. |
 | `/settings` | Две формы: `fip_settle_seconds` — пауза (в секундах) между привязкой Floating IP и началом self-check («прогрев» дата-плейна OpenStack, см. [USAGE.md](USAGE.md#пауза-перед-self-check-fip_settle_seconds)); и типы проверок пробера — TCP-порты (через запятую) + чекбокс ICMP, общие для всех площадок (см. [USAGE.md](USAGE.md#управление-типами-проверок-пробера)). |

docs/DIAGRAMS.md

@@ -222,9 +222,9 @@ flowchart TB
 проверки — подробнее о значениях полей см.
 [USAGE.md](USAGE.md#значения-полей-ip).
 
-> На диаграмме показан полный вариант с тремя площадками — это не
-> обязательный минимум. Площадки опциональны: сколько их ожидать (0–3),
-> определяется списком `sites` в конфиге control-api. При пустом списке
-> четвёртый поток телеметрии (`inbound-site-N`) просто отсутствует, и
-> агрегация ждёт только `egress_complete`. См.
+> На диаграмме показан пример с тремя площадками — это лишь иллюстрация,
+> не ограничение. Площадки опциональны и их число не ограничено: сколько
+> их ожидать, определяется списком `sites` в конфиге control-api (пустой
+> список — ни одного потока `inbound-site-N`, агрегация ждёт только
+> `egress_complete`; N площадок — N параллельных потоков телеметрии). См.
 > [USAGE.md](USAGE.md#управление-площадками-проберами).

docs/SETUP.md

@@ -176,9 +176,9 @@ cp configs/control-api.example.yaml /etc/cloud-ip-validator/control-api.yaml
   соответствующего `validator-agent`) и `os_port_id` — **ID Neutron-порта**
   основного сетевого интерфейса ВМ-валидатора (узнать: `openstack port
   list --server <имя-ВМ>` или в веб-консоли облака).
-- **`sites`** — три внешние площадки, `site_id` + `index` (1, 2 или 3).
-  `site_id` должен совпадать с `site_id` в конфиге соответствующего
-  `prober`.
+- **`sites`** — внешние площадки, `site_id` + `index` (число слотов не
+  ограничено; в примере ниже — три). `site_id` должен совпадать с
+  `site_id` в конфиге соответствующего `prober`.
 - **`ip_addresses`** — список публичных IPv4-адресов на проверку, **в
   порядке обработки**. Адреса должны существовать в сервисном проекте как
   уже выделенные (allocated) floating IP — инструмент их не создаёт.

docs/USAGE.md

@@ -123,10 +123,14 @@ curl -s http://<control-api>:8080/api/v1/admin/ips \
 | `AttemptNumber` | Номер попытки — растёт при каждом requeue (сбой привязки, сбой self-check, реклейм по таймауту) |
 | `RetryCount` | Сколько раз адрес уже переставлялся в очередь заново |
 | `EgressComplete` | Валидатор закончил исходящие проверки |
-| `Site1Complete` / `Site2Complete` / `Site3Complete` | Соответствующая площадка закончила входящие проверки |
 | `OverallResult` | Итог: `pass`, `partial`, `fail`, `cancelled` (принудительно остановлена, см. [«Принудительная остановка проверки»](#принудительная-остановка-проверки)), либо пусто, пока проверка не завершена |
 | `AssignedAt` / `AggregatedAt` / `FIPReleasedAt` | Метки времени соответствующих этапов |
 
+> Завершённость входящих проверок по каждой конкретной площадке в этом
+> списке не отображается (площадок теперь может быть сколько угодно, а не
+> фиксированные три) — детали по конкретной площадке смотрите в массиве
+> `checks` ответа `GET /api/v1/admin/ips/{ip}` (`Source: "inbound-site-N"`).
+
 ## Как читать итоговый результат (pass/partial/fail)
 
 - **`pass`** — прошли все проверки: все исходящие, плюс все площадки по
@@ -237,18 +241,17 @@ curl -s -X DELETE http://<control-api>:8080/api/v1/admin/config/validators/valid
 
 ## Управление площадками (проберами)
 
-**Входящие (inbound/prober) проверки полностью опциональны.** Список
-`sites` в конфиге control-api и есть переключатель: пусто — inbound-
-проверки выключены целиком, итоговый результат считается только по
-исходящим (egress) проверкам, и агрегация не ждёт вообще ни одного
-пробера. Указан один или два слота — ждём только их, остальные не
-учитываются. Указаны все три — работает как в исходной схеме процесса.
+**Входящие (inbound/prober) проверки полностью опциональны, а число
+площадок не ограничено.** Список `sites` в конфиге control-api и есть
+переключатель: пусто — inbound-проверки выключены целиком, итоговый
+результат считается только по исходящим (egress) проверкам, и агрегация
+не ждёт вообще ни одного пробера. Указано N слотов — ждём именно их.
 Явного отдельного флага "включить/выключить" нет — самого списка `sites`
 достаточно.
 
 Чтобы добавить площадку (без перезапуска control-api) — назначьте
-`site_id` на один из трёх слотов (`index` 1, 2 или 3 — см. ограничение
-ниже) через API:
+`site_id` любому свободному слоту (`index` — любое целое `>= 1`, слотов
+может быть сколько угодно) через API:
 ```bash
 curl -s -X PUT http://<control-api>:8080/api/v1/admin/config/sites/1 \
   -d '{"site_id": "site-1"}'
@@ -269,12 +272,26 @@ curl -s -X DELETE http://<control-api>:8080/api/v1/admin/config/sites/1
 > игнорируется при всех последующих рестартах. Для стенда, который уже
 > хоть раз запускался, используйте API выше.
 
-> Важно: количество *возможных* слотов площадок жёстко зашито в схему БД
-> (`Site1Complete`/`Site2Complete`/`Site3Complete`) — не более **трёх**,
-> как и описано в исходной схеме процесса. `index` может быть только 1, 2
-> или 3. Использовать *меньше* трёх (в том числе ноль) — штатный,
-> поддерживаемый сценарий; *больше* трёх потребует доработки схемы
-> данных, одной правкой конфига не обойтись.
+### Состояния площадки
+
+По аналогии с валидаторами (см. [«Управление
+валидаторами»](#управление-валидаторами) выше), у каждой площадки есть
+состояние подключения — видно и в `GET /api/v1/admin/config/sites`
+(поля `hostname`/`state`/`last_heartbeat_at`), и на странице `/sites`
+дашборда бейджем:
+- **`unregistered`** — слот сконфигурирован, но процесс `prober` на этой
+  площадке ещё ни разу не подключался (не вызывал `POST
+  /api/v1/probers/register`).
+- **`idle`** — площадка на связи: `prober` зарегистрирован и присылает
+  heartbeat (`POST /api/v1/probers/{site_id}/heartbeat`) на каждом опросе.
+- **`unreachable`** — площадка пропустила heartbeat дольше
+  `orchestrator.heartbeat_timeout_seconds` (тот же параметр, что и для
+  валидаторов) — вероятно, процесс `prober` упал или потерял сеть до
+  control-api.
+
+В отличие от валидатора, у площадки нет состояний `assigned`/`checking`
+— пробер не привязан к одному IP, а на каждом опросе обрабатывает сразу
+весь активный набор.
 
 ## Управление типами проверок пробера
 
@@ -522,13 +539,17 @@ https://api.ipify.org`) и логи `journalctl -u validator-agent` на пре
 сети) покажет приватный адрес валидатора независимо от того, правильно
 ли привязан FIP, и всегда будет давать ложный провал.
 
-**Площадка (`site-N`) никогда не отчитывается (`SiteNComplete` всегда
-`false`).**
-Проверьте, что `prober` на этой площадке запущен и его `site_id` в
-конфиге совпадает с `site_id` в конфиге control-api. Проверьте, что
-площадка имеет сетевой доступ и до `control-api`, и до проверяемого
-адреса (входящий трафик на 22/80/443/8080 + ICMP — это отдельная
-связность от связи с control-api, см.
+**Площадка (`site-N`) никогда не отчитывается по конкретному IP.**
+Сперва проверьте статус самой площадки — `GET
+/api/v1/admin/config/sites`, поле `state`. `unregistered` или
+`unreachable` означает, что `prober` на этой площадке вообще не на связи
+с control-api (см. [«Состояния площадки»](#состояния-площадки) выше) —
+проверьте, что процесс запущен и его `site_id` в конфиге совпадает с
+`site_id` в конфиге control-api, и что площадка имеет сетевой доступ до
+`control-api`. Если статус `idle` (площадка на связи), а конкретный IP
+всё равно не получает отметку о завершении — проверьте отдельно
+связность до проверяемого адреса (входящий трафик на 22/80/443/8080 +
+ICMP — это отдельная связность от связи с control-api, см.
 [SETUP.md](SETUP.md#сетевые-доступы)).
 
 **Много адресов зависло в `checking` дольше ожидаемого.**