Files
cluster-map/docs/README_RU.md
T
Виталий ЧефановandClaude Opus 5.5 4c5eb288cb v0.11.0: HTTP details on links where Cilium parses L7
Requests, response classes, p50/p95 latency and the busiest paths per link,
from Hubble L7 flows (method, path, status, latency only; headers are never
requested). The two inner legs of a proxied connection (Envoy -> pod, and the
pod's answers to the node on an ephemeral port) are no longer counted as
links.

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

121 lines
20 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 направлений трафика, линии бледные, пока не наведёшь курсор на карточку или не выберешь её.
- **Детали** (справа). Обзор (одна строка — работает или нет, проблемы объекта, его параметры, 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` | нет | только связи по конфигурации |
История хранится в памяти: после рестарта пода окна заполняются заново. Строка статуса пишет, сколько из окна реально видно.
## Подробности 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.