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 (работает на каждой из трёх внешних площадок, без состояния). Все три общаются между собой только через HTTP API control-api.

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

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

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