cloud-ip-validator/README.md

# Cloud IP Validator

Система проверки освобождённых публичных IPv4-адресов перед их повторной
выдачей: каждый адрес привязывается как Floating IP к ВМ-валидатору в
облаке (OpenStack), после чего проверяется одновременно в двух
направлениях — исходящий трафик валидатора (egress: HTTPS/ICMP/опционально
SSH до внешних целей) и входящая доступность самого адреса с трёх
независимых внешних площадок (inbound: TCP 22/80/443/8080 + ICMP). Итог по
каждому адресу — `pass`/`partial`/`fail`, с полной историей проверок в
базе данных.

Четыре компонента: `control-api` (управляющий сервис, единственный со
состоянием), `validator-agent` (работает на каждой ВМ-валидаторе, без
состояния), `prober` (работает на каждой из трёх внешних площадок, без
состояния) и `admin-dashboard` (браузерная веб-панель администратора, без
состояния, опциональна). Все четыре общаются между собой только через
HTTP API control-api.

## Документация

| Документ | Для чего |
|---|---|
| [docs/SETUP.md](docs/SETUP.md) | Развёртывание из готовых бинарников (`bin/`) или сборка из исходников, конфигурация, первый запуск стенда — с нуля |
| [docs/USAGE.md](docs/USAGE.md) | Повседневная работа: постановка адресов в очередь, наблюдение за статусом, разбор результатов |
| [docs/API.md](docs/API.md) | Спецификация HTTP API control-api и примеры запросов (curl) |
| [docs/DASHBOARD.md](docs/DASHBOARD.md) | Браузерная админ-панель (`admin-dashboard`) — то же самое API, но графически |
| [docs/DIAGRAMS.md](docs/DIAGRAMS.md) | Диаграммы потоков данных: control plane, поток проверки до целевого сервера, поток телеметрии |
| [docs/LOCAL_E2E.md](docs/LOCAL_E2E.md) | Полностью офлайн-прогон всей системы одним скриптом — без реального облака и интернета |

## Быстрый старт (60 секунд, без OpenStack)

Хотите просто увидеть систему в работе — без реального облака:

```bash
go build ./... && go test ./...
scripts/run-local-e2e.sh
```

Скрипт сам поднимет все три компонента как локальные процессы (в режиме
`openstack.mode: mock`) и прогонит один тестовый адрес через полный цикл
проверки, включая демонстрацию восстановления после сбоя валидатора.
Подробности — в [docs/LOCAL_E2E.md](docs/LOCAL_E2E.md).

## Быстрый старт (реальный стенд)

1. Возьмите готовые бинарники из `bin/` (Linux x86_64, статические, без
   зависимостей) или соберите из исходников, подготовьте конфиги —
   [docs/SETUP.md](docs/SETUP.md#получение-бинарников).
2. Разверните `control-api` на управляющей машине, `validator-agent` —
   на каждой ВМ-валидаторе, `prober` — на каждой из трёх площадок
   ([пошагово в docs/SETUP.md](docs/SETUP.md#развёртывание-control-api)).
3. Добавьте адреса в очередь и наблюдайте за результатом —
   [docs/USAGE.md](docs/USAGE.md).

```bash
curl -s http://<control-api>:8080/api/v1/admin/status | python3 -m json.tool
```