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

Pomerium currently exposes policy selection only. Advanced Envoy policy-specific configuration objects are not configurable through route settings.

Core

Config file keys	Type	Usage	Default
load_balancing_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
    load_balancing_policy: LEAST_REQUEST

Enterprise

Set the Load Balancing Policy in the Console:

The load_balancing_policy setting can also be configured by Terraform.

Kubernetes

Kubernetes does not currently expose a load balancing policy annotation.

Load Balancing Policy options

Pomerium currently supports selecting one of Envoy's built-in load balancing policies. Policy-specific Envoy config objects such as least_request_lb_config, ring_hash_lb_config, and maglev_lb_config are not currently exposed.

Load Balancer Policy options
ROUND_ROBIN
RING_HASH
LEAST_REQUEST
RANDOM
MAGLEV

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.