/install

name: install
user-invocable: true
description: >
  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: