Load Balancing for OpenAPI

Overview

Relixy can distribute traffic across multiple upstream servers for a single OpenAPI resource. This enables high availability and horizontal scaling without changes to the client.

Key capabilities:

• Round-robin and weighted round-robin traffic distribution
• Health checks to automatically remove and restore unhealthy servers
• Per-server headers and mTLS configuration

When a server fails its health check, Relixy removes it from the pool and stops routing traffic to it. Once the server recovers and passes the configured success threshold, it is automatically re-added.

Configuration

Defining multiple servers

Load balancing is activated when two or more servers are defined in the OpenAPI document. Use patches to inject server URLs via environment variables:

version: v1
kind: OpenAPI
metadata:
  name: pet-api
definition:
  ref: https://example.com/openapi.json
  patches:
    - target: $
      update:
        servers:
          - url: "{SERVER_URL}"
          - url: "{SERVER_URL_2}"

The patches field follows the OpenAPI Overlay specification. The target: $ selector replaces the root-level servers array.

Health check

Configure healthCheck under settings to control how Relixy probes each server:

version: v1
kind: OpenAPI
metadata:
  name: pet-api
definition:
  ref: ...
  settings:
    healthCheck:
      http:
        path: /health # required — endpoint to probe
        method: GET # default: GET
        headers: # optional headers sent with each probe
          Authorization:
            env: HEALTH_TOKEN
        interval: 60 # seconds between probes (default: 60)
        timeout: 5 # seconds before a probe times out (default: 5)
        successStatus: 200 # expected HTTP status code (200, 201, or 204)
        successThreshold: 1 # consecutive successes required to mark healthy
        failureThreshold: 3 # consecutive failures required to mark unhealthy

A server is removed from the rotation after failureThreshold consecutive failed probes, and is re-added after successThreshold consecutive successful probes.

Server extensions

Relixy reads the following vendor extensions on each entry in the OpenAPI servers array:

Extension	Type	Description
x-rely-server-weight	integer	Traffic weight. Values > 1 increase the server's share of requests.
x-rely-server-headers	object	Map of HTTP headers added to every request forwarded to this server.
x-rely-server-tls	object	TLS / mTLS configuration for the connection to this server.

Weighted round-robin example

servers:
  - url: "https://primary.example.com"
    x-rely-server-weight: 3 # receives 3× more traffic than secondary
    x-rely-server-headers:
      X-Region: "us-east-1"
  - url: "https://secondary.example.com"
    x-rely-server-weight: 1
    x-rely-server-headers:
      X-Region: "us-west-2"

In this example, primary.example.com receives 3 out of every 4 requests and secondary.example.com receives 1.