From 2246369b646d8de5af0c06755da35dc3983ca167 Mon Sep 17 00:00:00 2001 From: ayurishchev Date: Sun, 13 Sep 2026 21:38:51 +0300 Subject: [PATCH] Add control/data plane diagrams for microservices deployment to docs Standalone HTML page (docs/CONTROL_DATA_PLANE.html) showing the docker-compose deployment topology (hosts, COMPOSE_PROFILES) and the egress/inbound check traffic, refined through several presentation review passes. Linked from README.md's docs table and docs/DIAGRAMS.md alongside the existing Mermaid diagrams. Co-Authored-By: Claude Sonnet 5 Claude-Session: https://claude.ai/code/session_01NeVbMVEiE7XQAkBd7HQgj6 --- README.md | 1 + docs/CONTROL_DATA_PLANE.html | 439 +++++++++++++++++++++++++++++++++++ docs/DIAGRAMS.md | 5 + 3 files changed, 445 insertions(+) create mode 100644 docs/CONTROL_DATA_PLANE.html diff --git a/README.md b/README.md index 8c36136..dbc7dca 100644 --- a/README.md +++ b/README.md @@ -27,6 +27,7 @@ HTTP API control-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: команды `docker build`/`docker run`, переменные окружения | +| [docs/CONTROL_DATA_PLANE.html](docs/CONTROL_DATA_PLANE.html) | Презентационные схемы control plane и data plane для микросервисного (docker-compose) деплоя — открыть в браузере | ## Быстрый старт (60 секунд, без OpenStack) diff --git a/docs/CONTROL_DATA_PLANE.html b/docs/CONTROL_DATA_PLANE.html new file mode 100644 index 0000000..ba9b931 --- /dev/null +++ b/docs/CONTROL_DATA_PLANE.html @@ -0,0 +1,439 @@ + + + + + +Control Plane и Data Plane — Cloud IP Validator + + + + + +
+ +
+ Cloud IP Validator · микросервисный деплой +

Control Plane и Data Plane

+

+ Система ревалидации освобождённых публичных IPv4-адресов в облаке на + базе SDN VK Cloud. С переходом на docker-compose + каждый компонент — control-api, + admin-dashboard, prober, + validator-agent — разворачивается отдельным + контейнером по своему профилю (COMPOSE_PROFILES), на + своём хосте. Ниже показано, как они связаны между собой (control + plane) и что именно проверяется в реальном сетевом трафике (data + plane). +

+
+ +
+

1 Control plane: кто кем управляет

+

+ Оператор — через веб-панель или напрямую curl'ом — обращается к + единственному источнику истины, control-api. validator-agent + и prober сами инициируют все вызовы (pull-модель): + регистрируются, шлют heartbeat, забирают назначение, отчитываются о + результатах. control-api сам к ним не обращается. +

+ +
+
+ + + + + + + + + + Оператор + инженер эксплуатации + + + + Управляющая машина + profiles: control-plane, dashboard + + + admin-dashboard + браузерная панель оператора · :8090 + + + + control-api + HTTP API + оркестратор + SQLite · единственный stateful-сервис + :8080 + + + + + + + + curl /api/v1/admin/* · :8080 + + + + OpenStack API · mode: real + + + OpenStack + Keystone · Neutron / Sprut + associate / disassociate floating ip + + + + Внешние площадки ×N + profiles: prober + + + + + prober + TCP + ICMP пробы наружу + по 1 на площадку + + + + ВМ-валидаторы ×N + profiles: validator + + + + + validator-agent + egress-проверки + self-check + по 1 на ВМ-валидатор + + + + + register · heartbeat + assignments · results + → /api/v1/probers/* + + + + + register · heartbeat + self-check · events + results · complete + → /api/v1/agents/* + + + + управляющий вызов (control-plane API) + + только при openstack.mode: real + +
+
+ control-api — единственный компонент с состоянием + (SQLite) и единственная точка принятия решений: какой IP кому + назначить и когда считать проверку завершённой. Остальные сервисы + развёрнуты по одному контейнеру на профиль docker-compose — на + управляющей машине, на каждой внешней площадке и на каждой + ВМ-валидаторе; все стрелки к control-api идут от них — это + они опрашивают control-api, а не наоборот. Связь с облаком идёт + через сеть OpenStack — Neutron и его альтернативная реализация в + SDN VK Cloud, Sprut, — поэтому на схеме указаны оба. +
+
+
+ +
+ +
+

2 Data plane: что реально проверяется

+

+ Один и тот же публичный адрес проверяется одновременно с двух + независимых сторон. Этот сетевой трафик control-api не видит + напрямую — он получает только заявленный агентами результат по + отдельному управляющему каналу (см. схему control plane выше). +

+ +
+
+ + + + + + + + + + + + + Floating IP + 203.0.113.10 + + + + ВМ-валидатор + validator-agent + слушает 22/80/443/8080 + + + + 1. self-check + проверки + + + + + + IP-echo сервис + api.ipify.org и т.п., вне облака + + + + GET, сравнение адреса + + + + Целевые серверы (targets) + HTTPS · ICMP · SSH (опционально) + + + + 2. HTTPS / ICMP / SSH + + + + + + prober ×N площадок + внешние тестовые точки, + независимо друг от друга + + + + TCP 22/80/443/8080 + ICMP + +
+
+ Egress (слева): validator-agent сам + всегда обращается наружу через назначенный Floating IP — сначала + self-check во внешнем IP-echo сервисе (адрес обязан быть вне + облака — иначе SNAT не сработает), затем проверки из конфига до + целей. Inbound (справа): N внешних площадок + независимо стучатся в тот же адрес снаружи. Только сочетание + обоих направлений даёт полную картину — адрес может нормально + работать «наружу», но быть заблокирован для конкретной внешней + сети, и наоборот. +
+
+ egress-проверка (от validator-agent, через FIP) + inbound-проверка (от внешних площадок, в FIP) +
+
+
+ + + +
+ + diff --git a/docs/DIAGRAMS.md b/docs/DIAGRAMS.md index e72bcaf..80a5279 100644 --- a/docs/DIAGRAMS.md +++ b/docs/DIAGRAMS.md @@ -5,6 +5,11 @@ оператора). Диаграммы — в формате Mermaid, рендерятся нативно на GitHub/GitLab и в большинстве современных Markdown-просмотрщиков. +Презентационная версия этих же двух разрезов (control plane и data plane) +под микросервисный (docker-compose) деплой, с топологией по хостам и +профилям `COMPOSE_PROFILES` — [CONTROL_DATA_PLANE.html](CONTROL_DATA_PLANE.html) +(самодостаточный HTML-файл, открыть в браузере). + ## Как читать диаграммы Единое условное обозначение стрелок для всех диаграмм: