Kubernetes

The Oriel Helm chart is published from Arbor. It can run bundled PostgreSQL, ClickHouse, and Valkey for a cluster test, or point Oriel at external datastores for production.

Before you install

• Kubernetes cluster with a default StorageClass when bundled databases are used
• Helm 3 or newer
• Network access to the Arbor Helm repository
• Oriel image available at arbor.klado.dev/oriel/oriel

The chart default image repository is arbor.klado.dev/oriel/oriel. When image.tag is empty, the chart uses its appVersion; set image.tag only when you need to override the image tag separately from the chart version.

Install with bundled datastores

Add the Helm repository:

helm repo add oriel https://arbor.klado.dev/api/packages/oriel/helm
helm repo update

Install Oriel with bundled PostgreSQL, ClickHouse, and Valkey:

helm install oriel oriel/oriel --namespace oriel --create-namespace

Pin a production install to a chart version:

helm install oriel oriel/oriel \
  --namespace oriel \
  --create-namespace \
  --version 0.2.0

The default install creates a Secret named oriel-db-auth for database passwords, Oriel DSNs, and ORIEL_AUTH_COOKIE_SECRET. Generated values are preserved on upgrade while the Secret remains in the cluster.

Use external databases

Create a Secret with the Oriel application DSNs:

kubectl create secret generic oriel-external \
  --namespace oriel \
  --from-literal=ORIEL_METADATA_DSN='postgres://oriel:...@postgres.example.com:5432/oriel' \
  --from-literal=ORIEL_CLICKHOUSE_DSN='clickhouse://oriel:...@clickhouse.example.com:9000/oriel' \
  --from-literal=ORIEL_VALKEY_DSN='valkey://:...@valkey.example.com:6379/0' \
  --from-literal=ORIEL_AUTH_COOKIE_SECRET='replace-with-a-stable-random-secret'

Install with bundled databases disabled:

helm install oriel oriel/oriel \
  --namespace oriel \
  --create-namespace \
  --set postgresql.enabled=false \
  --set clickhouse.enabled=false \
  --set valkey.enabled=false \
  --set oriel.secrets.existingAppSecret=oriel-external

To have the chart create the Oriel Secret while using external stores, leave oriel.secrets.existingAppSecret empty and set:

postgresql:
  enabled: false
clickhouse:
  enabled: false
valkey:
  enabled: false
oriel:
  secrets:
    externalMetadataDsn: postgres://oriel:...@postgres.example.com:5432/oriel
    externalClickhouseDsn: clickhouse://oriel:...@clickhouse.example.com:9000/oriel
    externalValkeyDsn: valkey://:...@valkey.example.com:6379/0
    cookieSecret: replace-with-a-stable-random-secret

Networking

The chart creates separate Services for API/UI, OTLP gRPC, and OTLP HTTP:

Service	Default port
API/UI	6743
OTLP gRPC	4317
OTLP HTTP	4318

Services default to ClusterIP. Set service.*.type to NodePort or LoadBalancer when the cluster exposes traffic directly. Use ingress.api, ingress.otlpHttp, and ingress.otlpGrpc for controller-managed ingress.

Set oriel.config.server.publicUrl to the externally visible HTTPS URL when the UI/API is behind ingress or a proxy.

Runtime roles

Default mode runs one Deployment:

oriel:
  roleMode: all

Split mode runs query, ingest, and worker Deployments:

oriel:
  roleMode: split
  replicas:
    query: 2
    ingest: 2
    worker: 1

In split mode, the API Service targets query pods and OTLP Services target ingest pods.

Production overlay

The checked-in values-production.yaml is a production baseline for split-role deployments. With the hosted chart, copy it into your release configuration and upgrade from the Arbor repo:

helm upgrade --install oriel oriel/oriel \
  --namespace oriel \
  --create-namespace \
  -f values-production.yaml \
  --version 0.2.0

The overlay runs split deployments, disables plaintext non-loopback binds, turns on NetworkPolicy rendering, enables a PodDisruptionBudget, sets per-role resources and per-role config, spreads pods across zones, and autoscales query and ingest.

Develop from checkout

Use the local chart path when you are changing chart templates or testing this repository checkout:

helm dependency build deploy/k8s
helm install oriel deploy/k8s --namespace oriel --create-namespace

Render and lint the checked-in chart before submitting chart changes:

helm lint deploy/k8s
helm template oriel deploy/k8s
helm template oriel deploy/k8s -f deploy/k8s/values-production.yaml

Verify the release

Run the Helm test:

helm test oriel -n oriel

Bootstrap the first admin:

kubectl exec -n oriel deploy/oriel -- \
  env ORIEL_BOOTSTRAP_PASSWORD='change-me' \
  oriel admin bootstrap --email you@example.com

Create a workspace:

kubectl exec -n oriel deploy/oriel -- oriel admin create-workspace --slug demo

These examples use the default all-in-one deployment. In split mode, run the commands against deploy/oriel-query.

Recover a failed release

Check pods and migration state:

kubectl get pods -n oriel
kubectl exec -n oriel deploy/oriel -- oriel migrate status

If readiness returns ORL-5002, run migrations with the same environment as the pods:

kubectl exec -n oriel deploy/oriel -- oriel migrate up

If login or OIDC callbacks fail, confirm oriel.config.server.publicUrl matches the external HTTPS URL.