Anatomy of Kubeshark

A distributed packet capture system with a minimal footprint, designed for large-scale production clusters.

Anatomy of Kubeshark

Kubeshark offers two primary deployment methods:

  1. On-demand, lightweight traffic investigation accessible through a CLI for anyone with kubectl access.
  2. Long-term deployment via a helm chart, providing stable and secure access to developers without the need for kubectl access.

Kubeshark does not require any prerequisites such as CNI, service mesh, or coding. It functions without the need for a proxy or sidecar, and does not necessitate any changes to existing architecture.

Cluster Architecture

Full Architecture

Workers are deployed, one per node, at the node level, to sniff traffic and listen to requests on port 30001 on each node.

The Hub is a single container deployed at the Control Plane level. It consolidates information received from all the Workers and listens to requests on port 8898.

The Front is a single container deployed at the Control Plane level. It communicates with the Hub to receive consolidated information and serves the dashboard. It listens to requests on port 8899.

All ports are configurable.

The Dashboard

Kubeshark’s dashboard is a React application packaged as a Kubernetes (K8s) deployment. It operates within the K8s control plane and communicates with the Hub via WebSocket, displaying captured traffic in real-time as a scrolling feed.

Kubeshark UI

Service Name: kubeshark-front

NOTE: For more information, refer to the dashboard documentation.


The Hub is a Kubernetes deployment that acts as a gateway to the Workers. It hosts an HTTP server and performs several key functions:

  • Accepting WebSocket connections along with their respective filters.
  • Establishing WebSocket connections to the Workers.
  • Receiving processed traffic from the Workers.
  • Streaming results back to the requesters.
  • Managing Worker states via HTTP requests.

Service Name: kubeshark-hub


Each Worker pod is deployed into your cluster at the node level as a DaemonSet.

Each Worker pod includes two services:

  1. Sniffer: A network packet sniffer.
  2. Tracer: An optional kernel tracer.

Worker's Architecture


The Sniffer is the main container in the Worker pod responsible for capturing packets by one of the available means:

  2. PF_RING


Kubeshark can sniff encrypted traffic (TLS) in your cluster using eBPF without actually doing decryption. It hooks into entry and exit points in certain functions inside the OpenSSL library and Go’s crypto/tls package.

Kubeshark offers tracing of kernel-space and user-space functions using eBPF (Extended Berkeley Packet Filter). eBPF is an in-kernel virtual machine running programs passed from user space, first introduced into the Linux kernel with version 4.4 and has matured since then.

This functionality is performed by the Tracer container. Tracer deployment is optional and can be enabled and disabled using the tap.tls configuration value. When set to false, Tracer won’t get deployed.

Read more about TLS/eBPF capabilities in the eBPF & Encryption section.


The CLI, a binary distribution of the Kubeshark client, is written in the Go language. It is an optional component that offers a lightweight on-demand option to use Kubeshark that doesn’t leave any permanent footprint.

Once downloaded, you can simply use the tap command to begin monitoring cluster-wide API traffic:

kubeshark tap                                       - tap all pods in all namespaces
kubeshark tap -n sock-shop "(catalo*|front-end*)"   - tap only pods that match the regex in a certain namespace