Backends

Backends define pools of upstream servers. Each backend has a load balancing algorithm, optional health checks, and a list of server addresses in host:port format.

Server Pools

Servers are specified as host:port strings. Use plain addresses without scheme — the protocol is determined by the listener.

Backend with server pool

backends:
  - name: web_servers
    balance: roundrobin
    servers:
      - "10.0.1.10:8080"
      - "10.0.1.11:8080"
      - "10.0.1.12:8080"

Load Balancing Algorithms

Choose an algorithm based on your workload:

roundrobin — Distribute evenly across servers (default)
leastconn — Route to the server with fewest active connections
iphash — Sticky sessions based on client IP hash
weighted — Weighted distribution for heterogeneous servers

Sticky Sessions

Enable session persistence with sticky_session. Supports cookie-based and header-based affinity.

Balance algorithms + sticky sessions

backends:
  - name: api_servers
    balance: leastconn
    servers:
      - "10.0.2.10:3000"
      - "10.0.2.11:3000"

  - name: stateful_app
    balance: roundrobin
    sticky_session:
      type: cookie
      cookie_name: nvelox-sticky
      ttl: 1h
    servers:
      - "10.0.3.10:8080"
      - "10.0.3.11:8080"

Health Checks

Unhealthy servers are automatically removed from the pool. Nvelox supports active health checks (HTTP/TCP probes) and passive health checks (consecutive failure tracking).

Active Health Checks

active.type — http or tcp
active.path — HTTP path to check (required for type: http)
active.interval — Time between checks
active.timeout — Per-check timeout

Passive Health Checks

passive.max_fails — Consecutive failures to mark server unhealthy

Active health check (HTTP)

backends:
  - name: app_servers
    balance: roundrobin
    servers:
      - "10.0.1.10:8080"
    health_check:
      active:
        type: http
        interval: 10s
        timeout: 5s
        path: /healthz
      passive:
        max_fails: 3

TCP health check

health_check:
  active:
    type: tcp
    interval: 15s
    timeout: 3s

Backend TLS

When nvelox connects to upstream servers over TLS, configure the backend_tls block. Use insecure: true to skip certificate verification (dev only).

enabled — Enable TLS for backend connections
insecure — Skip certificate verification
ca_cert — CA certificate for server verification
client_cert — Client certificate for mTLS
client_key — Client private key for mTLS

Warning: Server addresses in backends should not include a scheme prefix. Use 10.0.1.10:8443, not https://10.0.1.10:8443.

Backend TLS

backends:
  - name: secure_api
    balance: roundrobin
    backend_tls:
      enabled: true
      insecure: false
      ca_cert: /etc/nvelox/ca/server-ca.crt
      client_cert: /etc/nvelox/client/client.crt
      client_key: /etc/nvelox/client/client.key
    servers:
      - "10.0.1.10:8443"
      - "10.0.1.11:8443"

DNS Service Discovery

Nvelox can discover backend servers dynamically via DNS. Set resolve_interval to periodically re-resolve server addresses.

DNS resolution

backends:
  - name: dynamic_servers
    balance: roundrobin
    resolve_interval: 30s
    servers:
      - "api.service.consul:8080"