Load balancing

Load balancing configuration can be set for all Emissary mappings in the ambassador Module, or set per Mapping. If nothing is set, simple round robin balancing is used via Kubernetes services.

To use advanced load balancing, you must first configure a resolver that supports advanced load balancing (e.g., the Kubernetes Endpoint Resolver or Consul Resolver). Once a resolver is configured, you can use the load_balancer attribute. The following fields are supported:

load_balancer:
  policy: <load balancing policy to use>

Supported load balancer policies:

• round_robin
• least_request
• ring_hash
• maglev

For more information on the different policies and the implications, see load balancing strategies in Kubernetes.

Round robin

When policy is set to round_robin, Emissary discovers healthy endpoints for the given mapping, and load balances the incoming L7 requests with round robin scheduling. To specify this:

apiVersion: getambassador.io/v3alpha1
kind:  Module
metadata:
  name:  ambassador
spec:
  config:
    resolver: my-resolver
    load_balancer:
      policy: round_robin

or, per mapping:

---
apiVersion: getambassador.io/v3alpha1
kind:  Mapping
metadata:
  name:  quote-backend
spec:
  prefix: /backend/
  service: quote
  resolver: my-resolver
  hostname: '*'
  load_balancer:
    policy: round_robin

Note that load balancing may not appear to be “even” due to Envoy’s threading model. For more details, see the Envoy documentation.

Least request

When policy is set to least_request, Emissary discovers healthy endpoints for the given mapping, and load balances the incoming L7 requests to the endpoint with the fewest active requests. To specify this:

apiVersion: getambassador.io/v3alpha1
kind:  Module
metadata:
  name:  ambassador
spec:
  config:
    resolver: my-resolver
    load_balancer:
      policy: least_request

or, per mapping:

---
apiVersion: getambassador.io/v3alpha1
kind:  Mapping
metadata:
  name:  quote-backend/
spec:
  hostname: '*'
  prefix: /backend/
  service: quote
  resolver: my-resolver
  load_balancer:
    policy: least_request

Sticky sessions / session affinity

Configuring sticky sessions makes Emissary route requests to a specific pod providing your service in a given session. One pod serves all requests from a given session, eliminating the need for session data to be transferred between pods. Emissary lets you configure session affinity based on the following parameters in an incoming request:

• Cookie
• Header
• Source IP

NOTE: Emissary supports sticky sessions using two load balancing policies, ring_hash and maglev.

Cookie

load_balancer:
  policy: ring_hash
  cookie:
    name: <name of the cookie, required>
    ttl: <TTL to set in the generated cookie>
    path: <name of the path for the cookie>

If the cookie you wish to set affinity on is already present in incoming requests, then you only need the cookie.name field. However, if you want Emissary to generate and set a cookie in response to the first request, then you need to specify a value for the cookie.ttl field which generates a cookie with the given expiration time.

apiVersion: getambassador.io/v3alpha1
kind:  Mapping
metadata:
  name:  quote-backend
spec:
  prefix: /backend/
  hostname: '*'
  service: quote
  resolver: my-resolver
  load_balancer:
    policy: ring_hash
    cookie:
      name: sticky-cookie
      ttl: 60s

Header

load_balancer:
  policy: ring_hash
  header: <header name>

Emissary allows header based session affinity if the given header is present on incoming requests.

Example:

apiVersion: getambassador.io/v3alpha1
kind:  Mapping
metadata:
  name:  quote-backend
spec:
  hostname: '*'
  prefix: /backend/
  service: quote
  resolver: my-resolver
  load_balancer:
    policy: ring_hash
    header: STICKY_HEADER

Source IP

load_balancer:
  policy: ring_hash
  source_ip: <boolean>

Emissary allows session affinity based on the source IP of incoming requests.

apiVersion: getambassador.io/v3alpha1
kind:  Mapping
metadata:
  name:  quote-backend
spec:
  hostname: '*'
  prefix: /backend/
  service: quote
  resolver: my-resolver
  load_balancer:
    policy: ring_hash
    source_ip: true

Load balancing can be configured both globally, and overridden on a per mapping basis. The following example configures the default load balancing policy to be round robin, while using header-based session affinity for requests to the /backend/ endpoint of the quote application:

Load balancing can be configured both globally, and overridden on a per mapping basis.

apiVersion: getambassador.io/v3alpha1
kind:  Module
metadata:
  name:  ambassador
spec:
  config:
    resolver: my-resolver
    load_balancer:
      policy: round_robin

apiVersion: getambassador.io/v3alpha1
kind:  Mapping
metadata:
  name:  quote-backend
spec:
  hostname: '*'
  prefix: /backend/
  service: quote
  resolver: my-resolver
  load_balancer:
    policy: ring_hash
    header: STICKY_HEADER