Files
cluster-map/docs/README_RU.md
T
Виталий ЧефановandClaude Opus 5.5 c50020e420 v0.10.0: each viewer sees what their own RBAC allows
Until now anyone admitted through Dex saw every namespace and every log,
read with the module's service account. auth.visibility: ViewerRBAC (the
default) asks the API server as the viewer, with the token the
DexAuthenticator forwards: list pods in all namespaces means the whole
cluster; otherwise the namespaces where they can list pods. Logs also
need get pods/log, node cards list nodes, cluster-wide alerts are for
cluster-wide viewers. Traffic to a hidden namespace keeps its counts with
the peer shown as hidden. One minute cache per token hash, SSARs in
parallel (8), a cluster-wide viewer costs two.

Verified against the live cluster with two real tokens: a service
account with view in one namespace got that namespace only (0 nodes, 403
on another namespace's YAML and logs, 403 on node usage); the module's
own account, cluster-wide, got all 56 namespaces and 6 nodes; no token,
401. auth.visibility: Everything keeps the old behaviour. The
DexAuthenticator now forwards the token when either actions or ViewerRBAC
need it (templates/_helpers.tpl).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-25 01:03:50 +03:00

17 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 направлений трафика, линии бледные, пока не наведёшь курсор на карточку или не выберешь её.
  • Детали (справа). Обзор (одна строка — работает или нет, проблемы объекта, его параметры, CPU и память относительно запросов и лимитов, его поды), Связи (по конфигурации и по трафику, с переходом), живой YAML, События, логи контейнеров и действия, которые разрешены пользователю.
  • Проблемы (кнопка в верхней панели). Всё, что сломано прямо сейчас, сначала самое серьёзное, с фильтром по приложениям и системным namespace; клик открывает объект.

Карточки нельзя перетащить, пока не открыт замок под кнопками масштаба, — случайный клик не перестроит карту. Последняя кнопка сохраняет текущую карту картинкой PNG.

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

Проблемы и алерты

Карточка с проблемой несёт значок: жёлтый ! — предупреждение, красный ! — ошибка. Рамки и карточки namespace, рамки нод и дерево окрашиваются по самой серьёзной проблеме внутри. Источники:

  • Состояние объектов: контейнеры в CrashLoopBackOff, ImagePullBackOff и подобном, недавние перезапуски и убийства за нехватку памяти, поды в ожидании или без места для запуска, workload'ы, у которых больше 2 минут не готовы все или часть реплик, застрявшая выкатка, CronJob с неудачным последним запуском, Service без готовых подов, Ingress на несуществующий Service, нода не готова или ей не хватает памяти, диска или PID.
  • Warning-события за последние 30 минут, сгруппированные по объекту и причине. Сбои планирования, томов и back-off дают значок сразу; любой другой причине нужно пять повторов в пределах окна, до этого она в списке без значка — одна проваленная проба во время рестарта не красит карту. Счётчик события накапливается с первого появления, поэтому давнее событие пересчитывается на окно: 40 проваленных проб за двое суток — это раз в час, а не всплеск.
  • Алерты Prometheus, которые Deckhouse зеркалирует в объекты ClusterAlert. Алерт привязывается по меткам (deployment, statefulset, daemonset, pod, service, ingress, node, namespace); алерт без объекта и namespace попадает в список кластера. severity_level 1–3 — ошибка, 4–6 — предупреждение, 7–9 — информация.

Записи уровня «для сведения» (нода закрыта для новых подов, одиночное обычное предупреждение) есть в списке, но значка не дают. Проблемы пересчитываются при каждом запросе карты, открытая страница обновляет их раз в минуту.

Уязвимости

Если установлен operator-trivy, у карточки, в образах которой есть CVE уровня CRITICAL, в правом нижнем углу красный щит с их числом. В панели деталей — все CVE уровней CRITICAL и HIGH образов workload'а: какие пакеты затронуты, стоящая версия и версия с исправлением, ссылка на описание. Одна CVE считается на карточке один раз, в скольких бы пакетах и контейнерах она ни нашлась. Уязвимости показываются отдельно от проблем: они есть почти в каждом образе, и значок на каждой карточке скрыл бы то, что действительно сломано.

Данные берутся из объектов VulnerabilityReport, которые пишет operator-trivy, поэтому видны только namespace, которые он сканирует (с меткой security-scanning.deckhouse.io/enabled), и только уровни, оставленные его настройкой severities.

Действия

При actions.enabled (по умолчанию включено) в панели деталей есть:

Объект Действия
Deployment, StatefulSet перезапуск (как kubectl rollout restart), масштабирование на 0–100 реплик
DaemonSet перезапуск
CronJob запустить сейчас (как kubectl create job --from=cronjob/…), приостановить, возобновить
Под (в таблице «Нагрузка») удалить, чтобы контроллер запустил новый
Нода (клик по рамке ноды) закрыть для новых подов (cordon) и открыть обратно

Каждое действие требует подтверждения и выполняется от имени пользователя: DexAuthenticator передаёт модулю собственный токен пользователя, модуль отправляет запрос в API-сервер с этим токеном, и API-сервер проверяет RBAC пользователя. Кнопка показывается, только если SelfSubjectAccessReview подтверждает право. Сервисный аккаунт модуля не получает прав на запись, в аудит-логе API-сервера записан пользователь; модуль тоже пишет каждое действие в лог с именем пользователя.

Запросы на запись с других сайтов отклоняются: модуль проверяет Sec-Fetch-Site, Origin и тип содержимого JSON.

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

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

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

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

Трафик между подами на разных нодах трассируется дважды: при выходе с ноды отправителя (to-overlay) и при доставке в под получателя (to-endpoint). Первая копия тоже отсекается на агентах, если получатель — под; это убирает около пятой части оставшихся потоков, ни одно число при этом не меняется.

Режимы сбора — параметр 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, events, deployments, statefulsets, daemonsets, cronjobs, ingresses, clusteralerts Deckhouse и vulnerabilityreports operator-trivy, get и list на pods и nodes из metrics.k8s.io и get на pods/log. Secret и ConfigMap он не читает, прав на запись нет. Изменения идут через действия, которые выполняются от имени пользователя.

Что видит пользователь, определяет его собственный RBAC (auth.visibility: ViewerRBAC, по умолчанию). С каждым запросом DexAuthenticator передаёт токен пользователя; модуль спрашивает API-сервер от его имени (SelfSubjectAccessReview) и кеширует ответ на минуту:

  • list pods во всех namespace — виден весь кластер;
  • иначе — только namespace, где пользователь может list pods; карточки, YAML, события, нагрузка и уязвимости остальных namespace не отдаются, а сосед по трафику оттуда показывается скрытым — с соединениями, но без имени;
  • для логов контейнеров нужно ещё get pods/log в этом namespace, для карточек нод и вида по нодам — list nodes; общекластерные алерты видны только пользователям с доступом ко всему кластеру.

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

Фронтенд отдаётся со строгой 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.
  • Видимость — по namespace: пользователь, который может смотреть поды в namespace, видит все его карточки, включая манифесты Deployment и Service, даже если его роль не дала бы прочитать эти объекты по отдельности.
  • Для алертов нужен модуль prometheus, он создаёт объекты ClusterAlert. Без него карта показывает проблемы только по состоянию объектов и событиям.
  • Трафик на уровне L3/L4. Подробности HTTP (пути, коды ответа) требуют L7-видимости Cilium и пока не показываются.