From 4152b56d04f079e4d567fb4ccff0e52a077753cc Mon Sep 17 00:00:00 2001 From: itvi-1234 Date: Sun, 30 Aug 2026 21:47:00 +0530 Subject: [PATCH 1/2] docs: add Headlamp Kmesh plugin docs and kmeshctl category Adds overview/installation pages for the Headlamp Kmesh plugin, and a missing _category_.json for kmeshctl so it gets a proper sidebar label and position like every other docs folder. --- docs/headlamp-kmesh-plugin/_category_.json | 7 ++++ docs/headlamp-kmesh-plugin/installation.md | 27 +++++++++++++ docs/headlamp-kmesh-plugin/overview.md | 46 ++++++++++++++++++++++ docs/kmeshctl/_category_.json | 7 ++++ 4 files changed, 87 insertions(+) create mode 100644 docs/headlamp-kmesh-plugin/_category_.json create mode 100644 docs/headlamp-kmesh-plugin/installation.md create mode 100644 docs/headlamp-kmesh-plugin/overview.md create mode 100644 docs/kmeshctl/_category_.json diff --git a/docs/headlamp-kmesh-plugin/_category_.json b/docs/headlamp-kmesh-plugin/_category_.json new file mode 100644 index 000000000..f00b63b32 --- /dev/null +++ b/docs/headlamp-kmesh-plugin/_category_.json @@ -0,0 +1,7 @@ +{ + "label": "Headlamp Kmesh Plugin", + "position": 10, + "link": { + "type": "generated-index" + } +} diff --git a/docs/headlamp-kmesh-plugin/installation.md b/docs/headlamp-kmesh-plugin/installation.md new file mode 100644 index 000000000..624fc1fa2 --- /dev/null +++ b/docs/headlamp-kmesh-plugin/installation.md @@ -0,0 +1,27 @@ +--- +sidebar_position: 2 +title: Installation +--- + +# Installation + +## Via Headlamp Plugin Catalog (Desktop) + +1. Navigate to **Plugin Catalog** in Headlamp Desktop. +2. Search for **Kmesh** and click **Install**. +3. Click **Reload UI** to activate the Kmesh sidebar section. + + + +## From Source + +```bash +git clone https://github.com/headlamp-k8s/plugins +cd plugins/kmesh +npm install +npm run build +``` + +## Contributors + +- **itvi-1234** — Plugin design, implementation, UI/UX, documentation, testing, and demo preparation diff --git a/docs/headlamp-kmesh-plugin/overview.md b/docs/headlamp-kmesh-plugin/overview.md new file mode 100644 index 000000000..d4b884ad8 --- /dev/null +++ b/docs/headlamp-kmesh-plugin/overview.md @@ -0,0 +1,46 @@ +--- +sidebar_position: 1 +title: Overview +--- + +# Headlamp Kmesh Plugin + +The **Kmesh Plugin for Headlamp** brings native Kmesh eBPF service mesh visibility directly into the [Headlamp](https://headlamp.dev/) Kubernetes dashboard. It is the first public release (`kmesh-0.1.0-alpha`) of the plugin, published in the [headlamp-k8s/plugins](https://github.com/headlamp-k8s/plugins/releases/tag/kmesh-0.1.0-alpha) repository. + +Kmesh is a high-performance, sidecar-free Layer-4/Layer-7 service mesh data plane built on eBPF. It intercepts traffic at the kernel socket layer via `sockops` and `tc` BPF hooks, without requiring sidecar containers. Headlamp is an open-source, extensible Kubernetes dashboard with a plugin architecture that lets projects like Kmesh add their own sidebar navigation, routes, resource models, and views. + + + +## Core Capabilities + +- **Waypoint Management** — Discovers and displays Kubernetes Gateway resources filtered by `gatewayClassName: kmesh-waypoint`, presenting searchable lists with status badges and enrollment indicators. +- **Daemon Health Dashboard** — Monitors `kmesh-daemon` pod readiness across all nodes, showing total vs. ready pod counts to help identify scheduling or attachment failures. +- **xDS Configuration Viewer** — Proxies requests into running daemon pods to fetch and render live ADS dumps, displaying Clusters, Listeners, and Routes in searchable tabs. +- **eBPF Telemetry Panel** — Surfaces BPF map metrics, TCP latency measurements, and packet counters without deploying additional exporters. +- **Authorization Policy Viewer** — Renders L4 authorization rules as human-readable tables mapping source workloads, destinations, and port actions. +- **eBPF Map Viewer** — For dual-engine deployments, provides tabbed access to kernel BPF state including Backends, Frontends, Services, Endpoints, and Workload Policies. +- **KmeshNodeInfo IPsec Visualization** — Displays per-node IPsec security state and daemon synchronization status through list and detail views. +- **Enrollment Indicators** — Visual badges on namespaces and waypoints show mesh membership at a glance. + + + +## Requirements + +- Headlamp Desktop or an in-cluster Headlamp installation +- Node.js v20.11.1 or later (for building from source) +- A Kubernetes cluster reachable from Headlamp +- Kmesh installed in kernel-native or dual-engine mode +- Linux kernel 5.10+ with eBPF support +- Kubernetes permissions for `get`, `list`, and `watch` on Kmesh resources + +## Development Details + +The plugin implements extension APIs from `@kinvolk/headlamp-plugin` for route registration, sidebar entries, and detail view sections. All daemon communication is securely proxied through the Headlamp backend, avoiding direct browser-to-pod access. The project uses Vitest for unit testing and follows standard Headlamp packaging conventions. + +## Feedback & Support + +- **Bug Reports** — Open an issue on the [headlamp-k8s/plugins](https://github.com/headlamp-k8s/plugins) repository. +- **Feature Requests** — Start a discussion thread on the repository. +- **Contributions** — Pull requests are welcome; see the repository's contribution guidelines. + +Released under the Apache 2.0 License. diff --git a/docs/kmeshctl/_category_.json b/docs/kmeshctl/_category_.json new file mode 100644 index 000000000..c2ea3266c --- /dev/null +++ b/docs/kmeshctl/_category_.json @@ -0,0 +1,7 @@ +{ + "label": "kmeshctl", + "position": 9, + "link": { + "type": "generated-index" + } +} From 196e4fde1257baa9e5e9a80f95f1bbf7e810b28c Mon Sep 17 00:00:00 2001 From: itvi-1234 Date: Sun, 30 Aug 2026 22:00:26 +0530 Subject: [PATCH 2/2] docs: add demo video and screenshots to Headlamp Kmesh plugin docs --- docs/headlamp-kmesh-plugin/installation.md | 2 +- docs/headlamp-kmesh-plugin/overview.md | 63 ++++++++++++++++++---- 2 files changed, 54 insertions(+), 11 deletions(-) diff --git a/docs/headlamp-kmesh-plugin/installation.md b/docs/headlamp-kmesh-plugin/installation.md index 624fc1fa2..04c21b3db 100644 --- a/docs/headlamp-kmesh-plugin/installation.md +++ b/docs/headlamp-kmesh-plugin/installation.md @@ -11,7 +11,7 @@ title: Installation 2. Search for **Kmesh** and click **Install**. 3. Click **Reload UI** to activate the Kmesh sidebar section. - +![Kmesh plugin in the Headlamp Plugin Catalog](https://github.com/user-attachments/assets/c230ec3b-f065-464f-91fc-99e8bfbd61e3) ## From Source diff --git a/docs/headlamp-kmesh-plugin/overview.md b/docs/headlamp-kmesh-plugin/overview.md index d4b884ad8..1d02c67ae 100644 --- a/docs/headlamp-kmesh-plugin/overview.md +++ b/docs/headlamp-kmesh-plugin/overview.md @@ -9,20 +9,63 @@ The **Kmesh Plugin for Headlamp** brings native Kmesh eBPF service mesh visibili Kmesh is a high-performance, sidecar-free Layer-4/Layer-7 service mesh data plane built on eBPF. It intercepts traffic at the kernel socket layer via `sockops` and `tc` BPF hooks, without requiring sidecar containers. Headlamp is an open-source, extensible Kubernetes dashboard with a plugin architecture that lets projects like Kmesh add their own sidebar navigation, routes, resource models, and views. - +## Demo + +https://github.com/user-attachments/assets/669a2ec7-d0d7-4bc9-a4e3-598282ffa73c ## Core Capabilities -- **Waypoint Management** — Discovers and displays Kubernetes Gateway resources filtered by `gatewayClassName: kmesh-waypoint`, presenting searchable lists with status badges and enrollment indicators. -- **Daemon Health Dashboard** — Monitors `kmesh-daemon` pod readiness across all nodes, showing total vs. ready pod counts to help identify scheduling or attachment failures. -- **xDS Configuration Viewer** — Proxies requests into running daemon pods to fetch and render live ADS dumps, displaying Clusters, Listeners, and Routes in searchable tabs. -- **eBPF Telemetry Panel** — Surfaces BPF map metrics, TCP latency measurements, and packet counters without deploying additional exporters. -- **Authorization Policy Viewer** — Renders L4 authorization rules as human-readable tables mapping source workloads, destinations, and port actions. -- **eBPF Map Viewer** — For dual-engine deployments, provides tabbed access to kernel BPF state including Backends, Frontends, Services, Endpoints, and Workload Policies. -- **KmeshNodeInfo IPsec Visualization** — Displays per-node IPsec security state and daemon synchronization status through list and detail views. -- **Enrollment Indicators** — Visual badges on namespaces and waypoints show mesh membership at a glance. +### Waypoint Management (Gateway API) + +Discovers Kubernetes `Gateway` resources filtered by `gatewayClassName: kmesh-waypoint` and presents a searchable list view with per-waypoint status badges and container image. Opens a split-right detail drawer showing live Kubernetes status conditions (`Accepted`, `Programmed`, `Ready`), so L7 waypoint proxy health is always visible without terminal access. Visual enrollment indicators highlight which waypoints are actively enrolled in the mesh at a glance. + +![Waypoint list view](https://github.com/user-attachments/assets/759c2cef-df20-4eb2-8011-d7b18dbf4ccd) + +### Daemon Health Dashboard + +Queries `kmesh-daemon` DaemonSet pod readiness across all nodes and displays a compact health summary (total vs. ready count), so operators can immediately identify nodes where BPF program attachment has failed, the daemon has not yet scheduled, or image pull issues are occurring. + +![Daemon health dashboard](https://github.com/user-attachments/assets/3a7acc41-8091-4983-876b-6cbac7972ab8) + +### xDS Configuration Viewer + +Proxies HTTP requests through the Headlamp backend into running Kmesh pods to fetch live ADS (Aggregate Discovery Service) dumps, parsing and rendering Clusters, Listeners, and Routes in separate searchable tabs — replacing the need for manual `kubectl exec curl localhost:15200/debug/config_dump/kernel-native` workflows. + +![xDS config dump viewer](https://github.com/user-attachments/assets/0b1858af-2a98-4ed6-a8ec-401f2c7c89c5) + +### eBPF Telemetry Panel + +Surfaces BPF telemetry counters from kernel-instrumented traffic hooks (`sockops`, `tc`) in a refreshable panel, giving platform teams a real-time window into mesh-managed connection throughput, packet counters, TCP hop latency distribution, and traffic spikes during canary deployments — without deploying additional exporters. + +![eBPF telemetry panel](https://github.com/user-attachments/assets/9e357d28-6a23-4cab-b489-a1e9b86528b8) + +### Authorization Policy Viewer + +Renders active Kmesh L4 authorization rules as a human-readable table mapping source workloads, destination workloads, and port allow/deny actions — translating low-level eBPF match criteria into an auditable policy view for zero-trust security teams. + +### eBPF Map Viewer + +For deployments running in dual-engine (workload) mode, provides a real-time tabbed view into the kernel's internal BPF state without dropping into shell sessions: + +- **Backends** — pod IPs known to the kernel with their waypoint associations. +- **Frontends** — the kernel's full IP routing table (every VIP or pod IP → upstream ID). +- **Services** — services with LB policy, port mappings, and endpoint counts. +- **Endpoints** — per-priority backend assignment revealing locality-aware LB buckets (Priority 0 = same node/zone, Priority 6 = cross-network). +- **Workload Policies** — active authz policy IDs applied per workload at the kernel level. + +All five tabs share a single HTTP round-trip via the daemon proxy deduplication layer. + +### KmeshNodeInfo IPsec Visualization + +Provides list and detail views for `KmeshNodeInfo` custom resources, exposing per-node IPsec security state and daemon synchronization status. Helps network administrators verify that secure inter-node tunneling is correctly established across all worker nodes participating in the mesh. + +![KmeshNodeInfo IPsec visualization](https://github.com/user-attachments/assets/abee05d9-8cd3-4ea4-8f69-9aa13936eac8) + +### Enrollment Indicators + +Extends the built-in Headlamp Namespace detail page with a **Kmesh Enrollment** section, making it immediately clear whether a namespace and its workloads are enrolled in the mesh — without requiring separate label inspection. Waypoints also display visual status badges directly in the list view, surfacing enrollment and health state at a glance. - +![Enrollment indicators](https://github.com/user-attachments/assets/0052ccaf-726d-4c38-83d2-989601292fdf) ## Requirements