Manage external site-prober actions va API and Dashboard

2026-08-26 19:45:48 +03:00
1 parent f22ad569b6
commit 42f584dd3c
@@ -231,7 +231,11 @@ target)` в рамках текущей попытки — безопасна и
 ]
 ```

-Пустой список `[]`, если сейчас нечего проверять.
+Пустой список `[]`, если сейчас нечего проверять. `ports`/`icmp` — текущая
+конфигурация типов проверок пробера, одна и та же для каждого IP в ответе;
+управляется через
+[`/api/v1/admin/config/inbound-checks`](#типы-проверок-пробера-apiv1adminconfiginbound-checks)
+и меняется без рестарта control-api.

 ### `POST /api/v1/probers/{site_id}/results`

@@ -477,6 +481,33 @@ fip_settle_seconds` в `control-api.yaml` — только одноразовы
 для пустой БД; дальше источник истины — сама база, менять значение нужно
 через `PUT` выше (или страницу `/settings` в дашборде).

+### Типы проверок пробера: `/api/v1/admin/config/inbound-checks`
+
+Единый глобальный набор TCP-портов и флага ICMP, которые `prober`
+проверяет на каждой настроенной площадке для каждого адреса в состоянии
+`checking` — то же самое `ports`/`icmp`, что отдаётся в ответе `GET
+/api/v1/probers/{site_id}/assignments` (см.
+[«Методы для prober»](#методы-для-prober) выше). Один набор общий для всех
+площадок; список [«площадок»](#площадки-apiv1adminconfigsites) отдельно
+решает, *сколько* точек его применяют, а не что именно они проверяют.
+Пустой список портов и `icmp: false` одновременно — допустимая
+конфигурация: временно отключает inbound-проверки, не трогая список
+`sites`.
+
+| Метод | Путь | Тело | Успех | Ошибки |
+|---|---|---|---|---|
+| GET | `/api/v1/admin/config/inbound-checks` | — | `{"ports":[...],"icmp":bool}` | |
+| PUT | `/api/v1/admin/config/inbound-checks` | `{"ports":[...],"icmp":bool}` | `200` | `400`, если какой-то порт вне диапазона `1..65535` или порты повторяются |
+
+Изменение вступает в силу немедленно — как для следующего ответа `GET
+/api/v1/probers/{site_id}/assignments`, так и для агрегации уже идущих
+проверок (см. [«Управление площадками»](USAGE.md#управление-площадками-проберами)
+в USAGE.md про тот же принцип для `sites`/`targets`/`check_types`). Как и
+остальные разделы этой группы, YAML-поле `orchestrator.inbound_checks` в
+`control-api.yaml` — только одноразовый bootstrap для пустой БД; дальше
+источник истины — сама база, менять значение нужно через `PUT` выше (или
+страницу `/settings` в дашборде).
+
 ### Пример: конфигурация целиком через API, без единой строки в YAML

 ```bash
@@ -55,7 +55,7 @@ admin-dashboard -config /etc/cloud-ip-validator/admin-dashboard.yaml
 | `/sites` | Три фиксированных слота площадок (1/2/3) — назначить/сменить/освободить `site_id`. |
 | `/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)). |
+| `/settings` | Две формы: `fip_settle_seconds` — пауза (в секундах) между привязкой Floating IP и началом self-check («прогрев» дата-плейна OpenStack, см. [USAGE.md](USAGE.md#пауза-перед-self-check-fip_settle_seconds)); и типы проверок пробера — TCP-порты (через запятую) + чекбокс ICMP, общие для всех площадок (см. [USAGE.md](USAGE.md#управление-типами-проверок-пробера)). |

 ### «Текущая» и «последняя завершённая» проверка

@@ -17,6 +17,7 @@
 - [Просмотр деталей и истории по конкретному адресу](#просмотр-деталей-и-истории-по-конкретному-адресу)
 - [Управление валидаторами](#управление-валидаторами)
 - [Управление площадками (проберами)](#управление-площадками-проберами)
+- [Управление типами проверок пробера](#управление-типами-проверок-пробера)
 - [Управление целями проверки](#управление-целями-проверки)
 - [Повторная проверка адреса](#повторная-проверка-адреса)
 - [Принудительная остановка проверки](#принудительная-остановка-проверки)
@@ -275,6 +276,44 @@ curl -s -X DELETE http://<control-api>:8080/api/v1/admin/config/sites/1
 > поддерживаемый сценарий; *больше* трёх потребует доработки схемы
 > данных, одной правкой конфига не обойтись.

+## Управление типами проверок пробера
+
+Список TCP-портов и флаг ICMP, которые `prober` проверяет на каждой
+настроенной площадке — единый глобальный набор, общий для всех площадок
+сразу (не то же самое, что список `sites` выше: `sites` решает, *сколько*
+точек его применяют, а этот набор — *что именно* они проверяют).
+
+Посмотреть текущий набор:
+```bash
+curl -s http://<control-api>:8080/api/v1/admin/config/inbound-checks | python3 -m json.tool
+```
+
+Изменить набор портов и/или ICMP (без перезапуска control-api — новое
+значение сразу видно и следующему опросу пробера, и уже идущей агрегации):
+```bash
+curl -s -X PUT http://<control-api>:8080/api/v1/admin/config/inbound-checks \
+  -d '{"ports": [22, 80, 443, 8080], "icmp": true}'
+```
+
+Порты должны быть в диапазоне `1..65535` и не повторяться — иначе `400`.
+Пустой список портов вместе с `"icmp": false` — штатный способ временно
+отключить inbound-проверки целиком, не трогая список площадок:
+```bash
+curl -s -X PUT http://<control-api>:8080/api/v1/admin/config/inbound-checks \
+  -d '{"ports": [], "icmp": false}'
+```
+
+То же самое — на странице `/settings` дашборда, второй формой рядом с
+паузой перед self-check (см. ниже): текстовое поле с портами через запятую
+и чекбокс ICMP.
+
+> Правки через `orchestrator.inbound_checks` в `control-api.yaml` тоже
+> поддерживаются, но только как bootstrap пустой базы данных при самом
+> первом старте — как только в БД есть эта настройка (а она появляется
+> сразу же при первом старте, значение по умолчанию — из YAML), YAML для
+> этой секции игнорируется при всех последующих рестартах. Для стенда,
+> который уже хоть раз запускался, используйте API выше.
+
 ## Управление целями проверки

 Набор egress-целей (`targets`) и типов проверок (`check_types`,