KubeShark Tutorial: Complete Step-by-Step Guide to Kubernetes Network Monitoring

What is KubeShark? The Ultimate Kubernetes Network Observability Tool

KubeShark is an open-source network observability platform for Kubernetes that provides real-time, protocol-level visibility into your cluster’s API traffic. Often described as “Wireshark for Kubernetes,” KubeShark captures and monitors all traffic flowing in, out, and across containers, pods, nodes, and clusters without requiring code instrumentation, sidecars, or service mesh installations.

Why KubeShark Matters for DevOps and Security Teams

Real-time visibility: Monitor all API calls and network traffic as they happen
Zero code changes: No instrumentation, CNI modifications, or architectural changes required
TLS decryption: View encrypted traffic without decryption by hooking into runtime libraries
Multi-protocol support: HTTP/1.x, HTTP/2, gRPC, GraphQL, AMQP, Kafka, Redis, and more
Security insights: Detect vulnerabilities, anomalies, and threats in real-time
Performance debugging: Identify bottlenecks and troubleshoot issues quickly

Prerequisites for Installing KubeShark

Before starting this KubeShark tutorial, ensure you have:

A running Kubernetes cluster (Minikube, Kind, EKS, GKE, AKS, or any distribution)
kubectl installed and configured with cluster access
Administrator privileges on your local machine
At least 2GB RAM available for KubeShark components
Port 8899 available (default dashboard port)

Verify Your Kubernetes Cluster

# Check cluster connection
kubectl cluster-info

# Verify nodes are ready
kubectl get nodes

# Check current context
kubectl config current-context

How to Install KubeShark: 3 Methods

Method 1: Quick Install Script (Recommended)

The fastest way to install KubeShark is using the official installation script:

