New external site management. New external prober heartbeat feature.

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` дольше ожидаемого.**