# KubeSkoop: an eBPF network diagnosis suite for Kubernetes > KubeSkoop is a network monitoring and diagnosis suite for Kubernetes that builds a traffic graph of the pods in a cluster and watches the kernel's critical path with eBPF, then exports the result to Prometheus, Grafana and Loki. The value is in the diagnosis side, which walks a connectivity problem through socket, bridge, veth, netfilter and sysctls, and the cost is that it needs privileged eBPF, kernel BTF and a bundle of components in the cluster. **alibaba/kubeskoop** — Network monitoring & diagnosis suite for Kubernetes - Repository: https://github.com/alibaba/kubeskoop - Website: https://kubeskoop.io - Stars: 699 · Forks: 92 - Language: Go - License: Apache-2.0 - Published: 2026-10-21 · Updated: 2026-10-21 · Language: en - Canonical page: https://hysenlabs.com/projects/alibaba-kubeskoop ## What the diagnosis is actually for KubeSkoop is described as a kubernetes networking diagnose tool for different CNI plug-ins and IAAS providers, and the sentence that explains its purpose is the one about constructing a traffic graph: it automatically constructs a network traffic graph of pods in the cluster, monitors and analyses the kernel's critical path by eBPF, to resolve most of Kubernetes cluster network problems. The scope of the diagnosis is listed in the key features under one-shot diagnose for network broken. It diagnoses in-cluster traffic between pods, services, nodes and ingress and egress traffic. It covers the whole Linux network stack, with the specific list Socket, Bridge, Veth, Netfilter and sysctls. And it supports IaaS network probe for cloud providers. That enumeration is the design statement. Kubernetes networking problems are rarely in one layer, and the failure mode for a human is that you end up with a packet counter from one tool, a conntrack table from another and a set of sysctl values from a third, and you still have to reason about how the layers connect. KubeSkoop's answer is a single traversal of the stack rather than a set of separate views. The tool is written in Go, the licence is Apache-2.0 for most of the code, and the project is hosted at kubeskoop.io. The last push was on 2026-09-23, and the most recent release listed is v1.0.1 from 2025-05-13. ## The one command install, and the warning attached to it Installation is a single kubectl apply against a bundle manifest that deploys KubeSkoop together with Prometheus, Grafana and Loki: ```bash kubectl apply -f https://raw.githubusercontent.com/alibaba/kubeskoop/main/deploy/skoopbundle.yaml ``` The bundle is called skoopbundle.yaml, and it starts with the minimum number of replicas and default configurations, which the documentation states is not suitable for production environments. That warning is worth taking seriously rather than skipping, because the same document tells you the default console credentials. Once the install finishes you reach the web console through the service named webconsole, and the readme gives the command to find it: ```bash kubectl get svc -n kubeskoop webconsole ``` You may need a Nodeport or a LoadBalancer to reach it from outside the cluster. The default username is admin and the default password is kubeskoop, so the first thing to do after exposing the service is change that password. The choice to ship one bundle rather than separate manifests is a reasonable trade for a diagnostic tool, since the components are useless apart, but it does mean you are installing a Prometheus, a Grafana and a Loki whether or not you already run them, and the readme does not describe how to point KubeSkoop at an existing stack. ## What the web console lets you do The console is described as user-friendly and integrates all the capabilities of KubeSkoop, providing network diagnosis, event monitoring, packet capturing and latency detection. The diagnosis section is the one-shot diagnostic. Under Diagnosis and Connectivity Diagnosis you enter the source address, destination address, port and protocol, click Diagnose to submit, and the result appears in a history list. That is a useful shape for the problem it targets, because the question being answered, can this pod reach that service on that port, is a question with four parameters, and a tool that takes exactly those four parameters saves the operator from assembling them by hand. Packet capturing is under the same section, for a node or a pod in the cluster. Latency Detection detects latencies between multiple nodes and pods, and the screenshot of it is a ping mesh, which is a reasonable hint that the implementation is a mesh of probes rather than a single vantage point. The monitoring side has three views. The Network Performance Dashboard shows the water level of each monitor item corresponding to the time point of the performance problem, which is the phrasing for a set of gauges you can read at the moment something went wrong. Under Monitoring and Event you see anomaly events occurring within the cluster at the current time point, and you can manually select a time range or filter by event type, node, and information such as the namespace and name of the pod where the event occurred, with a Live control in the top right to stream events under the current filters. The Network Graph on the homepage shows the actual network link graph in the cluster, with time and namespaces, and can be switched to a Table view to see each connection. ## eBPF as the measurement instrument, and why BTF matters The kernel monitoring capability is the technical core, and it rests on two things in the feature list: eBPF seamless kernel monitor, and CO-RE scripts on series kernel by BTF. CO-RE means compile once, run everywhere, and the mechanism is BTF, the kernel's own type information. The eBPF programs are compiled against the types the running kernel exposes, so one binary works across kernel versions rather than needing a rebuild per kernel. The dependency list backs this up with github.com/cilium/ebpf at 0.11.0. That is also the operational constraint. A node without BTF, which is common on some managed distributions or older kernels, cannot run these programs, and the failure shows up as a probe that never produces data rather than as a clear error. The rest of the stack is a Kubernetes control plane in Go: the Kubernetes client, cobra and pflag for the command line, gin and gorilla/mux for the HTTP servers, the Prometheus client library for the metrics exporter, ginkgo and gomega with testify for tests, and the usual set of netlink packages for vishvananda, conntrack and netfilter. The build itself is a multi-stage Dockerfile with a BPF build stage that runs make generate-bpf, a cross-compile stage that runs make all, a Node stage that builds the web console with yarn, and an Alpine base image carrying the userland tools the agent needs, iproute2, ipset, iptables, iptables-legacy, ipvsadm, jq, strace and tcpdump. ## Anomaly events, and where they are supposed to land The third key feature is network anomaly event handling, with support for dozens of anomaly scene recognition, exporting the anomaly event to Grafana Loki or a web console. Exporting events to Loki rather than only to the built-in console is the design decision with the most operational weight. An anomaly you can only see in a web console is an anomaly that someone has to be looking at. An anomaly that lands in Loki next to your other cluster logs can be correlated with pod events, controller logs and the metrics you already have, and can drive an alert on a rule you write. The same applies to the metrics side, which exports to the standard Prometheus metric API rather than to a private format. The trade is that you now own two more moving parts, Loki and the rule set. The readme documents the export targets and the filters in the console, but it does not describe the event schema, the list of recognised anomaly scenes, or the fields you would need to write a Loki query, so that part of the setup means reading the source. The web console remains useful for the interactive diagnosis work, where you want a one-shot answer rather than a stream, and it is where the packet capture and latency mesh live. ## The licensing split, and what it means for your build The licence is split in two, and the reason given is a technical one rather than a commercial preference. Most source code in KubeSkoop which runs in userspace is licensed under the Apache License, Version 2.0. The BPF code in the /bpf directory is licensed under GPL v2.0, to be compatible with the Linux kernel helper functions. That makes sense. eBPF programs loaded into the kernel run under the kernel's licensing expectations, so shipping them under a GPL v2.0 is the way to stay compatible with kernel helper functions rather than an attempt to restrict anyone. For a team building a product on top of KubeSkoop, the practical consequence is that the userspace parts carry the permissive licence you would want, while the eBPF part is copyleft. If you are statically linking, or if your distribution model touches the /bpf directory, the obligations differ from the Apache case, and that is a question for whoever owns your compliance rather than something this repository can answer for you. Security issues go to kubernetes-security@service.aliyun.com, and there is a SECURITY.md file in the repository with the details. The contact section lists a DingTalk group with the group ID 26720020148, and the project is also on OpenCollective. ## Where KubeSkoop is the wrong tool The suite is capable, but it is a heavy answer to a problem that some teams do not have. If all you need is per-flow or per-connection visibility, Prometheus with the right exporters and a Grafana dashboard will do that without a privileged eBPF agent, a Loki deployment and a web console. KubeSkoop's value is the traversal across layers, not the collection. The privilege requirement is the other boundary. The eBPF programs need to be loaded into the kernel on every node you want covered, which means the DaemonSet needs permissions and kernel support that many managed Kubernetes environments restrict. The bundled package list also shows what the agent assumes about the host, since it installs iptables-legacy and ipvsadm alongside iptables and iproute2, and it wants tcpdump, strace and jq available. And there is a version gap. The newest release listed is v1.0.1 from 2025-05-13, while the last commit is from 2026-09-23, so the code has moved on since the last tag. Anyone pinning to the release gets older code than the main branch, and the readme does not document a policy for that gap. The sensible adoption is staged. Run it against a staging cluster first, learn what its diagnosis output tells you, and only then decide whether the eBPF footprint in production is worth it. ## Conclusion Adopt KubeSkoop if your team is losing time to Kubernetes network problems and wants a single tool that walks the path from pod to service to node to ingress, because that traversal across the whole Linux network stack is the part no single existing component covers. Do not adopt it if you only need per-flow metrics, since Prometheus and the CNI's own tooling already do that, or if you cannot run privileged eBPF workloads in the cluster. Before you apply the bundle, read the warning about replica counts and default configuration, change the default admin password of the web console, and confirm that your nodes expose BTF, because the CO-RE eBPF programs are compiled against it. ## FAQ ### How do I install KubeSkoop? Apply the bundle manifest with kubectl apply -f https://raw.githubusercontent.com/alibaba/kubeskoop/main/deploy/skoopbundle.yaml, which deploys KubeSkoop together with Prometheus, Grafana and Loki. The readme warns that skoopbundle.yaml starts with the minimum number of replicas and default configurations, which is not suitable for production environments. ### What does the KubeSkoop connectivity diagnosis check? It covers the whole Linux network stack, specifically Socket, Bridge, Veth, Netfilter and sysctls, and diagnoses in-cluster traffic between pods, services and nodes plus ingress and egress traffic. The web console takes a source address, destination address, port and protocol, and the result appears in a history list. ### Does KubeSkoop need BTF to run? The kernel monitoring uses CO-RE scripts on series kernel by BTF, so the eBPF programs are compiled against the kernel's own type information and nodes need to expose BTF for them to load. The eBPF dependency is github.com/cilium/ebpf. ### Where can KubeSkoop send metrics and anomaly events? Metrics are exported to the standard Prometheus metric API, and anomaly events, with support for dozens of anomaly scene recognition, are exported to Grafana Loki or the web console. The network performance dashboard, the event view with time range and node filters, and the network link graph are all part of the console. ### What licence does KubeSkoop use? Most source code, which runs in userspace, is under the Apache License, Version 2.0, while the BPF code in the /bpf directory is under GPL v2.0 for compatibility with Linux kernel helper functions. Vulnerabilities are reported to kubernetes-security@service.aliyun.com and in the SECURITY.md file. ## Sources - [alibaba/kubeskoop on GitHub](https://github.com/alibaba/kubeskoop) - [License: Apache-2.0](https://github.com/alibaba/kubeskoop/blob/main/LICENSE) - [Project website](https://kubeskoop.io) - [README](https://github.com/alibaba/kubeskoop/blob/main/README.md) - [Releases](https://github.com/alibaba/kubeskoop/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/alibaba-kubeskoop