Getting Started

This quickstart starts with the default kube-insight binary artifact. The default binary has no storage-backend suffix, stays small and pure Go, and uses SQLite for local tests, short demos, and temporary single-file runs. For long-running retained history, use the Helm chart’s default chDB-backed install or an external ClickHouse backend.

A separate chDB-enabled binary artifact is available for local ClickHouse-compatible storage when libchdb.so is installed. Release container images are chDB-capable by default so the Helm chart can use chDB without a special image tag.

Install

Use a version from the release page:

KI_VERSION=0.1.3
KI_OS="$(uname -s | tr '[:upper:]' '[:lower:]')"
KI_ARCH="$(uname -m)"
case "${KI_ARCH}" in
  x86_64) KI_ARCH=amd64 ;;
  aarch64) KI_ARCH=arm64 ;;
esac

curl -L -o kube-insight.tar.gz \
  "https://github.com/nowakeai/kube-insight/releases/download/v${KI_VERSION}/kube-insight_${KI_VERSION}_${KI_OS}_${KI_ARCH}.tar.gz"
tar -xzf kube-insight.tar.gz kube-insight
chmod +x kube-insight

Windows users can download the .zip artifact from the release page.

Local Storage Variants

For performance numbers and backend tradeoffs, see Storage Modes And Performance.

Use the default kube-insight binary for the smallest local test install:

./kube-insight watch --db kubeinsight.db

Use the chDB-enabled variant when you want the embedded local store to share the ClickHouse table/query contract. Local development builds write bin/kube-insight-chdb; release chDB archives are named with _chdb_ and still contain a binary named kube-insight:

# Source checkout local build
./bin/kube-insight-chdb --config config/kube-insight.chdb.example.yaml \
  watch pods services --timeout 30s

# Release chDB archive, after extracting kube-insight and libchdb.so
CHDB_LIB_PATH=./libchdb.so ./kube-insight \
  --config config/kube-insight.chdb.example.yaml \
  watch pods services --timeout 30s

The chDB-enabled binary still supports SQLite and ClickHouse. It additionally requires a compatible libchdb.so discoverable through the system dynamic linker, LD_LIBRARY_PATH, or CHDB_LIB_PATH. The default binary does not link chDB; selecting storage.driver: chdb with it fails with an explicit setup error.

ClickHouse Service Backend

Use ClickHouse when kube-insight should keep continuous central evidence history for a team, API service, or MCP service. Start from the example config and pass the HTTP DSN through the configured environment variable:

export KUBE_INSIGHT_CLICKHOUSE_DSN='http://127.0.0.1:8123/?user=kube_insight&password=...'
./kube-insight --config config/kube-insight.clickhouse.example.yaml serve \
  --watch pods services endpointslices.discovery.k8s.io \
  --api \
  --mcp \
  --metrics

For source checkouts, the local Docker Compose workflow starts ClickHouse and a dev watcher environment:

make dev-compose-up-detached
make dev-compose-ps
make clickhouse-live-profile

Cold object-storage movement is opt-in. The default example config does not move data to S3 or another object store unless a matching ClickHouse storage policy is configured explicitly.

Watch Current Cluster

Watch all list/watch-capable resources in the current kubeconfig context:

./kube-insight watch --db kubeinsight.db

Watch a smaller set while testing:

./kube-insight watch pods services events.events.k8s.io \
  --db kubeinsight.db \
  --timeout 30s

Check collector coverage:

./kube-insight db resources health --db kubeinsight.db --stale-after 10m
./kube-insight db resources health --db kubeinsight.db --errors-only

Query From CLI

Start by inspecting schema:

./kube-insight query schema --db kubeinsight.db

Run read-only SQL:

./kube-insight query sql --db kubeinsight.db --max-rows 20 --sql \
  "select kind, name from object_kinds order by kind limit 20"

Search indexed evidence:

./kube-insight query search webhook --db kubeinsight.db --limit 10

Add full evidence only when needed:

./kube-insight query search webhook --db kubeinsight.db \
  --limit 3 \
  --include-bundles \
  --max-versions-per-object 2

Inspect one object’s retained content versions and observation trail:

./kube-insight query history --db kubeinsight.db \
  --kind ClusterRepo \
  --name rancher-charts \
  --max-versions 5 \
  --max-observations 20

versions are retained content changes. observations are list/watch sightings; unchanged observations keep the time/resourceVersion without duplicating JSON, facts, edges, or changes.

Compact Temporary SQLite Storage

Local watch and serve --watch processes run lightweight SQLite maintenance automatically. The periodic task checkpoints/truncates WAL and runs incremental vacuum when possible, so normal temporary watch operation should not require frequent full compaction. Do not use SQLite as the long-running retained-history backend; use chDB or ClickHouse instead.

After stopping a watcher, compact the local SQLite store:

./kube-insight db compact --db kubeinsight.db

If the database has object_observations backfilled, prune duplicate unchanged content versions while keeping every observation timestamp:

./kube-insight db compact --db kubeinsight.db --prune-unchanged

Local Service Smoke

For a temporary local all-in-one service process, run watcher plus read surfaces together. Release binaries embed the prebuilt React Web UI into the kube-insight binary, so using the UI does not require a separate frontend checkout or Node.js runtime:

./kube-insight serve --watch --app --db kubeinsight.db

Open the Web UI at http://127.0.0.1:8090. --app uses one listener for the local app: Web UI is available at /, API at /api/v1/*, MCP at /mcp, and legacy SSE at /sse.

Smoke test:

curl http://127.0.0.1:8090/healthz
curl http://127.0.0.1:8090/api/v1/schema
curl -X POST http://127.0.0.1:8090/api/v1/sql \
  -H 'content-type: application/json' \
  -d '{"sql":"select name from latest_index limit 5","maxRows":5}'
curl 'http://127.0.0.1:8090/api/v1/health?errorsOnly=true&problemLimit=20'

For built-in browser chat, configure server.chat and follow the Built-in Web UI Agent Tutorial. For an external agent, connect its MCP client to the Streamable HTTP endpoint:

{
  "mcpServers": {
    "kube-insight": {
      "type": "streamable-http",
      "url": "http://127.0.0.1:8090/mcp"
    }
  }
}

The External Agent Skill Tutorial covers MCP tool expectations, stdio fallback, and agent workflow rules.

Validate A Checkout

For source checkouts, run the same quick validation used during development:

make test
make build
git diff --check

make validate runs the generated PoC fixture validation and writes reports under testdata/generated/; use it when changing ingestion, extraction, storage, query, API, or MCP behavior. ClickHouse and chDB validation commands are listed in Development Commands.