# Kubeshark Kubeshark Install

> Kubeshark Installation & Deployment

- Skill: `tomevault-io/kubeshark-kubeshark-install` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/kubeshark-kubeshark-install`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/kubeshark-kubeshark-install/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/kubeshark-kubeshark-install

---


# 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:

```bash
kubeshark version
```

If not installed, offer one of these methods:

**Homebrew (easiest, where available):**

```bash
brew tap kubeshark/kubeshark
brew install kubeshark
```

**Binary download:**

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

```bash
# 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.

```bash
# 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`

```bash
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):

```bash
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.

```bash
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.

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

### Step 2 — Create a Config Directory

Store all configuration files in `~/.kubeshark/`:

```bash
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)

```yaml
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:

```yaml
tap:
  namespaces:
    - production
    - staging
```

Alternatively, use `excludedNamespaces` to monitor everything except specific
namespaces:

```yaml
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)

```yaml
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:

```yaml
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

```yaml
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

```yaml
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)

```yaml
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:

```yaml
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

```yaml
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)

```yaml
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:

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

For ALB on AWS:

```yaml
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:

```yaml
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

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

### Step 5 — Upgrade

When upgrading, **always update the Helm repo first**:

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

## Uninstalling

**Via CLI:**

```bash
kubeshark clean
kubeshark clean -s kubeshark  # Specific namespace
```

**Via Helm:**

```bash
helm uninstall kubeshark -n kubeshark
```

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

```bash
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:

```bash
# Claude Code
claude mcp add kubeshark -- kubeshark mcp

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

---
> Source: [kubeshark/kubeshark](https://github.com/kubeshark/kubeshark) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-05-28 -->