Distributes requests across a set of backend nodes. Nodes are grouped into one or more clusters, and the configured dispatching strategy picks a node for each request, defaulting to round-robin. Failover is always on: the remaining nodes are added as fallback destinations, so a request retries the next node when one fails. When a sessionIdExtractor is configured, requests carrying a known session are pinned to the node that first served it (sticky sessions). On dispatch the chosen node is stored on the exchange and its statistics are updated when the response returns; if no node is available the request is answered with 503. Can only be used inside an api or serviceProxy. See the examples under examples/loadbalancing.

 balancer:
   [ name: <id> ]                  # default: Default
   [ sessionIdExtractor: ... ]      # enables sticky sessions
   [ roundRobinStrategy | priorityStrategy | byThreadStrategy | faultMonitoringStrategy ]
   clusters:                        # 1..*
     - name: <id>
       nodes:                       # 1..*
         - host: <host>
           port: <port>
     ...

Example Configuration

api:
   port: 2000
   flow:
     - balancer:
         name: DemoBalancer
         clusters:
           - name: PROD
             nodes:
               - host: node1.predic8.com
                 port: 8080
               - host: node2.predic8.com
                 port: 8090

api:
   port: 2000
   flow:
     - balancer:
         name: DemoBalancer
         clusters:
           - name: PROD
             nodes:
               - host: node1.predic8.com
                 port: 8080
               - host: node2.predic8.com
                 port: 8090

Syntax

balancer:
  '$ref': <string>
  byThreadStrategy: {}
  clusters:
    - <cluster>
  faultMonitoringStrategy: {}
  jSessionIdExtractor: {}
  name: <string>
  priorityStrategy: {}
  roundRobinStrategy: {}
  sessionIdExtractor: {}
  sessionTimeout: <number>
  trackNodeStatus: <boolean>
  xmlSessionIdExtractor: {}

balancer:
  '$ref': <string>
  byThreadStrategy: {}
  clusters:
    - <cluster>
  faultMonitoringStrategy: {}
  jSessionIdExtractor: {}
  name: <string>
  priorityStrategy: {}
  roundRobinStrategy: {}
  sessionIdExtractor: {}
  sessionTimeout: <number>
  trackNodeStatus: <boolean>
  xmlSessionIdExtractor: {}

Attributes

Name	Required	Default	Description	Examples
$ref	false	-	Reference a component defined under components.	-
name	false	Default	Identifies this balancer when more than one is configured. Used by the web administration interface and the lbclient to address its nodes.	balancer1
sessionTimeout	false	3600000	Time in milliseconds after which an idle sticky session expires. Applies only when a sessionIdExtractor is configured. `0` disables expiry.	600000
trackNodeStatus	false	false	Whether to record the per-node outcome of every request on the exchange, so later plugins can inspect which node handled it and how.	-

Child Structure

Element	Cardinality	Description
byThreadStrategy	0..1	Dispatches each request to a node that has fewer than maxNumberOfThreadsPerEndpoint requests in flight, capping concurrency per node. When every node is at capacity it waits retryTimeOnBusy milliseconds and retries, up to five times, then fails the request with an error.
cluster	0..*	Clusters of nodes managed by this balancer. Nodes in the same cluster share session state.
faultMonitoringStrategy	0..1	Monitors the outcome of requests to each node to quickly disable/re-enable faulty ones.
jSessionIdExtractor	0..1	The jSessionIdExtractor extracts the JSESSIONID from a message and provides it to the {@link Balancer}.
priorityStrategy	0..1	Selects a node by ascending priority, then health. Nodes are grouped by their priority value (lower means higher priority); the first group that contains at least one node currently up is used, and if it holds several up nodes one is picked at random. Lower-priority groups are only used once all higher-priority nodes are down. If no node is up anywhere, it falls back to the first node in priority order. Set each node's priority attribute to control the order.
roundRobinStrategy	0..1	Dispatches requests to the available nodes in rotation, one after another. It ignores sessions and node load; only nodes currently up take part. This is the balancer's default strategy when none is configured.
sessionIdExtractor	0..1	Extracts a session ID from requests and responses to enable sticky sessions. Requests carrying a known session are routed back to the node that first handled it, until that node goes down.
xmlSessionIdExtractor	0..1	Extracts a session ID from an XML HTTP request body based on the qualified name of an XML element.

Can be used in

abort api case chain components for global if interceptor internal otherwise proxy registration request response serviceProxy soapProxy stompProxy time transport wsStompReassembler