Load Balancing in Ambassador

Load balancing configuration can be set for all Ambassador 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
  • 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, Ambassador discovers healthy endpoints for the given mapping, and load balances the incoming L7 requests in a round robin fashion. For example:

apiVersion: ambassador/v1
kind:  Module
name:  ambassador
config:
  resolver: my-resolver
  load_balancer:
    policy: round_robin

or, per mapping:

---
apiVersion: ambassador/v1
kind:  Mapping
name:  tour-ui_mapping
prefix: /
service: tour
resolver: my-resolver
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.

Sticky Sessions / Session Affinity

Configuring sticky sessions makes Ambassador route requests to the same backend service in a given session. In other words, requests in a session are served by the same Kubernetes pod. Ambassador lets you configure session affinity based on the following parameters in an incoming request:

  • Cookie
  • Header
  • Source IP

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

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 Ambassador 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.

For example, the following configuration asks the client to set a cookie named sticky-cookie with expiration of 60 seconds in response to the first request if the cookie is not already present.

apiVersion: ambassador/v1
kind:  Mapping
name:  tour-ui_mapping
prefix: /
service: tour
resolver: my-resolver
load_balancer:
  policy: ring_hash
  cookie:
    name: sticky-cookie
    ttl: 60s
load_balancer:
  policy: ring_hash
  header: <header name>

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

Example:

apiVersion: ambassador/v1
kind:  Mapping
name:  tour-ui_mapping
prefix: /
service: tour
resolver: my-resolver
load_balancer:
  policy: ring_hash
  header: STICKY_HEADER
Source IP
load_balancer:
  policy: ring_hash
  source_ip: <boolean>

Ambassador allows session affinity based on the source IP of incoming requests. For example:

apiVersion: ambassador/v1
kind:  Mapping
name:  tour-ui_mapping
prefix: /
service: tour
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 tour application:

apiVersion: ambassador/v0
kind:  Module
name:  ambassador
config:
  resolver: my-resolver
  load_balancer:
    policy: round_robin
apiVersion: ambassador/v1
kind:  Mapping
name:  tour-backend_mapping
prefix: /backend/
service: tour
resolver: my-resolver
load_balancer:
  policy: ring_hash
  header: STICKY_HEADER

Disabling advanced load balancing

In Ambassador 0.60, you can disable advanced load balancing features by setting the environment variable AMBASSADOR_DISABLE_ENDPOINTS to any value. If you find that this is necessary, please reach out to us on Slack so we can fix whatever is wrong!