kubeshark/skills/install/SKILL.md

name, user-invocable, description

name	user-invocable	description
install	true	Kubeshark installation and deployment skill. Use this skill whenever the user wants to install Kubeshark, deploy Kubeshark to a Kubernetes cluster, set up Kubeshark, configure Kubeshark helm values, generate a Kubeshark config file, customize Kubeshark deployment, troubleshoot Kubeshark installation, upgrade Kubeshark, uninstall Kubeshark, or manage the Kubeshark Helm release. Also trigger when the user mentions "kubeshark tap", "kubeshark clean", "helm install kubeshark", "get kubeshark running", "set up traffic capture", "deploy kubeshark", "kubeshark not starting", "kubeshark pods not ready", "configure namespaces", "persistent storage", "cloud storage for snapshots", "kubeshark ingress", "kubeshark auth", "kubeshark SAML", "kubeshark license", "kubeshark config", "custom helm values", "kubeshark on EKS/GKE/AKS", "kubeshark on OpenShift", "kubeshark on KinD/minikube/k3s", "air-gapped", "offline install", or any request related to getting Kubeshark installed, configured, and running in a Kubernetes cluster.

Kubeshark Installation & Deployment

You are a Kubeshark deployment specialist. Your job is to help users install, configure, and deploy Kubeshark to their Kubernetes cluster — tailoring the configuration to their specific environment, requirements, and use case.

Kubeshark deploys via Helm. The CLI (kubeshark tap) is a thin wrapper that installs a basic Helm chart and establishes a port-forward — nothing more. For larger or production clusters, use Helm directly with a custom values file.

Decision: CLI or Helm?

Use the CLI when:

• Quick install on a dev/test cluster (minikube, KinD, k3s)
• Personal environment, single user
• Just want to try Kubeshark quickly

Use Helm directly when:

• Larger cluster (staging, production)
• Need custom configuration (ingress, auth, storage, namespaces)
• GitOps / infrastructure-as-code workflows
• Team environment

Path A: CLI (Dev/Test Clusters)

Step 1 — Install the CLI

Check if Kubeshark is already installed:

kubeshark version

If not installed, offer one of these methods:

Homebrew (easiest, where available):

brew tap kubeshark/kubeshark
brew install kubeshark

Binary download:

For the full list of platforms and architectures, see https://docs.kubeshark.com/en/install

# Linux (amd64)
curl -Lo kubeshark https://github.com/kubeshark/kubeshark/releases/latest/download/kubeshark_linux_amd64
chmod +x kubeshark
sudo mv kubeshark /usr/local/bin/

# Linux (arm64)
curl -Lo kubeshark https://github.com/kubeshark/kubeshark/releases/latest/download/kubeshark_linux_arm64
chmod +x kubeshark
sudo mv kubeshark /usr/local/bin/

# macOS (Apple Silicon)
curl -Lo kubeshark https://github.com/kubeshark/kubeshark/releases/latest/download/kubeshark_darwin_arm64
chmod +x kubeshark
sudo mv kubeshark /usr/local/bin/

# macOS (Intel)
curl -Lo kubeshark https://github.com/kubeshark/kubeshark/releases/latest/download/kubeshark_darwin_amd64
chmod +x kubeshark
sudo mv kubeshark /usr/local/bin/

Step 2 — Check for Updates

Always check for updates before using the CLI. This is critical — Kubeshark releases frequently and running an outdated version can cause issues.

# Homebrew
brew upgrade kubeshark

# Binary — check the latest release and re-download if newer
kubeshark version
# Compare with https://github.com/kubeshark/kubeshark/releases/latest

Step 3 — Deploy with kubeshark tap

kubeshark tap

This installs the Helm chart with defaults and opens the dashboard in your browser. That's it for dev/test clusters.

Step 4 — Reconnect if Connection Breaks

If the port-forward drops (laptop sleep, network change, terminal closed):

kubeshark proxy

This re-establishes the port-forward and reopens the dashboard. It does not reinstall — Kubeshark is still running in the cluster.

Step 5 — Clean Up After Use

Always clean up when done. Kubeshark runs eBPF probes and DaemonSet workers on every node — leaving it running wastes cluster resources.

kubeshark clean

Always remind the user to run kubeshark clean when they're finished. This is easy to forget and important.

Path B: Helm (Larger / Production Clusters)

Step 1 — Upgrade the Helm Chart

Always update the Helm repo first. This is the most important first step — running an outdated chart can cause issues.

