Architecture — KubeBolt Docs

System Diagram

SOURCE Kubernetes Cluster(s)

API Server

Kubernetes core API

Metrics Server

metrics.k8s.io/v1beta1

ENGINE KubeBolt Backend (Go)

Cluster Manager

multi-cluster lifecycle, async connection

Shared Informers

typed resources via client-go

Dynamic Client

Gateway API CRDs (unstructured)

Permission Probe

22 SSAR calls, semaphore of 10

Metrics Collector

30s poll, in-memory cache

Insights Engine

24-rule evaluation engine

Auth Service

JWT sessions, BoltDB user store

REST API (Chi v5)

lists, details, YAML, logs

WebSocket Hub

real-time broadcasts

Copilot Proxy

LLM tool-calling bridge

SURFACE KubeBolt Frontend (React 18 · TS · Vite 5 · Tailwind)

30+ Resource Views

TanStack Table + Query

Cluster Map

React Flow 11

AI Copilot

multi-provider, 16 tools

Theme System

dark/light via CSS variables

Go Workspace

Monorepo with go.work containing three modules:

apps/api — Main backend server (entry: cmd/server/main.go)
packages/agent — The cluster agent (its own release line, 1.x)
packages/shared — Shared Go utilities

The two halves

Backend (per install): reads the Kubernetes API through shared informers, evaluates insights, serves the REST/WebSocket API, and stores historical metrics in an embedded VictoriaMetrics. Auth and users persist in BoltDB.

Agent (per cluster, optional): connects outbound over gRPC (AgentChannel) and ships metric samples — from its built-in kubelet/node collectors, a bundled vmagent scrape sidecar, or by reading your existing Prometheus (promRead). It also carries Hubble network flows for the Reliability tab and tunnels remote exec / port-forward / file browser sessions. See Connecting Clusters.

Key Backend Packages

Package	Purpose
`cluster/manager.go`	Cluster registry + lifecycle: kubeconfig contexts, agent-proxy and metrics-only clusters, display names, context switching
`cluster/connector.go`	Shared informers + dynamic client, 20s cache sync timeout, 15s rest timeout
`cluster/permissions.go`	RBAC probing via SSAR, cluster-wide then namespace fallback, semaphore of 10
`cluster/nslister.go`	Multi-namespace lister wrappers for namespace-scoped ServiceAccounts
`cluster/graph.go`	In-memory topology graph with debounced rebuild (2s)
`cluster/relationships.go`	Edge detection: ownerRefs, selectors, Gateway parentRefs, volumes
`agent/channel`	gRPC AgentChannel: sample ingest, tunnels for exec/port-forward/files
`metrics/collector.go`	Metrics Server polling, per-namespace fallback, graceful degradation
`insights/engine.go`	24-rule evaluation engine
`copilot/`	Kobi: 26 tools, providers, conversations, memory/compact, usage analytics
`auth/service.go`	User management, JWT issue/verify, role enforcement, BoltDB persistence
`websocket/hub.go`	Broadcast hub, 4096 buffer, silent drops when no clients
`api/router.go`	Chi router with requireConnector middleware

Data Flow

Manager reads kubeconfig contexts + the persistent registry → async connection (HTTP server binds immediately, returns 503 until connected)
Permission probe: SSAR calls, cluster-wide then namespace fallback, ~2-5s
Informers start only for permitted resources; namespace-scoped SAs get per-namespace informer factories with multi-lister aggregation
Dynamic client discovers Gateway API CRDs (5s timeout, gracefully skipped)
Metrics Server polls every 30s → in-memory cache; agent samples land in the embedded VictoriaMetrics and serve query/query_range (PromQL)
REST API serves enriched resources with metrics injection, paginated (50/page); WebSocket broadcasts changes with debounced topology rebuilds

Deployment topology

The web UI can be served from a different origin than the API (split UI/API), and the chart supports fronting the API with either a classic Ingress or Gateway API (gatewayAPI.enabled) — with separate listeners for the HTTP/WebSocket API and the agent’s gRPC channel.