Configuration reference

This page documents the chart values you’re most likely to set. Every value has a sensible default; override with --set key=value or a values file (-f my-values.yaml). Defaults shown are the chart defaults.

Images and registry

The core is offline-first: every image is {registry}/{repository}:{tag}. Point registry at a private mirror and no step reaches the public internet.

Value	Default	Notes
`registry`	`ghcr.io/ultrvlt`	Prefix applied to all first-party images.
`imageTag`	`""`	Global tag override. Empty → the chart’s `appVersion` (the release tag). A component’s own `image.tag` still wins.
`imagePullPolicy`	`IfNotPresent`
`imagePullSecrets`	`[]`	Names of pre-created pull secrets (private mirror).

ClickHouse

Provisioned as a ClickHouseInstallation (CHI) managed by the bundled operator. v1 is single-shard / single-replica.

Value	Default	Notes
`clickhouse.database`	`ultrvlt`
`clickhouse.user`	`ultrvlt`
`clickhouse.password`	`""`	Empty → a random password is generated on first install and kept stable across upgrades.
`clickhouse.persistence.size`	`50Gi`	Size the PVC for your retention.
`clickhouse.persistence.storageClass`	(cluster default)
`clickhouse.resources`	1 CPU / 2Gi req, 4Gi limit
`clickhouse-operator.enabled`	`true`	Set `false` if a cluster-wide ClickHouse operator already exists.

Schema and retention

Value	Default	Notes
`schemaInit.enabled`	`true`	Post-install/upgrade Job that applies the DDL (idempotent).
`schemaInit.auditRetentionDays`	`365`	Retention for the control-plane audit trail; re-tuned on each upgrade.

Authentication

Human authentication for the portal and read API. This gates browser access (distinct from the machine mTLS trust domain used by remote sites).

Value	Default	Notes
`queryApi.auth.mode`	`local`	`none` \| `local` \| `oidc`. `none` ships the API open — not recommended off a trusted network.
`queryApi.auth.sessionTtl`	`12h`
`queryApi.auth.sessionSecret`	`""`	Cookie signing key. Empty → auto-generated and kept stable. Required when `queryApi.replicaCount > 1`.
`queryApi.auth.existingSecret`	`""`	BYO Secret with `session-secret`, `admin-username`, and `admin-password` or `admin-password-hash`.
`queryApi.auth.admin.username`	`admin`
`queryApi.auth.admin.password`	`""`	Plaintext, hashed at boot. Provide this or `passwordHash`.
`queryApi.auth.admin.passwordHash`	`""`	Pre-computed argon2id PHC (preferred — no plaintext at rest). Set `hashed: true` to use it.

In local mode the admin credential is required (fail-closed). In oidc mode it’s optional and stays available as a break-glass login.

OIDC single sign-on (`auth.mode: oidc`)

Authorization Code + PKCE against a discovery-capable IdP; the caller’s groups map to viewer / editor / admin.

Value	Notes
`queryApi.auth.oidc.issuer`	IdP base URL serving `/.well-known/openid-configuration`.
`queryApi.auth.oidc.clientId` / `clientSecret`	Client secret may instead come from `existingSecret` key `oidc-client-secret`.
`queryApi.auth.oidc.redirectUrl`	e.g. `https://ultrvlt.example.com/api/v1/auth/oidc/callback`.
`queryApi.auth.oidc.adminGroups` / `editorGroups` / `viewerGroups`	Group → role mapping.
`queryApi.auth.oidc.defaultRole`	Role for users in no listed group; empty → deny.

Licensing and connected mode

Value	Default	Notes
`queryApi.license.existingSecret`	`""`	Name of a Secret with key `valid.lic`.
`queryApi.license.content`	`""`	Inline `.lic` (chart creates the Secret).
`queryApi.connected.enabled`	`false`	Automatic license renewal (recommended). Enable with a `portalUrl` + `tokenSecret`. Leave off for a fully air-gapped install.
`queryApi.connected.portalUrl`	`""`	The license endpoint you were given.
`queryApi.connected.tokenSecret`	`""`	Secret name with key `token`.
`queryApi.connected.callhomeInterval`	`6h`

