ayurishchevandClaude Sonnet 5
582b44f314
Adds POST /api/v1/admin/ips/scan (plus an optional periodic ticker) to
discover free Floating IPs in the OpenStack project and feed them straight
into the check queue. More importantly, decouples check/event history from
ip_queue's lifecycle: a new ip_registry table (migration 0007) gives every
address ever submitted a durable identity, so deleting it from the queue no
longer destroys its history — it's still reachable via the new
GET /api/v1/admin/registry[/{ip}] endpoints and the dashboard's /registry
pages, with retention depth configurable in check cycles per address
(history_retention_cycles, 0 = unlimited).
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
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.
Быстрый старт (реальный стенд)
- Возьмите готовые бинарники из
bin/(Linux x86_64, статические, без зависимостей) или соберите из исходников, подготовьте конфиги — docs/SETUP.md. - Разверните
control-apiна управляющей машине,validator-agent— на каждой ВМ-валидаторе,prober— на каждой из трёх площадок (пошагово в docs/SETUP.md). - Добавьте адреса в очередь и наблюдайте за результатом — 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).