headlamp-kmesh-plugin

A minimal Headlamp plugin that surfaces Kmesh resources as first-class views in the Headlamp UI. Built as the seed for the LFX 2026-T2 mentorship project — Integrating Kmesh into Headlamp UI.

Status

Seed implementation. Two views are wired up; nothing else is. Visual polish, tests, eBPF map view, cluster summary, and per-resource health indicators are deliberately deferred to the mentorship project.

What it registers

View	Path	Backed by	Notes
Kmesh → Node Info	/c/<cluster>/kmesh/nodes	KmeshNodeInfo CR (kmesh.net/v1alpha1, namespaced)	The only CRD Kmesh ships. Detail view is auto-generated by Headlamp's DetailsGrid (pretty-printed YAML, events, metadata).
Kmesh → Waypoints	/c/<cluster>/kmesh/waypoints	gateway.networking.k8s.io/v1.Gateway filtered by spec.gatewayClassName == 'istio-waypoint'	Row clicks link to Headlamp's built-in Gateway detail page.

Design notes

Three findings from reading Kmesh's source informed the resource model:

1. Kmesh ships exactly one CRD of its own. KmeshNodeInfo (kmesh.net/v1alpha1, namespaced) carries IPsec wiring per node (addresses, bootID, podCIDRs, spi). Its status schema is currently empty (type: object with no properties), which limits what the plugin can render for health indicators today — see kmesh#1693 for the proposed status.conditions extension.
2. Waypoints are not a Kmesh CRD. ctl/waypoint/waypoint.go:130 filters Gateway resources by the upstream Istio constant WaypointGatewayClassName ("istio-waypoint"). The plugin reuses Headlamp's existing Gateway resource class rather than declaring a new one.
3. eBPF map state is exposed over HTTP, not as a CRD. The kmesh-daemon pod's status server (pkg/status/status_server.go) serves /debug/config_dump/bpf/{kernel-native,dual-engine} on port 15200. A future iteration of this plugin will proxy those endpoints via Headlamp's ApiProxy. Not implemented in this seed.

Local development

Requires Node ≥ 20.11.1, npm ≥ 10.

npm install
npm run start   # watches src/ and rebuilds into the Headlamp plugin dir

Verify the build pipeline:

npm run tsc
npm run lint
npm run build

To see the plugin loaded, run Headlamp pointing at a cluster that has Kmesh installed (helm install kmesh kmesh-net/kmesh against a kind/minikube cluster — see Kmesh's docs).

Roadmap (mentorship deliverables)

• Per-resource health and readiness indicators for KmeshNodeInfo (gated on the schema extension proposed in kmesh#1693)
• eBPF map view backed by the daemon's /debug/config_dump/bpf/* HTTP endpoints via ApiProxy
• Cluster-level Kmesh component summary (DaemonSet pod health, mode detection, version)
• Related-pod views for waypoints (pods labelled gateway.istio.io/managed)
• Unit/component tests and a kind-based e2e smoke test
• Helm/manifest install docs with screenshots