Architecture Overview
High-level design
Section titled “High-level design”KubeGlass is a single Go binary that embeds the React frontend at compile time. It reads your kubeconfig, auto-discovers available API groups (including CRDs), and serves everything on one port.
Startup lifecycle
Section titled “Startup lifecycle”The binary boots through 8 sequential phases:
| Phase | Action |
|---|---|
| 1. Banner | ASCII art to stdout |
| 2. Config | Env vars → config file → defaults via Viper |
| 3. Logging | Bootstrap zerolog (JSON in production, human-readable in dev) |
| 4. Signals | Register SIGINT/SIGTERM for graceful shutdown |
| 5. K8s Client | Build KubeManager - in-cluster ServiceAccount → kubeconfig fallback |
| 6. API Discovery | Cache available K8s APIs including CRDs |
| 7. HTTP Server | Start listener on :PORT (default 8090), optional TLS |
| 8. Graceful Shutdown | Drain WebSocket connections, close BoltDB, stop goroutines |
Real-time updates
Section titled “Real-time updates”The WebSocket hub multiplexes multiple logical streams over a single connection per client:
| Stream type | Purpose |
|---|---|
| Watch streams | Real-time K8s resource changes (ADDED/MODIFIED/DELETED) |
| Log streams | Container log tailing |
| Terminal sessions | Interactive exec with 8-hour absolute lifetime |
Messages use a JSON envelope with type, channel, and payload fields.
Subscribe/unsubscribe messages add or remove channels on the fly.
Connection health
Section titled “Connection health”- Ping interval: 30s (server → client)
- Per-connection rate limit: 100 msg/s, burst 200
- Max message size: 1 MB
Circuit breaker
Section titled “Circuit breaker”A lightweight circuit breaker protects against thundering-herd retries when the K8s API is unreachable. Two states:
| State | Behavior |
|---|---|
| Closed (healthy) | API calls proceed normally |
| Open (unhealthy) | Callers skip or wait for recovery |
All subsystems (SSE, cross-cluster watches, resource search, log streamer) respect the circuit breaker state before attempting API calls.
Persistence
Section titled “Persistence”BoltDB stores operational state in {DataDir}/kubeglass.db:
- Drift scan results and policies
- Resource inventory snapshots
- Alert history
- Session revocations
- Cloud provider configs
- Container registry configs
- GitHub integration data
- User preferences
Default retention: 30 days. Pruned hourly in batches.
Configuration
Section titled “Configuration”Two layers:
- AppConfig - Immutable after startup. Loaded from env vars / config file via Viper
- AdminSettings - Runtime-mutable from the UI. Persisted to
admin-settings.json
See Configuration Reference for all settings.