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>
67 lines
5.3 KiB
Markdown
67 lines
5.3 KiB
Markdown
---
|
||
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.
|