Skip to main content

Architecture

System Architecture Diagram​

The diagram below illustrates the deployment relationships and communication paths between K8s Sentinel components:

Component Overview​

ComponentTechnologyDescription
FrontendTypeScript + React + Vite + shadcn/uiWeb UI delivered as an SPA, providing TracingPolicy management, event viewing, and cluster monitoring
BackendGo 1.x + HTTP Server (port 8080)RESTful API service with a built-in Kubernetes client, handling cluster communication and user authentication
Cilium TetragoneBPF DaemonSetSecurity observation agent deployed on every Kubernetes node, capturing syscalls and file access at the kernel layer via eBPF; K8s Sentinel collects events per node over gRPC (GetEvents)
Hubble RelayCilium componentAggregates every node's network flows behind one gRPC endpoint; K8s Sentinel reads its GetFlows stream as the data source for Network Topology
Trivy OperatorOptional component (Helm, installed in sentinel-system)Scans the images of running workloads and writes VulnerabilityReport; K8s Sentinel only reads the reports and does not scan workloads itself (v0.60+)
Trivy scan PodsKubernetes Job (sentinel-system)Started by K8s Sentinel for Registry Scanning, one short-lived Pod per image (v0.62+)
TracingPolicyKubernetes CRD (cilium.io/v1alpha1)Custom Resource Definition that defines the kprobe rules and security policies Tetragon should enforce
Persistent Storage/data/sentinel/Local persistence path: user accounts, the JWT signing key, alert and syslog configs, custom templates, event history and the Audit Log, registry settings and scan results

Data Flow​

The sequence diagram below shows the complete flow when a user creates a new TracingPolicy through K8s Sentinel:

Deployment Architecture​

K8s Sentinel uses a single binary deployment model that greatly simplifies the installation process.

The Go backend embeds the frontend React SPA's static files (HTML, JavaScript, CSS) at compile time using embed.go. Deployment requires only copying and running a single executable - no additional web server or static file service needed.

Persistent data is stored at the following paths:

PathPurpose
/data/sentinel/users.jsonUser accounts and password hashes
/data/sentinel/.jwt-secretThe JWT token signing key, auto-generated on first startup; can be overridden by the JWT_SECRET environment variable since v0.53
/data/sentinel/ (rest)Alert / syslog configs, custom policy templates, Security / Admission event history and the Audit Log
/data/sentinel/registries.jsonRegistry settings for registry scanning (including credentials)
/data/sentinel/registry-scans/Registry scan results, one directory per registry