Get started

Architecture overview

The services one Helm release installs, and how a change moves through them.

Everything runs inside your cluster from one Helm release. Five Go and Python services do the work; the dashboard is a static web app in front of them.

Services

ServiceWhat it does
discoveryWatches workloads and groups them into applications, records changes and snapshots, runs rollbacks, and drives the protection plan lifecycle: approvals, Kyverno policies, health checks, admission decisions and reports. Leader-elected.
exporterThe only writer of Telark custom resources. Stores snapshots and plan reports on its two volumes and seeds the built-in roles, categories and the default TelarkConfig. At startup, before it serves, it runs any migration steps and pins the bootstrap account.
authPasskey and Google sign-in, sessions, break-glass approvals, and cleanup when a user, group or role is deleted.
notifierConsumes application change events from NATS and persists them through the exporter. Sends signed webhooks to the endpoints you configure.
analyzerInsights: incident cards and setup recommendations, using read-only cluster access and a local model served by Ollama. Optional.
uiThe dashboard.

By default the chart also installs Kyverno (admission enforcement), Redis (leader locks, queues, caches), NATS JetStream (the event stream), metrics-server and Ollama. The bundled Kyverno can be turned off to use one you already run.

How a change flows

  1. Discover. Discovery sees a workload change, groups it into its application, compares it with the stored state, and classifies it (deployment, scaling, config, incident and so on). It stores the pre-change manifests as a snapshot through the exporter and publishes the change on NATS; the notifier writes the Application resource.
  2. Protect. When a protection plan's window opens, discovery renders its templates into Kyverno NamespacedValidatingPolicy objects labeled telark.io/protection-plan=<plan-id>, in audit or enforce mode.
  3. Verify. On every controller tick (31 seconds by default), discovery reads those policies back from the cluster, marks the plan healthy, drifted or degraded, and redeploys anything that drifted. The plan's admission decisions come from the Kubernetes events Kyverno raises, which discovery copies into a per-plan ledger before they expire.
  4. Explain. An incident or recovery queues an analysis job in Redis. When Insights is on, the analyzer runs its rules, has the local model rewrite the wording, and the dashboard shows the result.

When a plan ends, discovery deletes its policies and stores a final report through the exporter. When a window of a repeating plan ends, discovery removes its policies and stores a window report, and the plan waits, scheduled, for its next window.

Where state lives

StoreHolds
Custom resources (telark.io/v1alpha1, in etcd)Applications, protection plans, settings, users, groups, roles, passkeys, sessions. The system of record.
Snapshot volumePre-change manifests, one file per application, namespace and generation.
Reports volumeProtection plan reports and their decision ledgers, and the reports kept after their plan was deleted.
RedisCoordination, queues, caches, in-app notifications, insights and the webhook deliveries still owed. Treat it as disposable.

Security boundaries

  • Only the exporter writes Telark custom resources; discovery may also patch applications/status for rollbacks. The CRD write guard, on by default, rejects writes from any other identity at admission.
  • Users authenticate with an HttpOnly session cookie (API clients send the token in X-Session-Token); services with a shared service token generated by the chart.
  • Ingress NetworkPolicies, on by default, let only Telark pods of the same release reach the service APIs, and only discovery and the notifier reach NATS.
  • The analyzer's Kubernetes access is read-only. Auth, the notifier and the dashboard have none.

Next