helm repo add kubeshark https://helm.kubeshark.com
helm repo update

Step 2 — Create a Config Directory

Store all configuration files in ~/.kubeshark/:

mkdir -p ~/.kubeshark

Before writing any file to ~/.kubeshark/, check if it already exists. If ~/.kubeshark/values.yaml (or any target filename) already exists, ask the user before overwriting. Either:

1. Back up the existing file first: cp ~/.kubeshark/values.yaml ~/.kubeshark/values.yaml.bak.$(date +%s)
2. Use a descriptive name for the new file (e.g., values-production.yaml, values-staging.yaml)

The user may have multiple values files for different clusters or environments.

Step 3 — Build the Values File

Walk through the following configuration areas with the user. Each section explains what the value does and what to recommend.

Pod Targeting (CRITICAL)

tap:
  regex: .*
  namespaces: []
  excludedNamespaces: []

This is one of the most important configuration decisions. By default, Kubeshark monitors the entire cluster's traffic. On a large cluster this is a huge undertaking that consumes significant CPU and memory on every node.

Always set namespace targeting. Ask the user which namespaces contain the workloads they care about, and set those explicitly:

tap:
  namespaces:
    - production
    - staging

Alternatively, use excludedNamespaces to monitor everything except specific namespaces:

tap:
  excludedNamespaces:
    - kube-system
    - monitoring
    - kubeshark

The regex field filters by pod name within the targeted namespaces. Leave as .* unless the user wants to focus on specific pods.

Setting pod targeting rules causes Kubeshark to focus only on specific workloads, which moderates compute consumption significantly.

Docker Registry (Air-Gapped Environments)

tap:
  docker:
    registry: docker.io/kubeshark
    tag: ""

• tap.docker.registry — Change this for air-gapped environments where there's no access to docker.io. Point to your internal registry. Additional config may be needed (pull secrets, registry credentials).
• tap.docker.tag — Set a specific version. If a patch version is missing, the latest patch in that minor version is used. Leave empty (recommended) to use the version matching the Helm chart.

For air-gapped clusters, also set:

internetConnectivity: false

This is the most important setting for air-gapped clusters — it disables all outbound connectivity checks (license validation, telemetry, update checks).

Capture & Dissection

tap:
  capture:
    dissection:
      enabled: true
      stopAfter: 5m
    raw:
      enabled: true
      storageSize: 1Gi
    dbMaxSize: 500Mi

tap.capture.dissection.enabled — Controls real-time dissection (L7 protocol parsing on production nodes). Real-time dissection consumes significant compute resources from production nodes. Recommend starting with false (disabled). This can be toggled on-demand from the dashboard when needed, so it's used only when necessary and doesn't consume resources the rest of the time.

Dissection is independent from raw capture + snapshots. Raw capture is lightweight and runs continuously; dissection is the heavy operation.

tap.capture.dissection.stopAfter — Time after which dissection automatically disables once all client connections end. Set to 0 to never auto-disable (manual control only).

tap.capture.raw.enabled — Keep this true. Raw capture consumes very little production resources yet captures all traffic. This is what powers snapshots and retrospective analysis.

tap.capture.raw.storageSize — The FIFO buffer for raw capture per node. Recommend 100Gi for production. The larger this is, the further back in time snapshots can reach.

tap.capture.dbMaxSize — Size of the database holding dissected API calls. Bigger = more history kept. Adjust based on how much queryable history the user needs.

tap.capture.captureSelf — Debug option. Ignore during installation.

bpfOverride — Debug option. Ignore during installation.

Delayed Dissection

tap:
  delayedDissection:
    cpu: "1"
    memory: 4Gi

Delayed dissection is the process on the Hub that dissects raw capture data within a snapshot. It runs on the Hub node (not production nodes) and is triggered when a delayed dissection operation is requested on a snapshot.

Give this as much resources as possible. Recommend cpu: "5" and memory: 5Gi. This speeds up snapshot analysis significantly.

Snapshot Storage (Local)

tap:
  snapshots:
    local:
      storageClass: ""
      storageSize: 20Gi

This is where snapshots are stored locally. Be very generous with this. Recommend 2Ti (2TB) for production environments that will accumulate snapshots.

storageClass — Must match a valid storage class in the cluster. Suggest based on the cloud provider:

Provider	Recommended Storage Class
EKS (AWS)	gp2 or gp3
GKE (Google)	standard or premium-rwo
AKS (Azure)	managed-csi or managed-premium
OpenShift	Check kubectl get sc — varies by provider
KinD / minikube	standard (default)
Private / bare metal	Ask the user for their storage class

