Load Balancing

Bastion distributes traffic across upstream targets using configurable load balancing strategies. Each route can have multiple targets, and the load balancer selects a healthy target for every request. Five strategies are available out of the box.

Configuration

Set the global load balancing strategy:

bastion.WithLoadBalancing(bastion.LoadBalancingConfig{
    Strategy: bastion.LBWeightedRoundRobin,
})

Configuration Fields

Strategies

Round Robin

bastion.WithLoadBalancing(bastion.LoadBalancingConfig{
    Strategy: bastion.LBRoundRobin,
})

Selects targets in sequential order. Each target receives an equal share of requests regardless of weight. This is the default strategy and works well when all targets have similar capacity.

Weighted Round Robin

bastion.WithLoadBalancing(bastion.LoadBalancingConfig{
    Strategy: bastion.LBWeightedRoundRobin,
})

Uses a smooth weighted round-robin algorithm. Targets receive traffic proportional to their configured weight. A target with weight 3 receives roughly three times as many requests as a target with weight 1.

Configure weights per target:

bastion.WithRoute(bastion.RouteConfig{
    Path: "/api/*",
    Targets: []bastion.TargetConfig{
        {URL: "http://primary:8080", Weight: 3},
        {URL: "http://secondary:8080", Weight: 1},
    },
})

If all targets have equal weights (or weight 0), this strategy falls back to simple round robin.

Random

bastion.WithLoadBalancing(bastion.LoadBalancingConfig{
    Strategy: bastion.LBRandom,
})

Selects a random healthy target for each request. Provides natural distribution without any shared state, making it suitable for high-concurrency scenarios where round-robin counters might become a bottleneck.

Least Connections

bastion.WithLoadBalancing(bastion.LoadBalancingConfig{
    Strategy: bastion.LBLeastConnections,
})

Selects the target with the fewest active connections. This strategy adapts to heterogeneous backend performance -- slower targets naturally accumulate more connections and receive fewer new requests.

Active connections are tracked per target using atomic counters. The count increments when a request is forwarded and decrements when the response completes.

Consistent Hash

bastion.WithLoadBalancing(bastion.LoadBalancingConfig{
    Strategy:      bastion.LBConsistentHash,
    ConsistentKey: "header:X-User-ID",
})

Uses FNV hashing to deterministically route requests with the same key to the same target. This provides session affinity without server-side session state.

The ConsistentKey determines which request attribute is hashed. When a target is added or removed, only a fraction of keys are remapped.

Health Filtering

Before the load balancer selects a target, unhealthy and unavailable targets are filtered out. A target is excluded if:

• Its Healthy flag is false (failed health checks).
• Its circuit breaker is in the Open state.
• It is in the Draining state (graceful shutdown).

If all targets are unhealthy, the load balancer returns nil and the proxy engine responds with 503 Service Unavailable.

Per-Route Strategy

The global load balancing strategy applies to all routes. Routes inherit the global strategy automatically. To use different strategies for different routes, configure multiple gateway instances or use traffic splitting policies for fine-grained control.

Target Weights

Weights are integers where higher values mean more traffic. Weights only affect the LBWeightedRoundRobin strategy. Targets with weight 0 or unset are treated as weight 1.

bastion.WithRoute(bastion.RouteConfig{
    Path: "/api/*",
    Targets: []bastion.TargetConfig{
        {URL: "http://large-instance:8080", Weight: 5},
        {URL: "http://medium-instance:8080", Weight: 3},
        {URL: "http://small-instance:8080", Weight: 1},
    },
})

In this configuration, the large instance receives approximately 55% of traffic, the medium instance 33%, and the small instance 11%.

Strategy Constants