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.
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.
Strategies01
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:
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: 8080Best for: Homogeneous backends with similar capacity
Least Connections
Routes to the instance with the fewest active connections:
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: 8080Best for: Long-lived connections, varying request duration
Weighted Round Robin
Distributes based on instance weights:
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: 1Best for: Heterogeneous backends with different capacity
Random
Picks an instance at random:
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: 8080IP Hash
Routes the same client IP to the same instance (consistent hash on client IP):
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: 8080Best for: Stateful applications, session affinity
Health-Aware Load Balancing02
When active health checking is wired (operator path), only healthy instances receive traffic and unhealthy instances are removed from rotation:
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