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	Развёртывание из готовых бинарников (bin/) или сборка из исходников, конфигурация, первый запуск стенда — с нуля
docs/USAGE.md	Повседневная работа: постановка адресов в очередь, наблюдение за статусом, разбор результатов
docs/API.md	Спецификация HTTP API control-api и примеры запросов (curl)
docs/DASHBOARD.md	Браузерная админ-панель (admin-dashboard) — то же самое API, но графически
docs/DIAGRAMS.md	Диаграммы потоков данных: control plane, поток проверки до целевого сервера, поток телеметрии
docs/LOCAL_E2E.md	Полностью офлайн-прогон всей системы одним скриптом — без реального облака и интернета
deploy/docker/RUN.txt	Сборка и запуск каждого компонента в Docker: команды docker build/docker run, переменные окружения
docs/CONTROL_DATA_PLANE.html	Презентационные схемы control plane и data plane для микросервисного (docker-compose) деплоя — открыть в браузере

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

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

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

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

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

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

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

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

Все четыре компонента можно собрать и запустить как отдельные Docker-образы вместо systemd-юнитов — Dockerfile'ы лежат в deploy/docker/<компонент>/, полные команды сборки/запуска и список переменных окружения — в 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:

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.

Запуск всех компонентов через 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 / ВМ-валидатор), как в реальной топологии.

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).