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 (a one-line verdict, the object's problems, its facts, CPU and memory against requests and limits, its pods), Links (configuration and traffic, clickable), live YAML, Events, container logs, and the actions the viewer is allowed to run.
- Problems (the button in the top bar). Everything that is wrong right now, most severe first, filterable to applications or system namespaces; a click opens the object.
Cards cannot be dragged until the padlock under the zoom buttons is opened, so a stray click does not rearrange the map. The last button saves the current map as a PNG picture.
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.
Problems and alerts
A card with a problem carries a badge: yellow ! for a warning, red ! for an error. Namespace boxes and cards, node boxes and the tree take the colour of the worst problem inside. Sources:
- Object state: containers in
CrashLoopBackOff,ImagePullBackOffand similar, restarts and OOM kills of the last 30 minutes (of the last 24 hours for a container restarted three times or more), pods pending or unschedulable, workloads with no or not all replicas ready for more than 2 minutes, a stuck rollout, a CronJob whose last run failed, a Service with no ready pod, an Ingress routing to a Service that does not exist, a node that is not ready or is under memory, disk or PID pressure. - Warning events of the last 30 minutes, folded per object and reason. Scheduling, volume and back-off failures badge the card at once; any other reason needs five repeats inside the window and is listed without a badge before that, so a single failed probe during a restart does not colour the map. An event's count is cumulative since its first occurrence, so a long-lived event is scaled to the window: 40 probe failures over two days is one an hour, not a burst.
- Prometheus alerts that Deckhouse mirrors into
ClusterAlertobjects. An alert is attached by its labels (deployment,statefulset,daemonset,pod,service,ingress,node,namespace); one without an object or namespace goes to the cluster list.severity_level1–3 is an error, 4–6 a warning, 7–9 information.
Information-level entries (a cordoned node, a single ordinary warning) are listed and never badge a card. Problems are recomputed on every map request and the open page refreshes them every minute.
Ordinary restart history expires after 30 minutes regardless of lifetime restart count; repeated OOM kills retain the 24-hour window. TopologyAwareHintsDisabled is informational only for a Service with a Ready selected backend: Kubernetes uses cluster-wide routing when hints cannot be allocated. Missing backends still produce warnings. No cluster routing configuration is changed.
Vulnerabilities
With operator-trivy installed, a card whose images have CRITICAL CVEs shows a red shield with their number in the bottom-right corner. The details panel lists every CRITICAL and HIGH CVE of the workload's images: the packages it hits, the installed version and the version that fixes it, with a link to the advisory. A CVE counts once per card, however many packages and containers it is found in. Vulnerabilities are shown apart from problems: nearly every image has some, and a badge on each card would hide what is actually broken.
The data comes from the VulnerabilityReport objects operator-trivy writes, so only namespaces it scans appear (labelled security-scanning.deckhouse.io/enabled), and only the severities its severities setting keeps.
Actions
With actions.enabled (the default), the details panel offers:
| Object | Actions |
|---|---|
| Deployment, StatefulSet | restart (as kubectl rollout restart), scale to 0–100 replicas |
| DaemonSet | restart |
| CronJob | run now (as kubectl create job --from=cronjob/…), suspend, resume |
| Pod (in the Load table) | delete, so its controller starts a new one |
| Node (click the node box) | cordon, uncordon |
Every action asks for confirmation and runs as the viewer: the DexAuthenticator passes the user's own token to the module, the module sends the request to the API server with that token, and the API server checks the user's RBAC. A button is shown only when a SelfSubjectAccessReview says the user may do it. The module's service account never gets write permissions, and the API server's audit log records the user; the module also logs each action with the user's name.
Write requests from another site are refused: the module checks Sec-Fetch-Site, Origin and the JSON content type.
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.
Pod-to-pod traffic between nodes is traced twice, as it leaves the sender's node (to-overlay) and as it reaches the receiving pod (to-endpoint). The first copy is also filtered at the agents when the receiver is a pod; this removes about a fifth of the remaining flows without changing any count.
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.
HTTP details
Where Cilium parses HTTP on a port, the map adds to that link the number of requests, responses by class (2xx, 3xx, 4xx, 5xx), p50 and p95 latency and the ten busiest paths. A link with 5xx responses is drawn in the warning colour. Paths are grouped: the query string is dropped and segments that look like IDs (numbers, UUIDs, long hex strings) become :id, so /api/users/42?x=1 and /api/users/43 are one row /api/users/:id.
Cilium parses HTTP only on ports named in an L7 rule of a CiliumNetworkPolicy; the module does not create such policies. To enable it for one service without restricting its traffic, see the example. Keep in mind:
- the connections to that port go through the Envoy proxy on the node: a fraction of a millisecond per request and CPU of the Cilium agent in proportion to the request rate;
- the port must speak plain HTTP/1.x or HTTP/2 (h2c): Envoy cannot see inside TLS, so put the rule on the backend port behind the Ingress, not on 443. gRPC is parsed, but its status is in the trailers and every call shows as 200; a gRPC stream or a WebSocket is one request, not a series of messages;
- request and response headers reach Hubble, including
Authorizationand cookies. The module asks Hubble for the method, path, status and latency only; the headers are not read, stored or shown. Other Hubble clients (the Hubble UI,hubble observe) do see them.
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, events, deployments, statefulsets, daemonsets, cronjobs, ingresses, Deckhouse clusteralerts and operator-trivy vulnerabilityreports, get and list on metrics.k8s.io pods and nodes, and get on pods/log. It never reads Secrets or ConfigMaps and has no write verbs. Changes go through actions, which use the viewer's own identity.
What a viewer sees follows the viewer's own RBAC (auth.visibility: ViewerRBAC, the default). With every request the DexAuthenticator passes the user's token; the module asks the API server with that token (SelfSubjectAccessReview) and caches the answer for a minute:
list podsin all namespaces — the whole cluster;- otherwise only the namespaces where the user can
list pods; cards, YAML, events, load and vulnerabilities of other namespaces are not returned, and a traffic peer there is shown as a hidden peer, with its connections but without its name; - container logs additionally need
get pods/login that namespace, node cards and the node viewlist nodes; cluster-wide alerts are shown to cluster-wide viewers only.
With auth.visibility: Everything, anyone admitted to the web interface sees every namespace and can read container logs, whatever their own RBAC is. In both modes restrict who is admitted with auth.allowedUserGroups (and optionally auth.allowedUserEmails and auth.whitelistSourceRanges); what a user can change always follows their own RBAC.
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.
- Visibility is by namespace: a user who can list pods in a namespace sees all its cards, including the manifests of its Deployments and Services, even if their role would not let them read those objects one by one.
- Alerts need the
prometheusmodule, which createsClusterAlertobjects. Without it the map shows problems from object state and events only. - HTTP details only where a CiliumNetworkPolicy turns on L7 parsing, see HTTP details. Other protocols are shown at L3/L4.