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>
title, description, webIfaces
| title | description | webIfaces | |||
|---|---|---|---|---|---|
| The cluster-map module | Interactive topology map of the cluster with live traffic from Cilium Hubble. |
|
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-ciliumandcilium-hubblemodules. Withoutcilium-hubblethe module works and shows configuration links only. - For access control: the
user-authnmodule, 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 toOnDemand.
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. 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.