HAProxy

Status: Stub — content pending.

title: "HAProxy" description: "HAProxy configuration for TLS termination, round-robin load balancing across obleth pods, and streaming support."

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

Admin API protection

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