Files
cluster-map/README.md
T
Vitaliy ChefanovandClaude Opus 5.5 4518393ce1 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>
2026-09-23 21:17:52 +03:00

106 lines
4.2 KiB
Markdown

# 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](docs/README.md) ([на русском](docs/README_RU.md)).
The module follows [deckhouse/modules-template](https://github.com/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](https://github.com/deckhouse/lib-helm) (`charts/deckhouse_lib_helm-*.tgz`) |
| `hooks/batch/` | Go hooks on [module-sdk](https://github.com/deckhouse/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, and the pod-owner rules shared with traffic |
| `internal/traffic` | Hubble follow stream, per-minute buckets of distinct connections |
| `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`, `/api/flows?namespaces=a,b&window=<seconds>`, `/api/resource?kind=&namespace=&name=`, `/api/pods?id=&namespace=`, `/api/logs?namespace=&pod=&container=`, `/healthz`, `/readyz`; metrics on `:9090/metrics`.
## Development
```shell
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](https://github.com/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).
```shell
docker login git.project-chimera.ru
make publish VERSION=v0.7.0 # build, push bundle and release, register, channel alpha
make release VERSION=v0.7.0 CHANNEL=stable
```
The registry layout matches [deckhouse/modules-actions](https://github.com/deckhouse/modules-actions):
```text
<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
```yaml
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](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.