Виталий ЧефановandClaude Opus 5.5 3cdc2583ee v0.8.0: problem badges, actions as the viewer, load, events, lock
Problems: cards, namespace and node boxes and the tree carry a yellow or
red badge, computed on the server from object state (crash loops, image
pulls, pending and unschedulable pods, readiness older than 2 minutes, a
stuck rollout, a failed CronJob run, Services without endpoints,
Ingresses to missing Services, node conditions), recent Warning events
(notable reasons at once, others after five repeats) and Deckhouse
ClusterAlerts mapped by their labels. A Problems panel lists them all.
Checked against the live cluster: upmeter's synthetic probe pods and
ingress-nginx's fakeservice Ingresses are excluded, they fail on purpose.

Actions: restart, scale, run a CronJob now, suspend/resume, delete a
pod, cordon/uncordon. They run with the viewer's bearer token from the
DexAuthenticator (sendAuthorizationHeader), buttons follow a
SelfSubjectAccessReview, the service account stays read-only. Cross-site
writes are refused by Sec-Fetch-Site/Origin/content type. Scale retries
on conflict: right after a restart a single Get+Update got 409.

Load (metrics.k8s.io against requests/limits/allocatable, per-pod table)
and an Events tab. Cards are locked until the padlock is opened; the map
exports to PNG; the page refreshes badges every minute in place.

Performance, measured on the live cluster:
- layout of big views 3-4x faster: equal-size cards with no edges are
  laid out on the grid ELK would produce (same sizes, checked against
  ELK on a frozen node view), skipping ~8 ms per ELK call;
- hubble-relay gets ~20% fewer flows: the to-overlay copy of pod-to-pod
  traffic is dropped at the agents; 331/331 directions unchanged;
- static files carry ETags, a reload revalidates instead of pulling
  ~2 MB of vendored scripts.

KUBECONFIG is honoured for running the binary on a workstation.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-24 17:25:36 +03:00

cluster-map

A Deckhouse Kubernetes Platform module: an interactive topology map of the cluster with live traffic from Cilium Hubble. User documentation is in docs/README.md (на русском).

The module follows deckhouse/modules-template: werf build, lib-helm templates, module-sdk hooks, and it passes dmt lint with no findings.

Layout

Path What
module.yaml, Chart.yaml, .helmignore, oss.yaml, changelog.yaml module metadata
openapi/ config-values.yaml (ModuleConfig settings), doc-ru-config-values.yaml, values.yaml (internal values)
templates/ Helm templates on lib-helm (charts/deckhouse_lib_helm-*.tgz)
hooks/batch/ Go hooks on module-sdk: hubble CA, external auth, custom certificate
images/cluster-map/ the application image: werf.inc.yaml and the Go source in src/
monitoring/prometheus-rules/ alert rules
docs/ user documentation, English and Russian
.werf/, werf.yaml, werf-giterminism.yaml build, from modules-template
tests/values/ values for make render

The application (images/cluster-map/src)

Package What
cmd/cluster-map wiring, signals, graceful shutdown
internal/config settings from the environment (the Deployment template is the only writer)
internal/kube informer caches, managedFields stripped
internal/topology the graph: workloads, Services, Ingresses, nodes, the pod-owner rules shared with traffic, and the problems attached to cards
internal/traffic Hubble follow stream, per-minute buckets of distinct connections
internal/actions restart, scale, run, suspend, delete pod, cordon — as the viewer
internal/server HTTP API, CSP headers, request metrics
internal/metrics Prometheus metrics
web/ the frontend, embedded into the binary: plain JS, Cytoscape.js, elkjs, English and Russian

API: /api/graph (with problems), /api/flows?namespaces=a,b&window=<seconds>, /api/resource?kind=&namespace=&name=, /api/pods?id=&namespace=, /api/logs?namespace=&pod=&container=, /api/events?id=, /api/usage?id=, /api/me, /api/permissions?kind=&namespace=&name=, POST /api/action, /healthz, /readyz; metrics on :9090/metrics.

/api/me, /api/permissions and /api/action use the viewer's bearer token from the Authorization header (the DexAuthenticator adds it when actions.enabled), never the module's service account.

To run the binary on a workstation, point KUBECONFIG at a kubeconfig; without it the in-cluster service account is used.

Development

make test     # go test -race for the app, hook tests on the module-sdk framework
make lint     # golangci-lint and dmt
make render   # helm template with tests/values/*.yaml

dmt is built from deckhouse/dmt; crane from go-containerregistry.

Build and publish

Base images come from the base_images.yml Deckhouse publishes for its own modules (make base-images; the file is not committed, as in the template).

docker login git.project-chimera.ru
make publish VERSION=v0.8.0              # build, push bundle and release, register, channel alpha
make release VERSION=v0.8.0 CHANNEL=stable

The registry layout matches deckhouse/modules-actions:

<SOURCE>:cluster-map                    module registration (empty image)
<SOURCE>/cluster-map:v0.7.0             bundle
<SOURCE>/cluster-map:<content-tag>      application image
<SOURCE>/cluster-map/release:v0.7.0     release
<SOURCE>/cluster-map/release:<channel>  alpha | beta | early-access | stable | rock-solid

Install

apiVersion: deckhouse.io/v1alpha1
kind: ModuleSource
metadata:
  name: cluster-map
spec:
  registry:
    repo: git.project-chimera.ru/fanchji/cluster-map
    scheme: HTTPS
---
apiVersion: deckhouse.io/v1alpha2
kind: ModuleUpdatePolicy
metadata:
  name: cluster-map
spec:
  releaseChannel: Alpha
  update:
    mode: Auto
---
apiVersion: deckhouse.io/v1alpha1
kind: ModuleConfig
metadata:
  name: cluster-map
spec:
  enabled: true
  version: 1
  updatePolicy: cluster-map
  source: cluster-map
  settings:
    auth:
      allowedUserGroups: [admins]

The module is Experimental: enable allowExperimentalModules in the deckhouse ModuleConfig first.

License

Apache 2.0, see LICENSE. Go files carry an Apache-2.0 header with a neutral copyright line; DMT's license rule expects Copyright <year> Flant JSC, so .dmtlint.yaml excludes the two Go directories from that rule until the headers are changed on transfer.

S
Description
Interactive Deckhouse cluster topology map -- namespace/workload/service graph with click-through config details, live traffic overlay via Cilium Hubble
Readme Apache-2.0
1.2 MiB
Languages
Go 59.2%
JavaScript 29.1%
Go Template 4.7%
CSS 4%
HTML 1.8%
Other 1.2%