---
title: Load Balancing
description: Distribute traffic across backend instances
---

# Load Balancing

Octopus distributes traffic across an upstream's instances using a policy set per
upstream via `lb_policy`. Each instance is identified by `id`, `host`, and `port`.

<Callout type="warn" title="Policy is honored on the operator path">
  `lb_policy` (and instance `weight`) map to a live balancer on the
  Kubernetes/operator-driven path. For upstreams registered from a **static
  config file**, the gateway currently uses round-robin regardless of
  `lb_policy`. See [Upstreams](/docs/octopus/configuration/upstreams).
</Callout>

## Strategies

The recognized `lb_policy` values are `round_robin` (default),
`least_connections` (alias `least_conn`), `weighted_round_robin` (alias
`weighted`), `random`, and `ip_hash`.

### Round Robin

Distributes requests evenly across instances:

```yaml
upstreams:
  - name: api-service
    lb_policy: round_robin
    instances:
      - id: api-1
        host: 10.0.0.11
        port: 8080
      - id: api-2
        host: 10.0.0.12
        port: 8080
```

**Best for**: Homogeneous backends with similar capacity

### Least Connections

Routes to the instance with the fewest active connections:

```yaml
upstreams:
  - name: api-service
    lb_policy: least_connections
    instances:
      - id: api-1
        host: 10.0.0.11
        port: 8080
      - id: api-2
        host: 10.0.0.12
        port: 8080
```

**Best for**: Long-lived connections, varying request duration

### Weighted Round Robin

Distributes based on instance weights:

```yaml
upstreams:
  - name: api-service
    lb_policy: weighted_round_robin
    instances:
      - id: api-1
        host: 10.0.0.11
        port: 8080
        weight: 2   # Gets 2x the traffic of api-2
      - id: api-2
        host: 10.0.0.12
        port: 8080
        weight: 1
```

**Best for**: Heterogeneous backends with different capacity

### Random

Picks an instance at random:

```yaml
upstreams:
  - name: api-service
    lb_policy: random
    instances:
      - id: api-1
        host: 10.0.0.11
        port: 8080
      - id: api-2
        host: 10.0.0.12
        port: 8080
```

### IP Hash

Routes the same client IP to the same instance (consistent hash on client IP):

```yaml
upstreams:
  - name: api-service
    lb_policy: ip_hash
    instances:
      - id: api-1
        host: 10.0.0.11
        port: 8080
      - id: api-2
        host: 10.0.0.12
        port: 8080
```

**Best for**: Stateful applications, session affinity

## Health-Aware Load Balancing

When active health checking is wired (operator path), only healthy instances
receive traffic and unhealthy instances are removed from rotation:

```yaml
upstreams:
  - name: api-service
    lb_policy: round_robin
    health_check:
      type: http
      path: /healthz
      interval: 10s
      timeout: 2s
    instances:
      - id: api-1
        host: 10.0.0.11
        port: 8080
```

## See Also

- [Health Checks](/docs/octopus/concepts/health-checks)
- [Circuit Breaker](/docs/octopus/concepts/circuit-breaker)
- [Upstreams configuration](/docs/octopus/configuration/upstreams)