Skip to content

Kmesh Plugin for Headlamp 0.1.0-alpha

Choose a tag to compare

View all tags
@illume illume released this 25 Aug 09:19
· 58 commits to main since this release
kmesh-0.1.0-alpha
e400ec8

First public release. This release introduces native Kmesh eBPF service mesh visibility directly inside Headlamp. Feedback and bug reports are welcome.

Demo

Watch the complete visual walkthrough of the Headlamp Kmesh plugin in action:

Screencast.from.2026-08-02.09-40-08.mp4

About

Kmesh is a high-performance, sidecarless Layer-4 and Layer-7 service mesh data plane built on eBPF and the Linux programmable kernel. It intercepts and routes traffic at the kernel socket layer via sockops and tc BPF hooks — with no sidecar containers required.

Headlamp is an open-source, extensible Kubernetes web UI. Its plugin system lets Kubernetes projects add sidebar navigation, routes, resource models, list views, detail views, and actions that feel native to the rest of the interface.

Without this plugin, an operator working with Kmesh must jump between kubectl exec sessions, raw BPF map dumps, and manual curl requests against daemon diagnostic ports to understand the mesh state, traffic routing decisions, and security policy enforcement.

The Kmesh plugin brings that kernel-native context into Headlamp. It provides Waypoint Gateway management, daemon health monitoring, live xDS configuration inspection, eBPF kernel telemetry, zero-trust authorization policy viewing, live BPF map inspection, per-node IPsec security state visualization, and visual enrollment indicators for namespaces and waypoints — all without requiring terminal access.

What This Plugin Does

The Kmesh plugin for Headlamp adds native views for Kmesh resources and daemon state inside the Headlamp dashboard.

You can browse Gateway API Waypoints, monitor daemon pod health across nodes, inspect live kernel-native xDS configurations, view eBPF telemetry metrics, audit zero-trust authorization policies, explore live BPF kernel maps, inspect per-node IPsec security (KmeshNodeInfo), and see at-a-glance enrollment indicators on namespaces and waypoints — all from within Headlamp.

Highlights

  • Waypoint (Gateway API) list and detail views with status condition badges inside Headlamp.
  • Daemon Health Dashboard showing total vs. ready kmesh-daemon pods per node.
  • xDS Config Dump Viewer that proxies directly into running daemon pods, rendering Clusters, Listeners, and Routes in searchable tabs.
  • eBPF Telemetry & Observability Panel surfacing BPF map metrics, TCP latency, and packet counters.
  • Authorization Policies Viewer listing active zero-trust L4 eBPF-enforced security rules.
  • eBPF Map Viewer exposing live kernel BPF maps (backends, frontends, services, endpoints, workload policies) in the dual-engine daemon.
  • KmeshNodeInfo IPsec Visualization providing per-node IPsec security state and daemon sync status.
  • Visual enrollment indicators on namespaces and waypoints to show Kmesh mesh membership at a glance.
  • Kmesh CRD and DaemonSet detection so the sidebar stays clean on clusters where Kmesh is not installed.
  • All daemon API communication is securely proxied through the Headlamp backend — no direct browser-to-pod access.

Why This Plugin Matters

Kmesh engineers and cluster operators need to understand both the kernel-native mesh configuration and the live Kubernetes resources managed by it.

Without this plugin, that information is split across raw kubectl exec curl commands, BPF map inspection tools, and the Kubernetes API. The plugin brings those views together in Headlamp while keeping the workflow Kubernetes-native.

This helps operators:

  • See which Gateway resources are acting as L7 Waypoint proxies and their live health.
  • Monitor whether kmesh-daemon pods are ready and healthy across all nodes.
  • Inspect live kernel-native xDS routing decisions without executing diagnostic curl commands.
  • Observe real-time BPF telemetry metrics during canary deployments and load tests.
  • Audit active zero-trust authorization rules without reconstructing them from raw eBPF maps.
  • Explore the full state of kernel BPF maps in dual-engine mode.
  • Verify per-node IPsec tunneling state via KmeshNodeInfo resources.
  • Quickly identify which namespaces and waypoints are enrolled in the mesh.

