Skip to content
mcgrapengPublic

About

是什么: 轻量 K8s 集群管理界面 | 能干什么: 可视化查看资源拓扑、Pod 日志与 YAML 编辑 | 解决: kubectl 排查要在多终端来回跳 | 何时选: 嫌命令行繁琐又不需要重型平台时

Resources

Stars

1 star

Watchers

0 watching

Forks

Latest commit

 

History

230 Commits

Folders and files

Repository files navigation

Spotlight — A Kubernetes dashboard that thinks with you.

A Kubernetes dashboard that thinks with you.


Quick start  Discussions  Sponsor


English  ·  简体中文


MIT Python Node Kubernetes FastAPI Vue

📸 Screenshot

Spotlight dashboard — cluster health, pod pressure and restart counts on one screen

Every context in your kubeconfig on one screen: health, pressure, and the restart counts that explain your 3 a.m.

🎯 Why

kubectl tells you what is happening. Kubernetes Dashboard tells you where it is. Spotlight tells you why.

We were debugging a production incident at 2 a.m. The pod was crash-looping. kubectl logs showed 21,320 restarts. The Dashboard cheerfully reported the pod as "Running". Neither told us why — the OOMKilled line was buried at position 88 of a 200-line dump. That gap, dashboard without diagnosis, is what Spotlight closes.

No SaaS, no vendor lock. Your cluster, your data, your model.

✨ Features

  • Multi-cluster, one UI — every context in your kubeconfig, switchable live. No restart.
  • Real-time log stream — SSE, multi-pod select, ANSI color preserved, deduplicated, downloadable.
  • AI explainer, any model — OpenAI · Anthropic · Bedrock · Gemini · Ollama · 100+ via LiteLLM.
  • Keyboard-first — ⌘K palette, g d/p/n/e/f/a page jumps. Mouse optional.
  • Readable in the dark — a full dark theme (token-level, not inverted CSS), because 3 a.m. is the hour this thing gets opened.
  • Dense when it needs to be — sortable pod table, three density tiers, a log pane that owns the viewport.
  • Pluggable auth — bearer · session · Teleport tsh · your own plugin, one file.
  • Type-safe end to end — Pydantic v2 → OpenAPI → openapi-typescript. The UI cannot drift from the API.

🚀 Quick start

Two processes: the FastAPI backend and the Vue dev server. Ports are never hardcoded — pick what is free on your machine and tell each side about it.

# 1 · backend — pick any free port
cd backend
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
python -m app.server --reload --port 8002
# 2 · frontend — in a second terminal
cd frontend
pnpm install
pnpm dev

Tell the frontend where the backend is. It proxies /api to VITE_API_PROXY, which defaults to http://127.0.0.1:8000 — so if you started uvicorn on 8002 (or any other port), set it before running pnpm dev, or the frontend will silently proxy to a dead port:

# frontend/.env
VITE_API_PROXY=http://127.0.0.1:8002

Frontend port: leave VITE_PORT unset and Vite picks a free one, walking up if the default is busy. It prints the URL it actually bound — open that, don't assume a fixed port.

On macOS, set no_proxy before you start the backend. The Kubernetes Python SDK seeds its HTTP client from the system proxy settings, so a request to a local cluster at 127.0.0.1 goes through your proxy and comes back as a 500 with an SSL EOF on every call. A local apiserver address is not in the system's exception list (and k3d writes 0.0.0.0 as the server, which is not in it either), so the proxy has to be told to skip it:

# backend
no_proxy=127.0.0.1,localhost,0.0.0.0 python -m app.server --reload --port 8002

The symptom is a 500 on /api/v1/pods while /api/v1/clusters still answers 200 — the cluster list comes from the kubeconfig on disk, and everything else goes over the network.

Auth: Teleport, shared token, or direct kubeconfig

Pick one of three modes. All three are real and supported — Teleport is just the one that needs a bastion.

A · Direct kubeconfig (no bastion). Set nothing. Spotlight reads $KUBECONFIG or ~/.kube/config on the server and talks to the apiserver directly. The API starts open and logs a startup warning. This is the mode for a laptop or a single-team internal tool, where everyone sharing the server's cluster identity is fine.

B · Shared token. Set API_TOKEN (and optionally AUTH_PROVIDER=token). Callers send Authorization: Bearer <token>; there is no login form to fill in. The cluster credential is still the server's kubeconfig, so this changes who may enter, not what they may see.

