Dependencies

Berserk requires PostgreSQL (v17+) for metadata storage and S3-compatible object storage for segment data. The gateway also needs a small set of auth secrets (a cookie signing key plus internal service tokens), which the chart generates automatically by default. Depending on the features you enable you may also need an ingest token, a separate auth database, and an OIDC client secret. (The Git-synced query library's credentials are configured at runtime in the admin UI, not as a chart-managed Secret.)

The table below lists every Kubernetes Secret the chart uses. For each one you choose whether the Helm chart manages it for you (managed: true) or you create it yourself with kubectl (managed: false) — the per-secret sections that follow show both paths. The default differs per secret, as noted in the last column.

PostgreSQL Credentials

The meta service needs a PostgreSQL (v18+) connection string.

global:
  postgresCredentials:
    managed: true

helm install berserk berserk/berserk \
  --namespace bzrk \
  -f values.yaml \
  --set global.postgresCredentials.databaseUrl="postgres://<user>:<password>@host:5432/berserk"

kubectl create namespace bzrk

kubectl create secret generic postgres-credentials \
  --namespace bzrk \
  --from-literal=database_url="postgres://<user>:<password>@host:5432/berserk"

global:
  postgresCredentials:
    managed: false # default
    secretName: "postgres-credentials"

helm install berserk berserk/berserk \
  --namespace bzrk \
  -f values.yaml

S3 Object Store

Query, ingest, janitor, and nursery services all need access to an S3-compatible object store (AWS S3, MinIO, R2, etc.).

All approaches require the storage location in your values file:

global:
  storage:
    endpoint: "https://s3.eu-central-1.amazonaws.com"
    bucket: "your-berserk-bucket"
    region: "eu-central-1"

global:
  s3Credentials:
    managed: true

helm install berserk berserk/berserk \
  --namespace bzrk \
  -f values.yaml \
  --set global.s3Credentials.accessKeyId="AKIA..." \
  --set global.s3Credentials.secretAccessKey="secret..."

kubectl create namespace bzrk

kubectl create secret generic s3-credentials \
  --namespace bzrk \
  --from-literal=AWS_ACCESS_KEY_ID=<key> \
  --from-literal=AWS_SECRET_ACCESS_KEY=<secret>

global:
  s3Credentials:
    managed: false # default
    secretName: "s3-credentials"

helm install berserk berserk/berserk \
  --namespace bzrk \
  -f values.yaml

module "irsa" {
  source  = "terraform-aws-modules/iam/aws//modules/iam-role-for-service-accounts-eks"
  role_name = "berserk-s3-access"

  oidc_providers = {
    main = {
      provider_arn = module.eks.oidc_provider_arn
      namespace_service_accounts = ["bzrk:berserk"]
    }
  }
}

global:
  s3Credentials:
    managed: false
  serviceAccountName: "berserk"

helm install berserk berserk/berserk \
  --namespace bzrk \
  -f values.yaml

Gateway Auth Secrets

The gateway signs session cookies and authenticates its internal calls to the ui, admin-ui, and permissions services. These values live in one Secret (gateway-secrets) with three keys:

• cookie_signing_key — signs session cookies (must be at least 64 bytes)
• service_token — presented on the X-Bzrk-Service-Token header so ui/admin-ui trust the identity the gateway injects
• permissions_service_token — authenticates calls to the permissions service

Unlike the other secrets, this one is Helm-managed by default: the chart generates strong random values on first install and preserves them across upgrades, so most installs need no action here. Create it yourself only when integrating with an external secret manager, or when the values must survive a full uninstall/reinstall.

gateway:
  secrets:
    managed: true # default

kubectl create namespace bzrk

kubectl create secret generic gateway-secrets \
  --namespace bzrk \
  --from-literal=cookie_signing_key="$(openssl rand -hex 64)" \
  --from-literal=service_token="$(openssl rand -hex 32)" \
  --from-literal=permissions_service_token="$(openssl rand -hex 32)"

gateway:
  secrets:
    managed: false
    secretName: "gateway-secrets"

Auth Database (Optional)

The auth stack — gateway, admin-ui, permissions, and the optional source service — stores its tables in PostgreSQL. By default it shares the same database as meta (postgres-credentials) and isolates itself in an auth schema, so no extra secret is required.

To run the auth stack against a physically separate database, point it at its own connection string and opt out of the shared schema by setting global.authDatabaseSchema: "".

global:
  authPostgresCredentials:
    managed: true
    secretName: "auth-postgres-credentials"
  authDatabaseSchema: "" # opt out of the shared `auth` schema

helm install berserk berserk/berserk \
  --namespace bzrk \
  -f values.yaml \
  --set global.authPostgresCredentials.databaseUrl="postgres://<user>:<password>@host:5432/berserk_auth"

kubectl create namespace bzrk

kubectl create secret generic auth-postgres-credentials \
  --namespace bzrk \
  --from-literal=database_url="postgres://<user>:<password>@host:5432/berserk_auth"

global:
  authPostgresCredentials:
    managed: false # default
    secretName: "auth-postgres-credentials"
  authDatabaseSchema: ""

OIDC Client Secret (Optional)

When you enable OIDC single sign-on, the gateway needs the client_secret issued by your identity provider. Because that value comes from the IdP, this secret is always external — the chart never generates it. gateway and admin-ui read the same Secret and key.

kubectl create namespace bzrk

# client_secret must be at least 32 characters
kubectl create secret generic gateway-oidc-secrets \
  --namespace bzrk \
  --from-literal=client_secret="<client-secret-from-your-idp>"

gateway:
  config:
    oidc:
      enabled: true
      issuer: "https://idp.example.com"
      clientId: "berserk"
  secrets:
    oidcClientSecret:
      existingSecret:
        name: "gateway-oidc-secrets"
        key: "client_secret"

admin-ui:
  config:
    oidc:
      enabled: true
  secrets:
    oidcClientSecret:
      existingSecret:
        name: "gateway-oidc-secrets"
        key: "client_secret"

See Admin UI Setup for the full OIDC walkthrough.

Trusted-Proxy Authentication (Optional)

When you front the gateway with a trusted authenticating reverse proxy (PP), it can assert the signed-in user in a request header. Unlike the OIDC client secret, this path needs no secret material — identity is trusted on network grounds alone, so the gateway must be unreachable except through the proxy.

gateway:
  config:
    trustedProxy:
      enabled: true
      # Direct email header, SPIFFE on-behalf-of, or both:
      userHeader: X-PP-USER
      onBehalfOf:
        enabled: true
        header: on-behalf-of
        spiffePrefix: "spiffe://prod.example.net/user/"
        emailDomain: example.com

See Admin UI Setup → Path D for the full walkthrough, including directory mode and the security model.

Default Ingest Token

An ingest token authenticates data sent to the ingest service. By default, all requests into the ingest service are authenticated via the ingest token. If you want to allow unauthenticated requests to the ingest service, then set up a default ingest token as follows.

global:
  ingestToken:
    managed: true

helm install berserk berserk/berserk \
  --namespace bzrk \
  -f values.yaml

kubectl create namespace bzrk

kubectl create secret generic ingest-token \
  --namespace bzrk \
  --from-literal=default_ingest_token="<token>"

global:
  ingestToken:
    managed: false # default
    secretName: "ingest-token"

helm install berserk berserk/berserk \
  --namespace bzrk \
  -f values.yaml

UI Library (Optional)

The Query Library can be mirrored to a Git repo. This is not configured via Helm — a cluster admin sets the HTTPS remote and token at runtime in the admin UI, and it's stored in the database. See Git Sync Configuration for the walkthrough.

Full Install Example

When letting Helm manage all secrets, a single install command covers everything. The gateway's auth secrets (gateway-secrets) are generated automatically, so they need no flags below:

global:
  storage:
    endpoint: "https://s3.eu-central-1.amazonaws.com"
    bucket: "your-berserk-bucket"
    region: "eu-central-1"
  s3Credentials:
    managed: true
  postgresCredentials:
    managed: true
  ingestToken:
    managed: true

helm repo add berserk https://berserkdb.github.io/helm-charts
helm install berserk berserk/berserk \
  --namespace bzrk \
  -f values.yaml \
  --set global.s3Credentials.accessKeyId="AKIA..." \
  --set global.s3Credentials.secretAccessKey="secret..." \
  --set global.postgresCredentials.databaseUrl="postgres://user:password@host:5432/berserk" \

See example values for minimal, Helm-managed, and EKS configurations.