Load Balancing Settings

Load Balancing Policy

Load Balancing Policy defines the load balancing strategy between multiple upstream servers.

See Envoy documentation for more details.

How to configure

Some policy types support additional configuration.

Core

Config file keys	Type	Usage	Default
lb_policy	enum	optional	ROUND_ROBIN

Examples

routes:
  - from: https://myapp.localhost.pomerium.io
    to:
      - http://myapp-srv-1:8080
      - http://myapp-srv-2:8080
      - http://myapp-srv-3:8080
      - http://myapp-srv-4:8080
      - http://myapp-srv-5:8080
    lb_policy: LEAST_REQUEST
    least_request_lb_config:
      choice_count: 2 # current envoy default

Enterprise

Set the Load Balancing Policy in the Console:

Kubernetes

Annotation name	Type	Usage	Default
lb_policy	enum	optional	ROUND_ROBIN

Examples

ingress.pomerium.io/lb_policy: LEAST_REQUEST
ingress.pomerium.io/least_request_lb_config: '{"choice_count": 2}'

See Kubernetes - Ingress Configuration for more information.

Load Balancing Policy options

Load Balancer Policy options
ROUND_ROBIN
RING_HASH (may be further configured using ring_hash_lb_config option)
LEAST_REQUEST (may be further configured using least_request_lb_config)
RANDOM
MAGLEV (may be further configured using maglev_lb_config option)

Health Checks

When defined, Health Checks will issue periodic health check requests to upstream servers and unhealthy upstream servers won't serve traffic.

See Envoy's outlier_detection for automatic upstream server health detection. In the presence of multiple upstream servers, it is recommended to set up either health_checks, outlier_detection, or both.

Supported health checks parameters

Config file keys	Definition	Type	Usage
timeout	The total time to wait for a health check response.	Duration	required
interval	The interval between health checks.	Duration	required
unhealthy_threshold	The number of unhealthy health checks required before a host is marked unhealthy.	UInt32Value	required
healthy_threshold	The number of healthy health checks required before a host is marked healthy.	UInt32Value	required

See the Envoy documentation for a list of supported parameters.

How to configure

You may configure only one of the following options per health_check object definition:

• http_health_check
• tcp_health_check
• grpc_health_check

HTTP health check

Config file keys	Definition	Type	Usage
host	The Host header value in the HTTP health check request. If empty (default value), the name of the cluster this health check is associated with will be used.	string	optional
path	Specifies the HTTP path requested during a health check. For example, /healthcheck.	string	required
expected_statuses	Defines a range of HTTP response statuses that are considered healthy.	Int64Range	optional
codec_client_type	Specifies which application protocol to use: HTTP1 or HTTP2.	CodecClientType	optional

See the Envoy HTTP health checks documentation for more information.

TCP health check

Config file keys	Definition	Type	Usage
send	Defines the payload, which must be one of text or binary. An empty payload results in a connect-only health check.	Payload	optional
receive	Checks a response with 'fuzzy' matching to the extent that each payload block must be found, and in the specified order, but not necessarily contiguous.	Payload	optional

See the Envoy TCP health checks documentation for more information.

gRPC health check

Config file keys	Definition	Type	Usage
authority	The :authority header value in a gRPC health check request.	string	optional
service_name	A service name parameter sent to the gRPC service. See gRPC health checking for more information.	string	optional

See the Envoy gRPC health checks documentation for more information.

Core

Config file keys	Type	Usage
health_checks	array of objects	optional

HTTP example configuration

routes:
  - from: https://myapp.localhost.pomerium.io
    to:
      - http://myapp-srv-1:8080
      - http://myapp-srv-2:8080
    health_checks:
      - timeout: 10s
        interval: 60s
        healthy_threshold: 1
        unhealthy_threshold: 2
        http_health_check:
          path: '/'

TCP example configuration

routes:
  - from: tcp+https://tcp-service.localhost.pomerium.io
    to:
      - tcp://tcp-1.local
      - tcp://tcp-2.local
    health_checks:
      - timeout: 1s
        interval: 5s
        unhealthy_threshold: 3
        healthy_threshold: 1
        tcp_health_check:
          send:
            text: '50494E47' #PING
          receive:
            text: '504F4E47' #PONG

Enterprise

Configure Health Checks under Load Balancing settings in the Console:

Kubernetes

See Kubernetes Ingress - load balancing for more information.