Like Wireshark, but for Kubernetes.

Customer cluster is broken. You can't get access. You can't reproduce it. k8shark fixes that.

Important: k8shark is under active development. Performance and architecture work is landing quickly, and some updates can be backward-incompatible until the API and archive format stabilize.

For production usage, prefer the latest release candidate (v0.2.0-rc.N) so you get compatibility fixes and the current capture/replay behavior.

k8shark captures a Kubernetes cluster's state over time and packages it into a single portable archive. A built-in mock API server lets support engineers replay that archive exactly like a live cluster — no direct connectivity required.

A customer hands over one file. A support engineer queries the environment interactively, without live cluster access or back-and-forth command output.

How it works

flowchart LR
    A[Your Cluster] -->|kshrk capture| B(capture.tar.gz)
    B -->|kshrk open| C[Mock API Server]
    C -->|kubectl| D[Offline Debugging]

Loading

1. Capture — kshrk capture polls the Kubernetes API at configured intervals for a set duration and packages all responses into a .tar.gz file.
2. Open — kshrk open capture.tar.gz extracts the archive, starts a local mock HTTPS API server, and writes a kubeconfig. Set KUBECONFIG and use kubectl normally.

Quick start

# Install
brew install phenixblue/tap/k8shark

# Capture cluster state for 10 minutes
kshrk capture --config k8shark.yaml

# Replay the capture
kshrk open capture.tar.gz
export KUBECONFIG=~/.kube/k8shark-<id>.yaml
kubectl get pods -A

Web UI (Experimental)

kshrk ui capture.khsrk starts a local dashboard for browsing a capture — namespaces, workloads, pods, and every other captured resource — with object YAML/JSON, relationships, a watch-event timeline, and a time-travel scrubber. See docs/web-ui.md for a full tour.

⚠️ Note: The web UI for cluster exploration is experimental. Large cluster captures may consume significant amounts of RAM (1-2+ GB) during replay. For large clusters, consider using an explicit resource list in your config file rather than all: true for auto-discovery to reduce the capture size.

Documentation

Doc	Description
docs/usage.md	Installation, capture and open workflows, all CLI flags, kubectl compatibility
docs/web-ui.md	Web UI tour — dashboard, namespaces/workloads/pods, object views, filtering, timeline, themes
docs/config.md	Config file reference, namespaced vs cluster-scoped resources, example configs
docs/releases.md	How to cut a release, GoReleaser pipeline, signing, Homebrew tap
docs/development.md	Building, testing, linting, KinD dev cluster, E2E tests, package layout
docs/archive-format.md	Internal .tar.gz layout, record and index JSON schemas

License

Apache 2.0