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/`) или сборка из исходников, конфигурация, первый запуск стенда — с нуля, включая исчерпывающую инструкцию по Docker/docker-compose |
| [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) | Полностью офлайн-прогон всей системы одним скриптом — без реального облака и интернета |
| [deploy/docker/RUN.txt](deploy/docker/RUN.txt) | Краткая шпаргалка команд `docker build`/`docker run` по компонентам (без пояснений) — подробный пошаговый разбор, включая docker-compose, см. в [docs/SETUP.md](docs/SETUP.md#развёртывание-в-docker) |
| [docs/CONTROL_DATA_PLANE.html](docs/CONTROL_DATA_PLANE.html) | Презентационные схемы control plane и data plane для микросервисного (docker-compose) деплоя — открыть в браузере |

## Быстрый старт (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
```

## Развёртывание в Docker

Все четыре компонента можно собрать и запустить как отдельные Docker-образы
вместо systemd-юнитов — Dockerfile'ы лежат в `deploy/docker/<компонент>/`.
Исчерпывающая пошаговая инструкция (docker-compose для одного хоста и для
распределённого по нескольким хостам стенда, точечный `docker build`/`docker
run` по компоненту, обновление образов, диагностика) —
[docs/SETUP.md → «Развёртывание в Docker»](docs/SETUP.md#развёртывание-в-docker);
краткая шпаргалка тех же команд — в
[deploy/docker/RUN.txt](deploy/docker/RUN.txt).

- `prober`, `validator-agent`, `admin-dashboard` — конфиг генерируется
  внутри контейнера из переменных окружения (`docker-entrypoint.sh` +
  `envsubst`), готовых образов для монтирования не требуется.
- `control-api` — конфиг содержит списки (validators/sites/targets/
  ip_addresses) и имена env-переменных для OpenStack-креденшлов, поэтому
  монтируется файлом (`-v .../control-api.yaml:/etc/cloud-ip-validator/control-api.yaml:ro`),
  а база данных — отдельным volume для персистентности.

Пример для `prober`:

```bash
docker build --platform linux/amd64 -t cloud-ip-validator-prober -f deploy/docker/prober/Dockerfile .
docker run -d --platform linux/amd64 --cap-add NET_RAW --name prober \
  -e PROBER_SITE_ID=<site_id> \
  -e PROBER_CONTROL_API_URL=<http://control-api-host:port> \
  cloud-ip-validator-prober
```

`site_id` должен быть заранее зарегистрирован на control-api
(`PUT /api/v1/admin/config/sites/{index}`) — иначе контейнер завершится с
ошибкой регистрации. Аналогичные команды для остальных трёх компонентов —
в [deploy/docker/RUN.txt](deploy/docker/RUN.txt).

### Запуск всех компонентов через docker-compose

Для совместного запуска (сеть, healthcheck, volume для базы данных) есть
`docker-compose.yml` в `deploy/docker/` — разбит на базовый файл и
окружения: `docker-compose.override.yml` (dev, подхватывается автоматически)
и `docker-compose.prod.yml` (прод). Набор запускаемых сервисов на каждом
хосте задаётся через `COMPOSE_PROFILES` в `.env`-файле (`control-plane`,
`dashboard`, `prober`, `validator`) — так один и тот же compose можно
поднять целиком локально или по частям на разных хостах (управляющая
машина / внешняя площадка с `prober` / ВМ-валидатор), как в реальной
топологии.

```bash
cd deploy/docker
cp .env.example .env
cp control-api/control-api.docker.example.yaml control-api/control-api.docker.yaml
docker compose up -d --build
```

Для прода: `docker compose -f docker-compose.yml -f docker-compose.prod.yml --env-file .env.prod up -d --build`
(см. комментарии в `.env.prod.example`).