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>
111 lines
4.7 KiB
Markdown
111 lines
4.7 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, 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
|
|
|
|
```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.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](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.
|