# Download and install KubeShark
sh <(curl -Ls https://kubeshark.co/install)

# Verify installation
kubeshark version

# Optional: Create an alias
echo "alias ks='kubeshark'" >> ~/.bashrc
source ~/.bashrc

What happens during installation:

Downloads the latest KubeShark binary
Installs to /usr/local/bin/kubeshark
Offers to create a ks alias for convenience
Configures proper permissions

Method 2: Homebrew Installation (macOS/Linux)

For Homebrew users:

# Add KubeShark tap
brew install kubeshark/kubeshark/kubeshark

# Verify installation
kubeshark version

Method 3: Manual Binary Download

Download the binary directly from GitHub releases:

# Visit GitHub releases page
# https://github.com/kubeshark/kubeshark/releases

# Download for Linux AMD64
curl -Lo kubeshark https://github.com/kubeshark/kubeshark/releases/latest/download/kubeshark_linux_amd64

# Make executable
chmod +x kubeshark

# Move to PATH
sudo mv kubeshark /usr/local/bin/

Step-by-Step Guide: Running KubeShark for the First Time

Step 1: Start KubeShark Tap Command

The tap command is the primary way to start monitoring your cluster:

# Monitor all namespaces
kubeshark tap

# Monitor specific namespace
kubeshark tap -n production

# Monitor multiple namespaces
kubeshark tap -A

# Monitor specific pods using regex
kubeshark tap "nginx.*"
```

**Expected Output:**
```
INF Hub is available at: http://localhost:8899
INF Press Ctrl+C to stop

Step 2: Access the KubeShark Dashboard

KubeShark automatically opens a web browser to http://localhost:8899. If it doesn’t open automatically:

Open your browser manually
Navigate to http://localhost:8899
You should see the real-time traffic dashboard

Step 3: Understanding the Dashboard Interface

The KubeShark dashboard displays:

Traffic list: Real-time stream of all API calls
Protocol indicators: HTTP, gRPC, Kafka, Redis, etc.
Request/Response details: Full payloads and headers
Timeline view: Visual representation of traffic flow
Service map: Cluster communication topology
Filters: Query language for targeted analysis

KubeShark Filtering: Advanced Traffic Analysis

Basic Filtering Examples

KubeShark uses KFL (Kubeshark Filter Language) for powerful queries:

# Filter HTTP traffic only
http

# Filter by status code
http and response.status == 500

# Filter by HTTP method
http and request.method == "POST"

# Filter by namespace
kubernetes.namespace == "production"

# Filter by pod name
kubernetes.pod.name == "nginx-deployment-*"

# Filter by service
kubernetes.service.name == "backend-service"

# Regex pattern matching
http and response.status == r"5.*"

# Combined filters
http and response.status >= 400 and kubernetes.namespace == "default"

Advanced Filtering Techniques

# Filter DNS queries
dns

# Filter database traffic
redis or mongodb or postgresql

# Filter by request path
http and request.path == "/api/users"

# Filter by response time
http and response.duration > 1000

# Filter TLS traffic
tls

# Filter by source/destination
src.ip == "10.0.0.5" or dst.ip == "10.0.0.10"

Working with Specific Namespaces and Pods

Monitor Specific Namespace

# Monitor single namespace
kubeshark tap -n kube-system

# Monitor multiple namespaces
kubeshark tap -n production,staging,development

Monitor Specific Pods

# Monitor pods matching regex
kubeshark tap "frontend.*"

# Monitor coredns pods
kubeshark tap "coredns.*" -n kube-system

# Dry run to preview matched pods
kubeshark tap "nginx.*" --dry-run

Custom Port Configuration

# Use custom dashboard port
kubeshark tap -p 9090

# Check which port is in use
kubeshark tap --gui-port 8080

Practical Use Cases and Examples

Use Case 1: Debugging 500 Errors

Monitor and capture all 500 errors in real-time:

# Start KubeShark
kubeshark tap -n production

# In dashboard, apply filter:
http and response.status == 500

What you’ll see:

All API calls returning 500 status
Full request/response payloads
Stack traces (if available)
Service dependencies causing errors

Use Case 2: Monitoring Database Queries

Track all database operations:

# Filter for PostgreSQL
postgresql

# Filter for MongoDB
mongodb

# Filter for Redis with slow queries
redis and response.duration > 100

Use Case 3: API Performance Analysis

Identify slow API endpoints:

# Find requests taking longer than 2 seconds
http and response.duration > 2000

# Monitor specific API endpoint
http and request.path == "/api/v1/orders"

# Combine with namespace filter
http and response.duration > 1000 and kubernetes.namespace == "production"

Use Case 4: Security Threat Detection

Monitor suspicious patterns:

# Detect potential SQL injection
http and request.body contains "SELECT * FROM"

# Monitor authentication failures
http and response.status == 401

# Track unusual traffic patterns
http and request.method == "DELETE" and response.status == 200

Exporting and Analyzing Traffic Data

Export PCAP Files

KubeShark can export traffic as PCAP files for offline analysis:

# In the dashboard:
1. Apply your filters
2. Click on "Export PCAP"
3. Choose date range
4. Download file

# Open in Wireshark
wireshark captured-traffic.pcap

Scripting and Automation

Create JavaScript scripts for automated actions:

// Example: Alert on 500 errors
function onItemCaptured(data) {
  if (data.response && data.response.status === 500) {
    console.log("ERROR DETECTED:", data.request.path);
    // Trigger alert, log to external system, etc.
  }
}

Deploying KubeShark for Production Environments

Helm Chart Installation

For persistent deployments, use Helm:

# Add KubeShark Helm repository
helm repo add kubeshark https://helm.kubeshark.co

# Update repositories
helm repo update

# Install KubeShark
helm install kubeshark kubeshark/kubeshark

# Install in specific namespace
helm install kubeshark kubeshark/kubeshark -n monitoring --create-namespace

# Access dashboard
kubectl port-forward -n default service/kubeshark-front 8899:80

Custom Values Configuration

Create a values.yaml file:

# values.yaml
tap:
  namespaces:
    - production
    - staging
  resources:
    requests:
      cpu: 500m
      memory: 512Mi
    limits:
      cpu: 1000m
      memory: 1Gi

ingress:
  enabled: true
  host: kubeshark.example.com
  tls:
    enabled: true

Install with custom values:

helm install kubeshark kubeshark/kubeshark -f values.yaml

KubeShark Architecture and Components

Understanding KubeShark’s architecture helps with troubleshooting:

Core Components

CLI (kubeshark binary):
- Written in Go
- Communicates with Kubernetes API
- Deploys Hub and Worker pods
Hub Pod:
- Central gateway for Workers
- Hosts HTTP server and dashboard
- Aggregates traffic from all Workers
- Handles WebSocket connections
Worker Pods:
- Deployed as DaemonSet (one per node)
- Captures traffic using eBPF and AF_PACKET
- Dissects packets to application layer
- Sends analyzed data to Hub
Dashboard (Web UI):
- Real-time traffic visualization
- Filter and search capabilities
- Request/Response inspection
- Service map generation

References

Official Documentation: https://docs.kubeshark.co
GitHub Repository: https://github.com/kubeshark/kubeshark
Community Slack: Join for support and discussions
YouTube Tutorials: Video guides and demos
Blog Posts: Real-world use cases and tips