HAProxy

HAProxy is the recommended TLS terminator and load balancer for obleth. It is included in the Docker Compose stack under the edge compose profile and is referenced in the Helm chart as an optional sidecar/service.

Docker Compose (edge profile)

docker compose -f deploy/docker/docker-compose.yml --profile edge up -d

This starts HAProxy on port 80 (and 443 if certificates are mounted) with the obleth data plane as the backend.

Basic configuration

global
    log stdout format raw local0

defaults
    log     global
    mode    http
    option  httplog
    timeout connect 5s
    timeout client  300s    # must be >= OBLETH_UPSTREAM_TIMEOUT_SECS
    timeout server  300s

frontend obleth_frontend
    bind *:80
    # bind *:443 ssl crt /etc/ssl/certs/obleth.pem  # for TLS
    default_backend obleth_backend

backend obleth_backend
    balance roundrobin
    option  http-server-close
    option  forwardfor
    # Add each obleth pod
    server obleth1 obleth:8080 check
    # server obleth2 obleth2:8080 check
    # server obleth3 obleth3:8080 check

TLS termination

Mount your certificate (PEM format, certificate + private key in a single file) and enable TLS on the frontend:

frontend obleth_frontend
    bind *:443 ssl crt /etc/ssl/certs/obleth.pem
    bind *:80
    redirect scheme https code 301 if !{ ssl_fc }
    default_backend obleth_backend

For Docker Compose, mount the cert:

haproxy:
  volumes:
    - ./certs/obleth.pem:/etc/ssl/certs/obleth.pem:ro

Streaming requirements

obleth uses HTTP/1.1 streaming for text/event-stream (SSE) responses. HAProxy must not buffer streaming responses. Key settings:

• timeout client 300s and timeout server 300s (must be >= OBLETH_UPSTREAM_TIMEOUT_SECS)
• option http-server-close (do not use option http-tunnel)
• Do not enable compression — it buffers the response

Health check

HAProxy can health-check obleth pods using the /health endpoint:

backend obleth_backend
    option httpchk GET /health
    http-check expect string "ok"
    server obleth1 obleth:8080 check inter 5s fall 3 rise 2

Stats page

The Compose edge profile also exposes HAProxy's built-in Prometheus exporter and human stats UI on :8404 (/metrics and /stats). The /stats page is protected with HTTP basic auth so it can't be browsed anonymously if the port is ever published:

frontend stats
    bind *:8404
    http-request use-service prometheus-exporter if { path /metrics }
    stats enable
    stats uri /stats
    stats refresh 10s
    stats realm obleth\ stats
    stats auth ${HAPROXY_STATS_USER}:${HAPROXY_STATS_PASSWORD}

Set the credentials in deploy/docker/.env:

HAPROXY_STATS_USER=admin
HAPROXY_STATS_PASSWORD=...   # change from the dev example

The /metrics endpoint is left unauthenticated so Prometheus can scrape it; keep :8404 on the internal network and do not publish it publicly.

Admin API protection

The admin API (:9180) should not be exposed via HAProxy. Keep it on the internal network only and use Kubernetes NetworkPolicy or firewall rules to restrict access.