C · Teleport (real per-user isolation). Set TELEPORT_PROXY, TELEPORT_AUTH and AUTH_PROVIDER=teleport. Each browser session gets its own private tsh login state and its own kubeconfig — users see only what their Teleport role allows. Set TELEPORT_CLUSTER when your proxy hostname is not the cluster name.

Modes A and B share one Kubernetes identity. If you need "each engineer sees only their own RBAC scope", that is mode C, or a new AuthPlugin.

Behind a reverse proxy, set TRUSTED_PROXY_IPS to your LB subnet and start the server with python -m app.server (see Quick start). It is a uvicorn setting, so the bare uvicorn app.main:app form ignores it — and without it the login rate limiter sees only the proxy's IP and throttles every user as one shared bucket.

Writing your own auth plugin? Implement AuthPlugin in backend/app/infrastructure/auth/plugins/, register it in that package's REGISTRY, and set AUTH_PROVIDER=<your-plugin-id>. The login form adapts itself to the plugin's form_fields(). acquire() returns the kubeconfig to write into the session's private directory; per-session isolation, client pooling and cleanup are already handled for you.

⚖️ Compare

kubectl Dashboard Lens Spotlight
Live multi-cluster switch via kubectx manual yes yes
Real-time multi-pod log stream -f yes yes yes, deduplicated
AI log explainer — — — yes, any LLM
Pluggable auth — — partial yes, one file
Type-safe API → UI — — — yes, Pydantic → TS

Spotlight does not replace kubectl. It sits on top of it — and gives you the diagnosis.

🤖 AI in action

Pull up to 200 lines from any pod, click Analyze, pick a model:

▸ AI · claude-3-5-sonnet · 1.42s · tokens 412 in / 286 out

  Root cause
    The pod is being OOMKilled. Container RSS hit the 512 MiB limit at
    17:42:08; the kernel sent SIGKILL (exit 137); Kubernetes restarted
    the container 21,320 times in the last 5 minutes.

  Evidence
    L17  "oom score adj = 950"
    L23  "memory.peak = 512MiB / limit 512MiB"
    L88  "loki-write: signal SIGKILL, exit code 137"

  Suggested fix
    • Raise memory.limit to 768 MiB in the Helm values, or
    • Drop WAL retention from 24h → 6h in the ingester config, or
    • Shard the tenant — split by labels across 3 replicas.

Providers live in SQLite (ai_providers) and are managed entirely from Settings → AI. There is no AI_PROVIDER env var — switching models is a UI action, no restart, no rebuild.

🏗️ Architecture

Hexagonal. The domain and application layers know nothing about Kubernetes, HTTP, or LLMs; the infrastructure adapters do.

flowchart TB
  classDef ui    fill:#1A1A24,stroke:#8EC5FF,stroke-width:1.5px,color:#FAFAFA
  classDef api   fill:#1A1A24,stroke:#EFADF7,stroke-width:1.5px,color:#FAFAFA
  classDef app   fill:#1A1A24,stroke:#FFD69B,stroke-width:1.5px,color:#FAFAFA
  classDef port  fill:#0F0E16,stroke:#EFADF7,stroke-width:1px,color:#FAFAFA
  classDef dom   fill:#0F0E16,stroke:#8EC5FF,stroke-width:1px,color:#FAFAFA
  classDef infra fill:#11111A,stroke:#5A5A75,stroke-width:1px,color:#CFCFD8
  classDef store fill:#0F0E16,stroke:#FFD69B,stroke-width:1px,color:#FFD69B

  subgraph Browser["Browser · Vue 3"]
    UI["shadcn-vue · Pinia · Router · Sonner"]:::ui
  end

  subgraph Edge["Interface · HTTP + SSE"]
    API["FastAPI routers · deps · CORS"]:::api
    SSE["SSE routes · log streaming"]:::api
  end

  subgraph App["Application · use cases"]
    UC["commands · queries · handlers"]:::app
    PK["port: K8s"]:::port
    PL["port: LLM"]:::port
  end

  subgraph Dom["Domain · pure"]
    ENT["entities · value objects · services"]:::dom
  end

  subgraph Infra["Infrastructure · adapters"]
    K8S["multi-context k8s pool"]:::infra
    LLM["LiteLLM — any provider"]:::infra
    DB[("SQLite")]:::store
  end

  UI <-->|"axios + OpenAPI · type-safe"| API
  UI <-->|SSE| SSE
  API --> UC
  SSE --> UC
  UC --> ENT
  UC --> PK & PL
  PK -. implemented by .-> K8S
  PL -. implemented by .-> LLM
  K8S --> DB
  LLM --> DB
