Kubernetes Deployment

A Helm chart is provided in chart/hibou/ for Kubernetes deployments.

Prerequisites

Kubernetes 1.27+
Helm 3.12+
A PostgreSQL 18+ instance (bundled or external)

Quick Start

Create the namespace
Terminal window
```
kubectl create namespace hibou
```
Create the database secret

The database connection string is stored in a Kubernetes Secret — credentials never appear in Helm values.
- Bundled PostgreSQL
- External Database
When using the chart’s built-in PostgreSQL, pass the password at install time:
Terminal window
helm install hibou ./chart/hibou -n hibou \ --set postgresql.auth.password=changeme
The chart generates a Secret with the full connection URL automatically.
Create the secret manually, then reference it:
Terminal window
kubectl create secret generic hibou-db-url -n hibou \ --from-literal=url="postgres://hibou:secret@db.example.com:5432/hibou?sslmode=require"
Terminal window
helm install hibou ./chart/hibou -n hibou \ --set postgresql.enabled=false \ --set postgresql.auth.existingSecret=hibou-db-url

Verify the deployment

kubectl -n hibou rollout status deployment hibou
kubectl -n hibou get pods

Configuration

All Hibou settings are passed via the ConfigMap and Secret. No credentials are stored in values.yaml.

`values.yaml` Reference

hibou:
  image:
    repository: ghcr.io/hibouhq/hibou
    tag: latest
  replicas: 1
  logging:
    level: info       # debug, info, warn, error
    format: json      # console, json
  database:
    url: ""           # Override to skip secret entirely (not recommended)
  trivy:
    url: ""           # Auto-discovered when trivy.enabled=true
  advisory:
    cache:
      ttl: "6h"       # How long advisory query results are cached
    osv:
      url: "https://api.osv.dev"

postgresql:
  enabled: true       # Set false for external database
  auth:
    existingSecret: "" # Name of a Secret with key: url
    username: hibou
    password: ""       # Required via --set when existingSecret is empty
    database: hibou

trivy:
  enabled: true

ingress:
  enabled: false
  hostname: ""         # Required when ingress is enabled
  className: ""
  annotations: {}
  tls:
    enabled: false
    existingSecret: ""

Database Secret

The Secret must contain a single key:

Key	Description
`url`	Full PostgreSQL connection string (`postgres://user:pass@host:5432/db?sslmode=...`)

When using existingSecret, the chart reads the secret name from postgresql.auth.existingSecret and mounts the url key as HIBOU_DATABASE_URL.

Ingress

Enable ingress for external access:

helm install hibou ./chart/hibou -n hibou \
  --set postgresql.auth.password=changeme \
  --set ingress.enabled=true \
  --set ingress.hostname=hibou.example.com \
  --set ingress.className=nginx

For TLS with cert-manager:

helm install hibou ./chart/hibou -n hibou \
  --set postgresql.auth.password=changeme \
  --set ingress.enabled=true \
  --set ingress.hostname=hibou.example.com \
  --set ingress.className=nginx \
  --set ingress.tls.enabled=true \
  --set 'ingress.annotations.cert-manager\.io/cluster-issuer=letsencrypt-prod'

For TLS with an existing secret:

  --set ingress.tls.enabled=true \
  --set ingress.tls.existingSecret=my-tls-secret

Metrics

Hibou serves Prometheus metrics, including storage usage (database, tables, artifacts), on a dedicated port, 9090 by default. The ingress never forwards that port, so /metrics is reachable only inside the cluster. Admins can see the same storage numbers without a metrics stack under Settings → Storage.

hibou:
  metrics:
    # Scrape with the Prometheus Operator (the VictoriaMetrics operator converts it too)
    podMonitor:
      enabled: true
      labels:
        release: kube-prometheus-stack
    # Require a bearer token (Secret key "token"); the PodMonitor sends it
    auth:
      existingSecret: hibou-metrics-token
    # Only the monitoring namespace may reach the metrics port
    networkPolicy:
      enabled: true
      from:
        - namespaceSelector:
            matchLabels:
              kubernetes.io/metadata.name: monitoring

Set hibou.metrics.enabled=false to turn /metrics off entirely.

Upgrading

helm upgrade hibou ./chart/hibou -n hibou \
  --set postgresql.auth.password=changeme

Hibou runs database migrations automatically on startup.

Uninstalling

helm uninstall hibou -n hibou