Load Balancing Algorithms in INFINI Gateway: Configuration and Implementation Guide

INFINI Gateway currently implements a single weighted round-robin load balancing algorithm for both read and write operations, configured through the balancer and weights fields in the Elasticsearch filter configuration.

INFINI Gateway is a high-performance data gateway designed for Elasticsearch and other search engines. Understanding the available load balancing algorithms in INFINI Gateway is essential for optimizing traffic distribution across your cluster nodes. This guide examines the specific implementation details, configuration options, and source code structure that control how requests are routed to upstream Elasticsearch instances.

Supported Load Balancing Algorithms

Weighted Round-Robin Implementation

According to the source code in the infinilabs/gateway repository, INFINI Gateway provides exactly one load balancing algorithm: weighted round-robin. This algorithm distributes incoming requests across upstream nodes in a circular fashion, with each node receiving traffic proportional to its assigned weight.

The implementation resides in proxy/balancer/balancer.go, where the NewBalancer function constructs a balancer instance based on a slice of integer weights. The algorithm implements the IBalancer interface, exposing a Distribute method that selects the next appropriate upstream node based on the current state and weight distribution.

How Load Balancing Works in INFINI Gateway

The load balancing mechanism applies uniformly to both read and write operations. Whether processing search queries or indexing requests, INFINI Gateway uses the same weighted round-robin selection process to determine which Elasticsearch node handles the request.

The configuration structure defined in proxy/output/elastic/config.go includes a Balancer field of type string, which specifies the algorithm name, and a Weights map that associates endpoint URLs with integer values. When the Elasticsearch filter initializes, the default value "weight" is assigned in proxy/output/elastic/elasticsearch.go, ensuring the weighted round-robin algorithm is active by default.

Configuring Load Balancing

Basic Configuration

To configure load balancing in INFINI Gateway, you modify the filter configuration within your flow definition. The balancer key accepts the algorithm type (currently only "weight" is supported), while the weights map defines traffic distribution ratios.

flow:
  - name: default_flow
    filter:
      - elasticsearch:
          elasticsearch: prod
          balancer: weight          # ← balancer type (only "weight" is supported)

          weights:
            http://es-node-1:9200: 3    # ← node receives 3× the traffic of weight‑1 nodes

            http://es-node-2:9200: 1
            http://es-node-3:9200: 1

In this configuration, es-node-1 receives three times the traffic of the other nodes.

Weight Assignment Logic

The actual construction of the weight array occurs in proxy/output/elastic/reverseproxy.go. The code iterates through the configured hosts, retrieves the corresponding weight from the configuration map, and defaults to 1 if the weight is omitted or set to a value less than or equal to zero.

// From proxy/output/elastic/reverseproxy.go
ws := []int{}
for _, endpoint := range hosts {
    w, ok := cfg.Weights[endpoint]
    if !ok || w <= 0 {
        w = 1 // default weight
    }
    ws = append(ws, w)
}
p.bla = balancer.NewBalancer(ws) // creates the weighted round-robin balancer

Implementation Details

The load balancing system centers on the IBalancer interface defined in the balancer package. The weighted round-robin implementation maintains internal state to track the current position in the rotation and ensures distribution according to the specified weights.

Key source files include:

• proxy/balancer/balancer.go: Contains the NewBalancer constructor and Distribute method implementation
• proxy/output/elastic/config.go: Defines the ProxyConfig struct with Balancer and Weights fields
• proxy/output/elastic/elasticsearch.go: Sets the default balancer type to "weight"
• proxy/output/elastic/reverseproxy.go: Handles runtime construction of the balancer from configuration

Summary

• INFINI Gateway supports one load balancing algorithm: weighted round-robin, implemented in proxy/balancer/balancer.go
• The algorithm applies to both read and write operations uniformly
• Configuration occurs through the balancer (type: "weight") and weights (endpoint-to-integer map) fields in the Elasticsearch filter
• Default weight is 1 for any node where weight is omitted or set to ≤ 0
• The balancer is constructed at runtime in proxy/output/elastic/reverseproxy.go using the NewBalancer function

Frequently Asked Questions

What load balancing algorithms does INFINI Gateway support?

INFINI Gateway currently supports only the weighted round-robin algorithm. According to the source code in proxy/balancer/balancer.go, no other algorithms such as random, least-connections, or consistent-hashing are implemented. The IBalancer interface is designed to allow future extensions, but only the weighted round-robin implementation exists in the current codebase.

How do I configure different weights for Elasticsearch nodes?

Configure the weights map in your Elasticsearch filter configuration. Each key represents the endpoint URL (e.g., http://es-node-1:9200), and the value is an integer weight. Nodes with higher integers receive proportionally more traffic. If you omit a node from the weights map or set its value to 0 or negative, INFINI Gateway automatically assigns it a default weight of 1 as implemented in proxy/output/elastic/reverseproxy.go.

Does INFINI Gateway use the same algorithm for reads and writes?

Yes, INFINI Gateway uses the same weighted round-robin algorithm for both read and write operations. The balancer selection occurs at the filter level in proxy/output/elastic/elasticsearch.go, where the Balancer field defaults to "weight". There is no separate configuration path for read versus write traffic; all requests passing through the Elasticsearch filter use the same upstream selection logic defined in proxy/balancer/balancer.go.

What happens if I don't specify weights in the configuration?

If you omit the weights configuration entirely, or if specific nodes are missing from the weights map, INFINI Gateway treats every upstream node equally. According to the logic in proxy/output/elastic/reverseproxy.go, when a weight is not found or is less than or equal to zero, the system assigns a default value of 1. This results in a standard round-robin distribution where each node receives an equal share of traffic regardless of capacity or performance characteristics.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}