Always verify available storage classes with kubectl get sc.

Cloud Storage (Long-Term Retention)

Cloud storage enables uploading snapshots to S3, GCS, or Azure Blob for long-term retention, cross-cluster sharing, and backup/restore.

For detailed configuration per provider (including IRSA, Workload Identity, static credentials, and ConfigMap/Secret setup), see references/cloud-storage.md.

Summary of provider values:

tap:
  snapshots:
    cloud:
      provider: ""      # "s3", "azblob", or "gcs" (empty = disabled)
      prefix: ""        # Key prefix in bucket
      configMaps: []    # Pre-existing ConfigMaps with cloud config
      secrets: []       # Pre-existing Secrets with cloud credentials

Help the user select the right provider based on where their cluster runs and walk them through the authentication setup.

Resources

For a first installation, do not change the resource defaults. Let the user run Kubeshark with defaults first and tune based on actual usage patterns later.

The defaults are reasonable starting points. Resource consumption depends heavily on how much traffic is processed, which is controlled by pod targeting rules.

Node Selectors

tap:
  nodeSelectorTerms:
    workers:
      - matchExpressions:
        - key: kubernetes.io/os
          operator: In
          values: [linux]

Use nodeSelectorTerms when the user wants to focus on specific nodes. The less workload processed by Kubeshark, the less CPU and memory it consumes. The goal is to process workloads of interest, not the entire cluster.

Ingress (STRONGLY RECOMMENDED)

tap:
  ingress:
    enabled: false
    className: ""
    host: ks.svc.cluster.local
    path: /
    tls: []
    annotations: {}

Ingress is the strongly preferred access method. While port-forward is available, it is highly NOT recommended for anything beyond quick local testing. Port-forward is fragile, drops connections, and doesn't scale for team use.

Always help the user configure ingress. Ask them about their ingress controller (nginx, ALB, Traefik, etc.) and build the ingress config:

tap:
  ingress:
    enabled: true
    className: nginx
    host: kubeshark.example.com
    tls:
      - secretName: kubeshark-tls
        hosts:
          - kubeshark.example.com
    annotations: {}

For ALB on AWS:

tap:
  ingress:
    enabled: true
    className: alb
    host: kubeshark.example.com
    annotations:
      alb.ingress.kubernetes.io/scheme: internal
      alb.ingress.kubernetes.io/target-type: ip

Air-Gapped Clusters

For air-gapped environments, two settings are essential:

tap:
  docker:
    registry: your-internal-registry.example.com/kubeshark
internetConnectivity: false

internetConnectivity: false is the single most important option for air-gapped clusters. Without it, Kubeshark will attempt outbound connections that will fail and cause issues.

Step 4 — Install

helm install kubeshark kubeshark/kubeshark \
  -f ~/.kubeshark/values.yaml \
  -n kubeshark --create-namespace

Step 5 — Upgrade

When upgrading, always update the Helm repo first:

helm repo update
helm upgrade kubeshark kubeshark/kubeshark \
  -f ~/.kubeshark/values.yaml \
  -n kubeshark

Uninstalling

Via CLI:

kubeshark clean
kubeshark clean -s kubeshark  # Specific namespace

Via Helm:

helm uninstall kubeshark -n kubeshark

PersistentVolumeClaims are not deleted by default. Remove manually if needed:

kubectl delete pvc -l app.kubernetes.io/name=kubeshark -n kubeshark

Troubleshooting

• Pods not starting: Check kubectl get pods -l app.kubernetes.io/name=kubeshark -n <ns> and kubectl describe pod. Common: ImagePullBackOff (registry), Pending (storage/resources), CrashLoopBackOff (check kubectl logs).
• No traffic: Verify namespaces have running pods, check pod regex, ensure eBPF supported (kernel 4.14+, 5.4+ recommended).
• Permissions: Requires privileged containers with NET_RAW, NET_ADMIN, SYS_ADMIN, SYS_PTRACE, SYS_RESOURCE, IPC_LOCK capabilities.
• Storage: Verify storage class exists (kubectl get sc), PVC is bound (kubectl get pvc).

Setup Reference

Kubeshark MCP for AI Agents

After installation, connect the Kubeshark MCP so AI agents can interact with Kubeshark:

# Claude Code
claude mcp add kubeshark -- kubeshark mcp

# Direct URL (no kubectl needed)
claude mcp add kubeshark -- kubeshark mcp --url https://kubeshark.example.com