Connected mode is the recommended way to run — it keeps your license current for you and sends usage metadata only, never telemetry. Turn it on by setting connected.enabled, portalUrl, and tokenSecret. For offline environments, leave it off and manage the .lic yourself — see Licensing & connected mode.

Leave both license fields empty for an unlicensed boot (core runs UI-locked).

Notification secrets

Alert notification channels store only a secret_key in the database — never a secret value. The core resolves ULTRVLT_NOTIFY_SECRET_<key> from the Secret below. Keys must be valid env-var suffixes ([A-Za-z0-9_]); that same string is what you type into a channel’s secret_key field.

Value	Default	Notes
`queryApi.notify.secrets`	`{}`	Inline map, e.g. `{ slack_hook: "https://hooks.slack.com/..." }` (chart renders a Secret).
`queryApi.notify.existingSecret`	`""`	BYO Secret; its keys become `ULTRVLT_NOTIFY_SECRET_<key>`.

Webhook/email targets that need no secret work without any of this.

Portal ingress

Value	Default	Notes
`portalUi.ingress.enabled`	`false`
`portalUi.ingress.className`	`""`
`portalUi.ingress.host`	`ultrvlt.local`
`portalUi.ingress.annotations`	`{}`	e.g. ALB/ACM annotations.
`portalUi.ingress.tls`	`[]`	e.g. `[{secretName: ultrvlt-tls, hosts: [ultrvlt.example.com]}]`.

Serve the portal over HTTPS — the session cookie is Secure.

Data sources

eBPF sensor

Off by default; only works on BTF-enabled Linux kernels. Validate the node kernel first (see Deploy to EKS).

Value	Default	Notes
`sensor.enabled`	`false`
`sensor.siteId` / `sensor.clusterId`	`default`	Tag captured data.
`sensor.privileged`	`true`	`false` uses the minimal capability set.
`sensor.tolerations`	`[{operator: Exists}]`	Runs on every node, including control-plane.

Cluster-state collector

Value	Default	Notes
`clusterState.enabled`	`false`	Singleton Deployment; reads k8s object state for the Infrastructure pages (no eBPF).

Log collector

Opt-in OpenTelemetry Collector DaemonSet that forwards pod logs as OTLP. Not a first-party image — pinned explicitly.

Value	Default	Notes
`logCollector.enabled`	`false`
`logCollector.image.tag`	`0.111.0`	Pinned to a statically-linked contrib build; re-verify on bumps.
`logCollector.siteId` / `clusterId`	`default`	Keep in sync with the sensor’s.
`logCollector.k8sAttributes`	`true`	Resolve `service.name` from the k8s workload so log `service` matches span `service`.
`logCollector.excludeLogPaths`	`[]`	Extra pod-log globs to drop.

Day-2 operations

Backups

Scheduled and on-demand ClickHouse backups to a dedicated backup disk (the BACKUP statement carries no storage credentials).

Value	Default	Notes
`backup.enabled`	`false`
`backup.schedule`	`0 2 * * *`	Daily at 02:00 UTC.
`backup.destination.type`	`file`	Dedicated PVC. S3/GCS/Azure land later.
`backup.destination.persistence.size`	`50Gi`	Use a different storageClass/AZ than the data volume.
`backup.prune.enabled`	`false`	Sidecar prune; keeps a snapshot if EITHER `keepLast` or `maxAgeDays` still protects it.

Lifecycle manager

Opt-in singleton that tracks a signed release channel and serves upgrade status to the portal’s Updates page.

Value	Default	Notes
`lifecycleManager.enabled`	`false`
`lifecycleManager.channel`	`stable`	`stable` (recommended) or `latest`.
`lifecycleManager.channelsRepo`	`ghcr.io/ultrvlt/charts/ultrvlt-channels`
`lifecycleManager.upgrades.enabled`	`false`	Opt-in actuation — adds a verified “Deploy now” button via a privilege-separated Job.
`lifecycleManager.upgrades.schedule.enabled`	`false`	Opt-in automatic weekly-window upgrades (requires `upgrades.enabled`).