Skip to main content

Upstream Load Balancing

This article covers Pomerium built-in load balancing capabilities in presence of multiple upstream servers.

Multiple Upstream Servers​

You may specify multiple servers for your upstream application, and Pomerium would load balance user requests between them.

routes:
  - from: https://myapp.localhost.pomerium.io
    to:
      - http://myapp-srv-1:8080
      - http://myapp-srv-2:8080
tip

In the presence of multiple upstream servers, make sure to specify either an active or passive health check, or both, to avoid requests being served to an unhealthy backend.

Active Health Checks​

Active health checks issue periodic requests to each upstream to determine its health. See Health Checking for a comprehensive overview.

HTTP Example​

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​

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

Passive Health Checks​

Passive health check tries to deduce upstream server health based on recent observed responses. See Outlier Detection for comprehensive overview.

routes:
  - from: https://myapp.localhost.pomerium.io
    to:
      - http://myapp-srv-1:8080
      - http://myapp-srv-2:8080
    outlier_detection: {}

Load Balancing Method​

lb_policy should be set to one of the values:

Example​

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

Load Balancing Weight​

When a list of upstream URLs is specified in the to field, you may append an optional load balancing weight parameter. The individual lb_policy settings will take this weighting into account when making routing decisions.

Example​

This configuration uses the default round_robin load balancer policy but specifies different frequency of selection be applied to the upstream servers.

routes:
  - from: https://myapp.localhost.pomerium.io
    to:
      - http://myapp-srv-1:8080,10
      - http://myapp-srv-2:8080,20
      - http://myapp-srv-3:8080,30
      - http://myapp-srv-4:8080,20
      - http://myapp-srv-5:8080,10

Further reading​