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

67 lines
8.2 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
---
title: "Модуль cluster-map"
description: "Интерактивная карта кластера с живым трафиком из Cilium Hubble."
webIfaces:
- 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 и пока не показываются.