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

> Explore 7 essential Easegress load balancing strategies like roundRobin, ipHash, and weightedRandom. Optimize your proxy performance with efficient traffic distribution.

- Repository: [easegress-io/easegress](https://github.com/easegress-io/easegress)
- Tags: tutorial
- Published: 2026-03-01

---

**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`](https://github.com/easegress-io/easegress/blob/main/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`](https://github.com/easegress-io/easegress/blob/main/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.

```yaml
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`](https://github.com/easegress-io/easegress/blob/main/loadbalance.go)) uses a standard random selection mechanism across the active server pool.

```yaml
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).

```yaml
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`](https://github.com/easegress-io/easegress/blob/main/loadbalance.go) (lines 39-40), the algorithm hashes the source IP and applies modulo arithmetic against the server list length.

```yaml
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`](https://github.com/easegress-io/easegress/blob/main/loadbalance.go) define this behavior. You must explicitly set `headerHashKey` (e.g., `X-User-ID` or `X-Tenant-ID`) to enable this policy.

```yaml
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.

```yaml
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`](https://github.com/easegress-io/easegress/blob/main/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.

```yaml
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:**

```yaml
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:**

```yaml
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:**

```yaml
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`](https://github.com/easegress-io/easegress/blob/main/pkg/filters/proxies/loadbalance.go).
- The **forward** policy in [`pkg/filters/proxies/grpcproxy/loadbalance.go`](https://github.com/easegress-io/easegress/blob/main/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`](https://github.com/easegress-io/easegress/blob/main/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.