--- 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 направлений трафика, линии бледные, пока не наведёшь курсор на карточку или не выберешь её. - **Детали** (справа). Обзор (одна строка — работает или нет, проблемы объекта, его параметры, CPU и память относительно запросов и лимитов, его поды), Связи (по конфигурации и по трафику, с переходом), живой YAML, События, логи контейнеров и действия, которые разрешены пользователю. - **Проблемы** (кнопка в верхней панели). Всё, что сломано прямо сейчас, сначала самое серьёзное, с фильтром по приложениям и системным namespace; клик открывает объект. Карточки нельзя перетащить, пока не открыт замок под кнопками масштаба, — случайный клик не перестроит карту. Последняя кнопка сохраняет текущую карту картинкой PNG. Workload'ы под нестандартными контроллерами тоже на карте: Advanced DaemonSet из OpenKruise, кластеры операторов баз данных, статические поды, одиночные Job. Они названы так же, как их называет Hubble, поэтому трафик привязывается к тем же карточкам. ## Проблемы и алерты Карточка с проблемой несёт значок: жёлтый `!` — предупреждение, красный `!` — ошибка. Рамки и карточки namespace, рамки нод и дерево окрашиваются по самой серьёзной проблеме внутри. Источники: - **Состояние объектов**: контейнеры в `CrashLoopBackOff`, `ImagePullBackOff` и подобном, перезапуски и убийства за нехватку памяти за последние 30 минут (за сутки, если контейнер перезапускался три раза и больше), поды в ожидании или без места для запуска, 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 — информация. Записи уровня «для сведения» (нода закрыта для новых подов, одиночное обычное предупреждение) есть в списке, но значка не дают. Проблемы пересчитываются при каждом запросе карты, открытая страница обновляет их раз в минуту. Обычная история рестартов истекает через 30 минут независимо от накопленного счётчика; для повторных OOM остаётся окно 24 часа. `TopologyAwareHintsDisabled` показывается для сведения только у Service с готовым выбранным backend: Kubernetes использует обычную маршрутизацию по кластеру, когда не может назначить hints. Отсутствующие backend по-прежнему дают предупреждения. Настройки маршрутизации кластера не меняются. ## Уязвимости Если установлен 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` | нет | только связи по конфигурации | История хранится в памяти: после рестарта пода окна заполняются заново. Строка статуса пишет, сколько из окна реально видно. ## Подробности HTTP Там, где Cilium разбирает HTTP на порту, карта добавляет к связи число запросов, ответы по классам (2xx, 3xx, 4xx, 5xx), задержку p50 и p95 и десять самых нагруженных путей. Связь, на которой были ответы 5xx, рисуется цветом предупреждения. Пути группируются: строка запроса отбрасывается, а сегменты, похожие на идентификаторы (числа, UUID, длинные hex-строки), заменяются на `:id` — `/api/users/42?x=1` и `/api/users/43` попадают в одну строку `/api/users/:id`. Cilium разбирает HTTP только на портах, упомянутых в L7-правиле `CiliumNetworkPolicy`; сам модуль таких политик не создаёт. Как включить это для одного сервиса, не ограничивая его трафик, — в [примере](EXAMPLES_RU.md#подробности-http-для-одного-сервиса). Учтите: - соединения на этот порт идут через прокси Envoy на ноде: доли миллисекунды на запрос и CPU агента Cilium пропорционально числу запросов; - порт должен говорить на обычном HTTP/1.x или HTTP/2 (h2c): внутрь TLS Envoy не заглядывает, поэтому правило ставится на порт бэкенда за Ingress, а не на 443. gRPC разбирается, но его статус лежит в трейлерах, и каждый вызов виден как 200; поток gRPC или WebSocket — это один запрос, а не последовательность сообщений; - заголовки запроса и ответа попадают в Hubble, включая `Authorization` и cookie. Модуль запрашивает у Hubble только метод, путь, код и задержку; заголовки он не читает, не хранит и не показывает. Другие клиенты Hubble (Hubble UI, `hubble observe`) их видят. ## Требования - 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`. Без него карта показывает проблемы только по состоянию объектов и событиям. - Подробности HTTP — только там, где CiliumNetworkPolicy включает разбор L7, см. [Подробности HTTP](#подробности-http). Остальные протоколы показываются на уровне L3/L4. ## Уточнение диагностики после перезапуска Обычный перезапуск контейнера отмечается в течение 30 минут. Накопленный счётчик перезапусков за всю жизнь pod’а не доказывает повторные сбои за сутки; расширенное окно остаётся для последних завершений OOMKilled. Текущий CrashLoopBackOff и неготовность проверяются независимо. Сервис без endpoints остаётся предупреждением, кроме подтверждённого случая, когда все подходящие Deployment/StatefulSet/DaemonSet уже обработали конфигурацию и ожидают ноль pod’ов. Тогда запись информационная. Неизвестное состояние, устаревший статус контроллера, подходящий CronJob или незавершённый pod сохраняют предупреждение.