Kubernetes

Prerequisites

• Kubernetes cluster with a default StorageClass when bundled databases are used
• Helm 3 or newer
• Repository checkout with deploy/k8s
• Oriel image available at arbor.klado.dev/oriel/oriel

The chart default image repository is arbor.klado.dev/oriel/oriel. Set image.tag to the pushed release tag for production installs.

Install

Fetch chart dependencies:

helm dependency build deploy/k8s

Install Oriel with bundled PostgreSQL and ClickHouse:

helm install oriel deploy/k8s --namespace oriel --create-namespace --set image.tag=dev

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.

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 deploy/k8s \
  --namespace oriel \
  --create-namespace \
  --set image.tag=dev \
  --set postgresql.enabled=false \
  --set clickhouse.enabled=false \
  --set valkey.enabled=false \
  --set oriel.secrets.existingAppSecret=oriel-external

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.

Verify

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

Rollback/Recover

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.