Security Architecture

Berserk has one public edge, the gateway, and one intake for telemetry, ingest. Every other service checks a credential on every request instead of trusting the network it sits on.

What it providesCopy Anchor Link

• One place authenticates people and clients. The gateway signs users in — with a password, through your identity provider, or behind a trusted reverse proxy — and accepts CLI and service-account tokens. Every account is one kind: a local account signs in with a password, an SSO account through your identity provider, which never signs in a local account. On every request it passes on, it adds a short-lived token it signs, naming the caller. The UI, the query service and meta take the caller from that token alone, so a request that bypasses the gateway is refused.
• Changing the catalog takes a role. Anyone signed in can read and query databases, tables and views. Changing them, or ingest tokens, takes an admin or a maintainer, a role a service account can hold too.
• Workflows and alerts act for their owner, and say so. A scheduled run gets its own signed token naming the workflow and the user it acts for. Logs and query records show both, so a workflow's queries are never recorded as the user acting.
• Services authenticate each other. Every service inside the cluster presents a token derived from the master key on its calls to the others, and meta, the query workers and the query pods' shared cache refuse calls without it. Another workload on the same network or host cannot register itself in the cluster, read its metadata or pose as a worker.
• Ingest is the cluster's intake for telemetry. It is a service inside the cluster like the others, and authenticates each request by the ingest token the sender presents. What it reports to meta about where data goes counts only for the tokens it shows and for its own streams.
• Other clusters query this one only as site principals. An admin creates a site principal for each cluster allowed to query this one, with the databases it may read. Its token reaches only the site service, which runs a share of the other cluster's query on those databases, and nothing else; this cluster's users and service accounts cannot use the site service. The other cluster states which of its users a query is for, which is logged and never trusted. See Querying other clusters.
• Data without a token is refused by default. Anonymous ingest, into the default table, is for installs that turn it on.
• Network policies add a second layer. The chart's optional network policies limit which pods reach which. Credentials stay the control.

What it requiresCopy Anchor Link

• Expose only the gateway and ingest. Every other service is internal.
• Keep the master key secret. Every service holds it, and whoever has it can act as any service and, through them, as any user. The chart keeps it in the berserk-master-key Secret; rotate it as described there.
• Behind a trusted proxy, make the gateway reachable only through the proxy, which is trusted with the identity headers it sends (Trusted reverse proxy).
• Give each cluster that queries this one its own site principal, with only the databases it needs, and treat its token as a long-lived credential: it does not expire unless you set an expiry. Disabling the site principal stops all its tokens at once.
• Encrypt traffic inside the cluster yourself if you need to. Berserk authenticates the traffic between its services but does not encrypt it; use a service mesh or an encrypted network for that.