Trim README.md down to an entry point with links, add a component role table
Replaced the duplicated Docker walkthrough (now fully covered in docs/SETUP.md) with a single link, and turned the prose description of each component into an explicit role/state/host table so the architecture reads at a glance. Cuts the file roughly in half. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
ayurishchevandClaude Sonnet 5 committed
1 parent
046cb98036
commit
008ae1b0db
1 file changed
+33
-94
@@ -1,115 +1,54 @@
|
||||
# Cloud IP Validator
|
||||
|
||||
Система проверки освобождённых публичных IPv4-адресов перед их повторной
|
||||
выдачей: каждый адрес привязывается как Floating IP к ВМ-валидатору в
|
||||
облаке (OpenStack), после чего проверяется одновременно в двух
|
||||
выдачей: каждый адрес временно привязывается как Floating IP к
|
||||
ВМ-валидатору в облаке (OpenStack) и проверяется одновременно в двух
|
||||
направлениях — исходящий трафик валидатора (egress: HTTPS/ICMP/опционально
|
||||
SSH до внешних целей) и входящая доступность самого адреса с трёх
|
||||
SSH до внешних целей) и входящая доступность самого адреса с нескольких
|
||||
независимых внешних площадок (inbound: TCP 22/80/443/8080 + ICMP). Итог по
|
||||
каждому адресу — `pass`/`partial`/`fail`, с полной историей проверок в
|
||||
базе данных.
|
||||
каждому адресу — `pass`/`partial`/`fail`, с полной историей проверок,
|
||||
которая сохраняется даже после того, как адрес убрали из очереди (см.
|
||||
[«Реестр адресов»](docs/USAGE.md#реестр-адресов-и-глубина-истории)).
|
||||
|
||||
Четыре компонента: `control-api` (управляющий сервис, единственный со
|
||||
состоянием), `validator-agent` (работает на каждой ВМ-валидаторе, без
|
||||
состояния), `prober` (работает на каждой из трёх внешних площадок, без
|
||||
состояния) и `admin-dashboard` (браузерная веб-панель администратора, без
|
||||
состояния, опциональна). Все четыре общаются между собой только через
|
||||
HTTP API control-api.
|
||||
## Роли компонентов
|
||||
|
||||
| Компонент | Роль | Состояние | Где работает |
|
||||
|---|---|---|---|
|
||||
| `control-api` | Управляющий сервис: ведёт очередь адресов и реестр их истории, назначает валидаторов, агрегирует результаты. Единственная точка, с которой общаются все остальные компоненты. | Хранит (SQLite) | Одна управляющая машина |
|
||||
| `validator-agent` | Привязывает к себе выданный Floating IP и прогоняет egress-проверки до внешних целей. | Без состояния | Каждая ВМ-валидатор в облаке |
|
||||
| `prober` | Проверяет входящую доступность адреса снаружи (TCP/ICMP) — с независимой от облака сети. | Без состояния | Каждая внешняя тестовая площадка |
|
||||
| `admin-dashboard` | Браузерная админ-панель — то же самое, что доступно через API `control-api`, но графически. Опционален. | Без состояния | Любая машина с сетевым доступом к `control-api` |
|
||||
|
||||
Все четыре общаются между собой **только** через HTTP API `control-api` —
|
||||
прямых связей между остальными компонентами нет. Подробная схема
|
||||
control/data plane — в [docs/DIAGRAMS.md](docs/DIAGRAMS.md).
|
||||
|
||||
## Документация
|
||||
|
||||
| Документ | Для чего |
|
||||
|---|---|
|
||||
| [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/SETUP.md](docs/SETUP.md) | Развёртывание с нуля: бинарники или сборка из исходников, конфигурация, systemd **и** Docker/docker-compose — пошагово |
|
||||
| [docs/USAGE.md](docs/USAGE.md) | Повседневная работа: постановка адресов в очередь, сканирование Floating IP, наблюдение за статусом, реестр и история, разбор результатов |
|
||||
| [docs/API.md](docs/API.md) | Спецификация HTTP API `control-api` и примеры запросов (curl) |
|
||||
| [docs/DASHBOARD.md](docs/DASHBOARD.md) | Устройство `admin-dashboard`: страницы, поиск/фильтр, обработка ошибок |
|
||||
| [docs/DIAGRAMS.md](docs/DIAGRAMS.md) | Диаграммы потоков данных: control plane, egress-проверка, телеметрия |
|
||||
| [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) деплоя — открыть в браузере |
|
||||
| [docs/CONTROL_DATA_PLANE.html](docs/CONTROL_DATA_PLANE.html) | Презентационные схемы control/data plane для docker-compose-деплоя — открыть в браузере |
|
||||
|
||||
## Быстрый старт (60 секунд, без OpenStack)
|
||||
## Быстрый старт
|
||||
|
||||
Хотите просто увидеть систему в работе — без реального облака:
|
||||
Посмотреть систему в работе без реального облака (60 секунд):
|
||||
|
||||
```bash
|
||||
go build ./... && go test ./...
|
||||
scripts/run-local-e2e.sh
|
||||
```
|
||||
|
||||
Скрипт сам поднимет все три компонента как локальные процессы (в режиме
|
||||
`openstack.mode: mock`) и прогонит один тестовый адрес через полный цикл
|
||||
проверки, включая демонстрацию восстановления после сбоя валидатора.
|
||||
Подробности — в [docs/LOCAL_E2E.md](docs/LOCAL_E2E.md).
|
||||
Поднимет все компоненты как локальные процессы (`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`).
|
||||
Для реального стенда (systemd-юниты или Docker/docker-compose, на одной
|
||||
машине или распределённо) — по шагам в
|
||||
[docs/SETUP.md](docs/SETUP.md), начиная с
|
||||
[«Получение бинарников»](docs/SETUP.md#получение-бинарников).
|
||||
Reference in new issue
Block a user