Files
cluster-map/docs/README_RU.md
T
Vitaliy ChefanovandClaude Opus 5.5 4518393ce1 Package cluster-map as a Deckhouse module
Layout, build and templates follow deckhouse/modules-template; dmt lint
passes with no findings (Go files are excluded from the Flant-only
license-header rule, see .dmtlint.yaml).

- module.yaml, openapi schemas with Russian docs, lib-helm templates:
  https modes, ingress class, publicDomainTemplate, node placement,
  priority class, PSS-restricted security context, VPA, PDB, Ingress
  plus Gateway API ListenerSet/HTTPRoute, DexAuthenticator.
- module-sdk hooks: hubble CA from d8-cni-cilium (public certificate
  only), external_auth, copy_custom_certificate.
- The app moves to images/cluster-map/src and is split into packages;
  traffic mode Continuous/OnDemand/Disabled and retention are module
  settings; graceful shutdown; Prometheus metrics and two alerts;
  frontend embedded, English and Russian, strict CSP.
- Built with werf on Deckhouse's published base images; Makefile
  publishes the registry layout modules-actions uses.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-23 21:17:52 +03:00

8.2 KiB
Raw Blame History

title, description, webIfaces
title description webIfaces
Модуль cluster-map Интерактивная карта кластера с живым трафиком из Cilium Hubble.
name
cluster-map

Модуль cluster-map отвечает на вопрос «где живёт этот сервис и с кем он общается» без похода в kubectl. Он показывает кластер деревом инвентаря и картой: namespace, workload'ы с их Service и Ingress, ноды, на которых они работают, реальный трафик между ними, YAML и логи каждого объекта.

Что на экране

  • Дерево инвентаря (слева). Два вида: Namespaces — namespace → тип объекта → объекты; Ноды — нода → namespace → workload'ы. Поиск ищет по имени, образу и хосту Ingress. Дерево управляется с клавиатуры.
  • Карта (в центре). Только то, что выбрано в дереве: один или несколько namespace (Ctrl+клик) или одна нода. Объекты — компактные карточки в рамках namespace, слева направо: Ingress → Service → workload.
    • Сплошные стрелки — связи по конфигурации: backend Ingress и селектор Service.
    • Пунктир с анимацией — реальные соединения из Hubble за выбранное окно (5 минут, 15 минут, час); красный, если Cilium часть из них отбросил. Пиры из других namespace — пунктирные карточки в своих рамках.
    • Если на экране больше 30 направлений трафика, линии бледные, пока не наведёшь курсор на карточку или не выберешь её.
  • Детали (справа). Обзор, Связи (по конфигурации и по трафику, с переходом), живой YAML и логи контейнеров.

Workload'ы под нестандартными контроллерами тоже на карте: Advanced DaemonSet из OpenKruise, кластеры операторов баз данных, статические поды, одиночные Job. Они названы так же, как их называет Hubble, поэтому трафик привязывается к тем же карточкам.

Как собирается трафик

Каждый агент Cilium хранит только кольцевой буфер потоков (по умолчанию 4095); при нескольких сотнях потоков в секунду это около десяти секунд истории. Разовый запрос «за последние 15 минут» молча вернул бы последние секунды. Поэтому модуль держит постоянный поток из Hubble Relay и раскладывает его по минутным корзинам на заданную глубину.

Считаются различные соединения (адрес и порт источника и получателя), а не события Hubble: одно соединение даёт несколько событий. Для каждого направления модуль отдельно показывает, сколько соединений открыто внутри окна (TCP SYN) и сколько получили вердикт DROPPED.

Пробы kubelet и прочий трафик с хостов нод, трафик между нодами, проверки Cilium health и DNS отсекаются на агентах и до модуля не доходят. На обычном кластере это около трёх четвертей всех потоков, и ни один из них не привязан к workload'у. Чтобы всё же собирать их, включите traffic.collectInfraTraffic.

Режимы сбора — параметр traffic.mode:

Режим Цена Окна трафика
Continuous поток открыт всегда; около 100–150m CPU на hubble-relay на нагруженном кластере заполнены сразу при открытии карты
OnDemand поток открыт, только пока с картой работают заполняются с момента открытия карты
Disabled нет только связи по конфигурации

История хранится в памяти: после рестарта пода окна заполняются заново. Строка статуса пишет, сколько из окна реально видно.

Требования

  • Deckhouse Kubernetes Platform 1.72 или новее.
  • Для трафика — модули cni-cilium и cilium-hubble. Без cilium-hubble модуль работает и показывает только связи по конфигурации.
  • Для разграничения доступа — модуль user-authn или любая внешняя аутентификация (auth.externalAuthentication).

Безопасность

Веб-интерфейс читает кластер через собственную учётку модуля (ClusterRole d8:cluster-map): get, list, watch на namespaces, pods, services, nodes, deployments, statefulsets, daemonsets, cronjobs и ingresses и get на pods/log. Secret и ConfigMap он не читает, прав на запись нет.

Отсюда следует: любой, кого пустили в веб-интерфейс, видит все namespace и может читать логи контейнеров — независимо от собственных прав RBAC. Ограничивайте доступ через auth.allowedUserGroups (а также auth.allowedUserEmails и auth.whitelistSourceRanges).

Фронтенд отдаётся со строгой Content Security Policy: только собственные скрипты, стили и API, без inline-кода, без встраивания во фреймы.

Чтобы проверять сертификат Hubble Relay, модулю нужен публичный сертификат hubble CA. Хук модуля читает его из Secret hubble-ca-secret в d8-cni-cilium; jq-фильтр оставляет только ca.crt, ключ CA в значения модуля не попадает.

Метрики и алерты

Под отдаёт метрики Prometheus на порту 9090 (cluster_map_*: состояние потока из Hubble, обработанные потоки, число отслеживаемых соединений, задержки API) и приносит два алерта:

  • ClusterMapHubbleDisconnected — 15 минут нет потоков из Hubble Relay, хотя сбор должен идти.
  • ClusterMapTrackedTuplesHigh — коллектор держит больше 2 миллионов соединений; уменьшите глубину хранения или переключите режим на OnDemand.

Ограничения

  • Одна реплика: история трафика живёт в процессе. Вторая реплика держала бы свою историю и удвоила бы нагрузку на hubble-relay.
  • Доступ по принципу «всё или ничего», см. раздел Безопасность. Показ каждому пользователю только того, что разрешает его RBAC, — в планах.
  • Трафик на уровне L3/L4. Подробности HTTP (пути, коды ответа) требуют L7-видимости Cilium и пока не показываются.