KubeBolt docs
ENES GitHub

Core Concepts

Architecture

Go backend with informer caches, VictoriaMetrics for history (bundled with the Helm chart and Compose), and an outbound-only agent. React frontend with live WebSocket updates.

On this page
  1. System Diagram
  2. Go Workspace
  3. The two halves
  4. Key Backend Packages
  5. Data Flow
  6. Deployment topology

System Diagram

SOURCE Kubernetes Cluster(s)
API Server
Kubernetes core API + CRDs
Metrics Server
metrics.k8s.io/v1beta1, live usage
KubeBolt Agent
optional; dials out over gRPC
Hubble · OpenCost · Prometheus
optional sources the agent reads
ENGINE KubeBolt Backend (Go)
Cluster Manager
multi-cluster lifecycle, async connection
Shared Informers
typed resources via client-go
Dynamic Client
Gateway API + optional CRDs
Permission Probe
31 SSAR checks, semaphore of 10
Metrics Collector
Metrics Server poll every 30s
Agent Channel
gRPC ingest + API, exec, file tunnels
Insights Engine
24 rules, evaluated every 60s
Auth Service
JWT sessions, viewer / editor / admin
REST API (Chi v5)
lists, details, YAML, logs
WebSocket Hub
real-time broadcasts
Kobi (Copilot)
multi-provider LLM, 41 tools
Storage
BoltDB state, VictoriaMetrics history
SURFACE KubeBolt Frontend (React 18 · TS · Vite 5 · Tailwind)
Resource Views
26 list views, TanStack Table + Query
Cluster Map
React Flow 11, Grid · Flow · Traffic
Kobi Panel
chat, tool calls, action proposals
Theme System
dark/light via CSS variables

Go Workspace

Monorepo with go.work containing four modules:

The two halves

Backend (per install): reads the Kubernetes API through shared informers, evaluates insights, serves the REST/WebSocket API, and keeps state — users, settings, insight episodes, security findings, the audit trail, Kobi conversations — in an embedded BoltDB. Historical metrics go to VictoriaMetrics: the Helm chart and the Compose stack run a single-node instance next to the API; the single binary and single-container image don’t bundle one, and read any VictoriaMetrics-compatible endpoint you point KUBEBOLT_METRICS_STORAGE_URL at.

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 the Cluster Map’s Traffic layout, OpenCost series for the Cost tab and, in reader or operator mode, proxies Kubernetes API calls for clusters the backend can’t reach directly — including exec, port-forward and file-browser sessions in operator mode. See Connecting clusters.

Key Backend Packages

All under apps/api/internal/.

PackagePurpose
cluster/manager.goCluster registry + lifecycle: kubeconfig contexts, agent-proxy and metrics-only clusters, display names, context switching; runs the insight evaluation loop (every 60s)
cluster/connector.goShared informers + dynamic client; the cache sync fails after 45s without receiving anything (configurable) and carries on while pages arrive, up to 10 minutes; 15s rest timeout, debounced topology rebuild (2s)
cluster/permissions.goRBAC probing via SSAR (31 resource types), cluster-wide then namespace fallback, semaphore of 10
cluster/optional_crds.goRe-checks optional CRDs (cert-manager, Argo CD, VPA, Cilium policies) every 2 minutes
cluster/nslister.goMulti-namespace lister wrappers for namespace-scoped ServiceAccounts
cluster/graph.goIn-memory topology graph
cluster/relationships.goEdge detection: ownerRefs, selectors, Gateway parentRefs, volumes, env references
agent/channelgRPC AgentChannel: sample ingest, tunnels for exec/port-forward/files
metrics/collector.goMetrics Server polling (every 30s), per-namespace fallback, graceful degradation
insights/engine.go24-rule evaluation engine
insights/policy.goRule classes, thresholds and the per-rule policy layer
insights/episodestore_bolt.goEpisode lifecycle on BoltDB: episodes, transitions, mutes, presence
insights/policystore_bolt.goRule policy overrides on BoltDB
helm/Read-only Helm releases decoded from their storage Secrets
findings/Security & Compliance store — Trivy, Kyverno and Falco findings, persisted so they answer without a live connector
copilot/Kobi: 41 tools, providers, conversations, memory/compact, usage analytics
mcp/Read-only MCP server over Streamable HTTP and stdio
auth/store.go, auth/jwt.go, auth/middleware.goUsers and refresh tokens on BoltDB, JWT issue/verify, role enforcement (viewer < editor < admin)
auth/api_tokens_store.goLong-lived REST tokens (kbs_ service, kbk_ key) with path scopes and the public-edge rejection
websocket/hub.goBroadcast hub, 4096 buffer, silent drops when no clients; broadcasts carry a reference (kind, namespace, name), never the object
api/router.goChi router with requireConnector middleware

Data Flow

Deployment topology

The web UI can be served from a different origin than the API (split UI/API, with KUBEBOLT_CORS_ORIGINS listing the UI’s origin), 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.