Loading

The rule: domain/ and application/ never import kubernetes or litellm. Everything crosses a port declared in application/ports/. To add an auth provider, an LLM, or a log source — implement the matching adapter in infrastructure/ and register it. Nothing else moves.

Stack — backend: FastAPI · Pydantic v2 · kubernetes-python · LiteLLM · SQLAlchemy (async + aiosqlite) · structlog. Frontend: Vue 3 · Vite · Tailwind CSS · shadcn-vue · Pinia · axios. Tests: pytest · Vitest · Playwright · axe-core.

🗺️ Roadmap

  • v2.0 — multi-cluster kubeconfig, SSE log streaming, LiteLLM, UI v6, hexagonal backend
  • v2.1 — Helm chart · single-binary mode · SQLite → Postgres
  • v2.2 — multi-user session isolation (per-user cluster credentials via a new AuthPlugin) · audit log UI
  • v3.0 — plugin SDK · authenticated public read-only share links

Open a Discussion if something matters to you — the roadmap follows what people actually use.

📚 More

Is it production-ready?

Yes for everything except the AI explainer. v2.0 ships with hexagonal architecture, typed API contracts, SSE log streaming, and a test suite over the critical ports. The AI analyzer is the only feature that reaches an external LLM; the rest runs entirely offline.

How is it different from Lens or k9s?

Lens is a full Kubernetes IDE — excellent for exploring resources, no AI log analysis. k9s is a terminal UI — fast and minimal, no web dashboard. Spotlight is the web dashboard with AI diagnosis in the middle. See Compare.

Can I use my own endpoint?

Yes. Settings → AI → Add provider → custom, then paste the base URL of any OpenAI-compatible endpoint (Ollama, vLLM, LM Studio). The model name comes from the same form. Saved to SQLite, used on the next call — no restart.

Does it store my cluster credentials?

No. Spotlight reads your KUBECONFIG at runtime and never persists cluster credentials. API_TOKEN lives in backend/.env (gitignored). Teleport sessions are per-session and expire.

Is there a Docker image?

Not yet — Helm chart and single-binary mode are on the v2.1 roadmap. For now run the two processes directly, see Quick start.

Contributing

Any-size contribution is welcome — bugs, docs, code, provider adapters.

git clone https://github.com/mcgrapeng/Spotlight.git && cd Spotlight

cd backend && python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt && pytest -q

cd ../frontend && pnpm install
pnpm test         # Vitest
pnpm test:e2e     # Playwright

Type checking reads /openapi.json from a running backend:

cd frontend && pnpm types:check

Per-package guides: backend/README.md · frontend/README.md

Project layout
Spotlight/
├── backend/                   FastAPI · hexagonal architecture
│   ├── app/
│   │   ├── application/       use cases + ports
│   │   ├── domain/            entities · value objects · services
│   │   ├── infrastructure/    adapters: ai, auth, cache, config, k8s, logging, persistence
│   │   ├── interface/         api/ (routers · DTOs) + sse/
│   │   └── main.py
│   ├── tests/                 pytest — unit + integration
│   └── requirements.txt
├── frontend/                  Vue 3 + Vite + Tailwind + shadcn-vue
│   ├── src/
│   │   ├── components/        ui/, layout/, common/, pod/, dashboard/, log/, ai/
│   │   ├── views/             9 pages
│   │   ├── stores/            Pinia
│   │   ├── api/               axios + generated OpenAPI types
│   │   └── styles/            design tokens
│   └── package.json
├── assets/                    logo lockup, README screenshots
├── LICENSE                    MIT
└── README.md · README.zh-CN.md

⭐ Star history


MIT © Spotlight contributors


Discussions  ·  Issues  ·  Releases  ·  Sponsor

About

是什么: 轻量 K8s 集群管理界面 | 能干什么: 可视化查看资源拓扑、Pod 日志与 YAML 编辑 | 解决: kubectl 排查要在多终端来回跳 | 何时选: 嫌命令行繁琐又不需要重型平台时

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages