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>
This commit is contained in:
Vitaliy Chefanov
2026-09-23 21:17:52 +03:00
co-authored by Claude Opus 5.5
parent 41f9b47556
commit 4518393ce1
82 changed files with 5712 additions and 1415 deletions
+5
View File
@@ -0,0 +1,5 @@
---
title: "The cluster-map module: configuration"
---
<!-- SCHEMA -->
+5
View File
@@ -0,0 +1,5 @@
---
title: "Модуль cluster-map: настройки"
---
<!-- SCHEMA -->
+42
View File
@@ -0,0 +1,42 @@
---
title: "The cluster-map module: examples"
---
## Enable the module for administrators
```yaml
apiVersion: deckhouse.io/v1alpha1
kind: ModuleConfig
metadata:
name: cluster-map
spec:
enabled: true
version: 1
settings:
auth:
allowedUserGroups:
- admins
```
The web interface opens at `cluster-map.<publicDomainTemplate>`.
## Collect traffic only while the map is in use
```yaml
spec:
settings:
traffic:
mode: OnDemand
onDemandIdleMinutes: 15
```
## Keep a day of traffic
```yaml
spec:
settings:
traffic:
retentionMinutes: 1440
```
Memory grows with retention; watch `cluster_map_traffic_tracked_tuples` and the `ClusterMapTrackedTuplesHigh` alert.
+42
View File
@@ -0,0 +1,42 @@
---
title: "Модуль cluster-map: примеры"
---
## Включить модуль для администраторов
```yaml
apiVersion: deckhouse.io/v1alpha1
kind: ModuleConfig
metadata:
name: cluster-map
spec:
enabled: true
version: 1
settings:
auth:
allowedUserGroups:
- admins
```
Веб-интерфейс открывается по адресу `cluster-map.<publicDomainTemplate>`.
## Собирать трафик только во время работы с картой
```yaml
spec:
settings:
traffic:
mode: OnDemand
onDemandIdleMinutes: 15
```
## Хранить трафик за сутки
```yaml
spec:
settings:
traffic:
retentionMinutes: 1440
```
Память растёт вместе с глубиной хранения — следите за `cluster_map_traffic_tracked_tuples` и алертом `ClusterMapTrackedTuplesHigh`.
+66
View File
@@ -0,0 +1,66 @@
---
title: "The cluster-map module"
description: "Interactive topology map of the cluster with live traffic from Cilium Hubble."
webIfaces:
- name: cluster-map
---
The `cluster-map` module answers "where does this service live and what does it talk to" without a trip through `kubectl`. It shows the cluster as an inventory tree and a topology map: namespaces, workloads with their Services and Ingresses, the nodes they run on, real traffic between them, and the YAML and logs of each object.
## What is on the screen
- **Inventory tree** (left). Two views: *Namespaces* — namespace → object kind → objects; *Nodes* — node → namespace → workloads. Search matches names, images and Ingress hosts. The tree is keyboard-navigable.
- **Map** (centre). Only what is selected in the tree: one or several namespaces (Ctrl+click) or one node. Objects are compact cards inside namespace boxes, laid out left to right: Ingress → Service → workload.
- Solid arrows are configuration links: Ingress backends and Service selectors.
- Dashed animated arrows are real connections from Hubble over the chosen window (5 minutes, 15 minutes, 1 hour); red when Cilium dropped some of them. Peers from other namespaces appear as dashed cards in their own boxes.
- With more than 30 traffic directions on screen, lines stay faint until a card is hovered or selected.
- **Details** (right). Overview, Links (configuration and traffic, clickable), live YAML, and container logs.
Workloads managed by non-native controllers are included: Advanced DaemonSets of OpenKruise, database operator clusters, static pods, standalone Jobs. They are named the way Hubble names workloads, so their traffic attaches to the same cards.
## How traffic is collected
Every Cilium agent keeps only a ring buffer of flows (4095 by default); at a few hundred flows per second this is about ten seconds of history. A one-off query "for the last 15 minutes" would silently return the last few seconds. The module therefore keeps a follow stream from Hubble Relay and aggregates it into per-minute buckets for the configured retention.
Counts are **distinct connections** (source and destination address and port), not Hubble events: one connection produces several events. For each direction the module also reports how many connections were opened (TCP SYN) inside the window and how many had a `DROPPED` verdict.
Kubelet probes and other traffic originating from node hosts, node-to-node traffic, Cilium health checks and DNS are filtered at the agents and never reach the module. On a typical cluster this is about three quarters of all flows and none of it maps to a workload. Set `traffic.collectInfraTraffic` to collect it anyway.
The collector runs in one of three modes, see `traffic.mode`:
| Mode | Cost | Traffic windows |
|---|---|---|
| `Continuous` | stream always open; about 100–150m CPU on hubble-relay on a busy cluster | full as soon as the map is opened |
| `OnDemand` | stream only while someone uses the map | fill from the moment the map is opened |
| `Disabled` | none | configuration links only |
History is kept in memory: after a pod restart the windows fill again. The status line says how much of the window has actually been seen.
## Requirements
- Deckhouse Kubernetes Platform 1.72 or newer.
- For traffic: the `cni-cilium` and `cilium-hubble` modules. Without `cilium-hubble` the module works and shows configuration links only.
- For access control: the `user-authn` module, or any external authentication (`auth.externalAuthentication`).
## Security
The web interface reads the cluster through the module's own service account (`d8:cluster-map` ClusterRole): `get`, `list`, `watch` on namespaces, pods, services, nodes, deployments, statefulsets, daemonsets, cronjobs and ingresses, and `get` on `pods/log`. It never reads Secrets or ConfigMaps and has no write verbs.
This means **anyone admitted to the web interface sees every namespace and can read container logs**, whatever their own RBAC permissions are. Restrict access with `auth.allowedUserGroups` (and optionally `auth.allowedUserEmails` and `auth.whitelistSourceRanges`).
The frontend is served with a strict Content Security Policy: only its own scripts, styles and API, no inline code, no framing.
To verify the Hubble Relay certificate the module needs the public certificate of the hubble CA. A module hook reads it from the `hubble-ca-secret` Secret in `d8-cni-cilium`; the jq filter keeps only `ca.crt`, the CA key never reaches the module values.
## Metrics and alerts
The pod exposes Prometheus metrics on port `9090` (`cluster_map_*`: Hubble stream state, flows processed, tracked connections, API latency) and ships two alerts:
- `ClusterMapHubbleDisconnected` — no flows from Hubble Relay for 15 minutes while the collector is supposed to be running.
- `ClusterMapTrackedTuplesHigh` — the collector holds more than 2 million connections; lower the retention or switch to `OnDemand`.
## Limitations
- One replica: traffic history lives in the process. A second replica would keep its own history and double the load on hubble-relay.
- Access is all-or-nothing, as described in [Security](#security). Showing each user only what their RBAC allows is planned.
- Traffic is L3/L4. HTTP-level details (paths, status codes) need Cilium L7 visibility and are not shown yet.
+66
View File
@@ -0,0 +1,66 @@
---
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 и пока не показываются.