Contributors

This plugin was created as part of the Linux Foundation Mentorship (LFX) program and developed with review and guidance from the Headlamp community.

Contributor Role
@itvi-1234 Plugin design, implementation, UI/UX decisions, documentation, testing, and demo preparation
@illume Maintainer review, technical guidance

Thank you to the Headlamp maintainers and reviewers for helping shape the plugin through implementation feedback and review.

Installation

Build the plugin from source:

git clone https://github.com/headlamp-k8s/plugins
cd plugins/kmesh
npm install
npm run build

Or install directly via the Headlamp Plugin Catalog (Desktop):

  1. Open Headlamp desktop and navigate to Plugin Catalog.
  2. Search for Kmesh and click Install.
  3. Click Reload UI to activate the KMesh sidebar section.

Requirements

  • Headlamp Desktop or an in-cluster Headlamp installation.
  • Node.js v20.11.1 or later (required to build from source).
  • A Kubernetes cluster reachable from Headlamp.
  • Kmesh installed in the cluster (running in kernel-native or dual-engine mode).
  • Linux kernel 5.10+ with eBPF support enabled.
  • Kubernetes permissions to get, list, and watch Kmesh resources and pods.

Features

Navigation and Sidebar

The plugin adds a KMesh section to the Headlamp sidebar with dedicated pages for Waypoints, xDS Config Dump, Daemon Health, Observability, Authorization Policies, eBPF Maps, and Node Security.

Kmesh DaemonSet detection keeps the sidebar entries relevant — if the kmesh-daemon DaemonSet is not found, operators are informed through appropriate empty states rather than broken views.

Waypoint Management (Gateway API)

Discovers Kubernetes Gateway resources filtered by gatewayClassName: kmesh-waypoint and presents a searchable list view with per-waypoint status badge 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 now highlight which Waypoints are actively enrolled in the mesh at a glance.

Image

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.

Image

xDS Config Dump 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.

Image

eBPF Telemetry & Observability

Surfaces BPF telemetry counters from kernel-instrumented traffic hooks (sockops, tc) in a refreshable panel. Platform teams get 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.

Image

Authorization Policies 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.

Image

Visual 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.

Image

Development

  • Implements plugin using @kinvolk/headlamp-plugin extension APIs (registerRoute, registerSidebarEntry, registerDetailsViewSection).
  • All daemon API communication is proxied securely through the Headlamp backend to avoid direct pod access from the browser. A deduplication layer ensures one HTTP round-trip per pod per request cycle.
  • Uses Vitest for unit testing and Headlamp's standard headlamp-plugin format, tsc, and test scripts for CI quality gates.
  • Plugin is packaged via npm run package and distributed as a tar.gz archive for Artifact Hub.

Changelog

Features Added

  • Added Kmesh plugin scaffold and sidebar navigation under the KMesh section.
  • Added Waypoint (Gateway API) list and detail views with status condition badges and container image display.
  • Added Daemon Health Dashboard to monitor total vs. ready kmesh-daemon pods across nodes.
  • Added xDS Config Dump Viewer to live-inspect kernel-native ADS clusters, listeners, and routing rules.
  • Added Observability Panel to inspect BPF telemetry metrics and traffic stats directly from daemon pods.
  • Added Authorization Policies Viewer to track zero-trust L4 security rules in eBPF.
  • Added eBPF Map Viewer to inspect live kernel BPF maps for dual-engine daemon.
  • Added KmeshNodeInfo IPsec visualization for per-node security state.
  • Added visual enrollment indicators for namespaces and waypoints.

Feedback

This is the first public release of the Kmesh plugin for Headlamp. Feedback, bug reports, and feature ideas are welcome.

Bug reports: Open an issue
Feature requests: Start a discussion
Contributing: Pull requests are welcome. See the repository contribution guidance.

Plugin source: headlamp-k8s/plugins/kmesh
License: Apache 2.0

Contributors

illume and itvi-1234
Assets 3
Loading