Load Balancing Strategies in Easegress: 7 Built-in Policies Explained

Easegress supports seven distinct load balancing strategies—roundRobin, random, weightedRandom, ipHash, headerHash, cookieHash, and the gRPC-specific forward policy—configurable via the LoadBalanceSpec for HTTP, HTTPS, TCP, and gRPC proxies.

The easegress-io/easegress repository implements a flexible traffic distribution framework centered on the LoadBalanceSpec (defined as proxy.LoadBalance). These policies handle server selection across multiple pool types while integrating with health checking and sticky session mechanisms. This guide examines each strategy's implementation in the source code and provides production-ready configuration examples.

Core Load Balancing Policies

The primary load balancing implementations reside in pkg/filters/proxies/loadbalance.go. The GeneralLoadBalancer serves as the default balancer for HTTP and TCP traffic, supporting sticky sessions and delegating server selection to the configured policy.

Round Robin (Default)

roundRobin cycles through healthy servers in sequential order, guaranteeing uniform request distribution across the pool. If no policy is explicitly defined, Easegress defaults to this algorithm.

As implemented in pkg/filters/proxies/loadbalance.go (lines 31-34), the balancer maintains an index counter that increments atomically for each request, modulo the number of available servers.

loadBalance:
  policy: roundRobin    # Optional; used by default if omitted

Random Selection

random selects a server uniformly at random from the set of healthy backends. This strategy provides simple, stateless distribution without maintaining connection counters or indices.

The implementation (lines 35-36 in loadbalance.go) uses a standard random selection mechanism across the active server pool.

loadBalance:
  policy: random

Weighted Random

weightedRandom distributes traffic probabilistically based on server-specific weight values defined in the server configuration. Higher weights increase selection probability, allowing asymmetric capacity allocation.

The policy processes the weight field (defaulting to 1) from each server definition to construct a weighted probability distribution (lines 37-38).

servers:
  - url: http://10.0.0.1:8080
    weight: 2
  - url: http://10.0.0.2:8080
    weight: 8
loadBalance:
  policy: weightedRandom

IP Hash (Session Affinity)

ipHash calculates a hash of the client's real IP address to map requests to specific servers. This provides session affinity (sticky sessions) based on source IP, ensuring a client consistently reaches the same backend.

According to the source in loadbalance.go (lines 39-40), the algorithm hashes the source IP and applies modulo arithmetic against the server list length.

loadBalance:
  policy: ipHash

Header Hash

headerHash enables affinity based on arbitrary HTTP request attributes. The policy hashes the value of a configurable header key (specified via headerHashKey) to determine server selection.

Lines 41-42 in loadbalance.go define this behavior. You must explicitly set headerHashKey (e.g., X-User-ID or X-Tenant-ID) to enable this policy.

loadBalance:
  policy: headerHash
  headerHashKey: X-User-ID

Cookie Hash

cookieHash functions as a specialized shortcut of headerHash that automatically targets the Cookie header. This simplifies session affinity for HTTP-based applications relying on cookie-based identification.

The implementation (lines 42-44) extracts the cookie value and applies the same hashing logic as the generic header policy.

loadBalance:
  policy: cookieHash

gRPC-Specific Forwarding Strategy

The Forward Policy

forward is a specialized strategy available exclusively to the GRPCProxy filter. Rather than selecting from a static pool, this policy forwards requests to addresses dynamically extracted from gRPC metadata.

Implemented in pkg/filters/proxies/grpcproxy/loadbalance.go (lines 28-31), the policy reads the target address from a configurable metadata key (default x-target-address), enabling client-directed routing or service mesh integration.

apiVersion: easegress/v2
kind: Pipeline
spec:
  filters:
  - kind: GRPCProxy
    pools:
    - servers: []               # Empty pool; targets determined per-request

      loadBalance:
        policy: forward
        forwardKey: x-target-address

Implementation Architecture

The load balancing framework integrates with Easegress's proxy filters through the GeneralLoadBalancer struct. When processing a request, the balancer executes the following logic:

1. Sticky Session Check: If stickySession is configured in the LoadBalanceSpec, the balancer first attempts to route to a previously associated server using cookie-based session tracking.
2. Policy Delegation: If no sticky session exists or the associated server is unhealthy, the system delegates to the configured policy implementation (roundRobin, random, etc.).
3. Health Check Integration: All policies operate only on servers marked healthy by the active health checking subsystem.

This architecture ensures that policies like ipHash or headerHash respect backend availability, automatically remapping hash ranges when servers fail.

Configuration Examples

Below are complete pipeline configurations demonstrating each strategy in context:

Random Distribution:

apiVersion: easegress/v2
kind: Pipeline
spec:
  filters:
  - kind: Proxy
    pools:
    - servers:
      - url: http://10.0.0.1:8080
      - url: http://10.0.0.2:8080
      loadBalance:
        policy: random

Weighted Random with Health Checking:

apiVersion: easegress/v2
kind: Pipeline
spec:
  filters:
  - kind: Proxy
    pools:
    - servers:
      - url: http://backend-a:8080
        weight: 3
      - url: http://backend-b:8080
        weight: 1
      loadBalance:
        policy: weightedRandom
      healthCheck:
        url: /health
        interval: 10s

Header Hash for Multi-Tenant Routing:

apiVersion: easegress/v2
kind: Pipeline
spec:
  filters:
  - kind: Proxy
    pools:
    - servers:
      - url: http://tenant-pool-1:8080
      - url: http://tenant-pool-2:8080
      loadBalance:
        policy: headerHash
        headerHashKey: X-Tenant-ID

Summary

• Easegress provides seven load balancing strategies ranging from simple distribution (roundRobin, random) to sophisticated affinity (ipHash, headerHash, cookieHash) and dynamic routing (forward).
• The default roundRobin policy ensures even distribution without configuration overhead.
• WeightedRandom supports heterogeneous backend capacities through per-server weight definitions.
• Hash-based policies (ip, header, cookie) provide session affinity, implemented in pkg/filters/proxies/loadbalance.go.
• The forward policy in pkg/filters/proxies/grpcproxy/loadbalance.go enables metadata-driven routing exclusively for gRPC traffic.
• All policies integrate with the GeneralLoadBalancer, which supports sticky sessions and health check awareness.

Frequently Asked Questions

What is the default load balancing strategy in Easegress?

If the policy field is omitted from LoadBalanceSpec, Easegress defaults to roundRobin. This is hardcoded in the policy factory implementation within pkg/filters/proxies/loadbalance.go, ensuring deterministic cyclic distribution across healthy servers without explicit configuration.

How do I configure session affinity in Easegress?

Session affinity can be achieved through three hash-based policies: ipHash (client IP affinity), headerHash (custom HTTP header affinity), or cookieHash (Cookie header affinity). Alternatively, enable the stickySession sub-spec in your loadBalance configuration to use cookie-based sticky sessions managed by the GeneralLoadBalancer, which preserves client-server associations regardless of the underlying selection policy.

Can I use header-based load balancing for TCP traffic?

No. The headerHash and cookieHash policies require HTTP headers and are only applicable to HTTP/HTTPS proxies. For raw TCP traffic, use ipHash (for source IP affinity) or roundRobin/**random** distribution. TCP proxies in Easegress operate at the connection level without access to application-layer headers.

What is the difference between weightedRandom and random policies?

random selects backends with uniform probability, assuming equal capacity across servers. weightedRandom respects the weight field defined on each server object (default weight: 1), selecting servers with probability proportional to their weight. For example, a server with weight 8 receives four times the traffic of a server with weight 2 under the weightedRandom policy.

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