From ee28f008b502b25ac458a49d4b1ffbb77f28be56 Mon Sep 17 00:00:00 2001 From: Travis Groth Date: Wed, 17 Feb 2021 12:36:47 -0500 Subject: [PATCH] docs: add load balancing weight documentation (#1883) --- docs/docs/topics/load-balancing.md | 17 +++++++++++++++++ docs/docs/upgrading.md | 3 ++- docs/reference/readme.md | 6 ++++-- docs/reference/settings.yaml | 6 ++++-- 4 files changed, 27 insertions(+), 5 deletions(-) diff --git a/docs/docs/topics/load-balancing.md b/docs/docs/topics/load-balancing.md index 2970ae653..41c7c7e3c 100644 --- a/docs/docs/topics/load-balancing.md +++ b/docs/docs/topics/load-balancing.md @@ -105,6 +105,23 @@ policy: 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`](#load-balancing-method) 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 upstreams. + +```yaml +policy: + - 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 - [Introduction to modern network load balancing and proxying](https://blog.envoyproxy.io/introduction-to-modern-network-load-balancing-and-proxying-a57f6ff80236) diff --git a/docs/docs/upgrading.md b/docs/docs/upgrading.md index 72f2911ed..a09cba19e 100644 --- a/docs/docs/upgrading.md +++ b/docs/docs/upgrading.md @@ -14,7 +14,8 @@ description: >- With the v0.13 release, routes may contain [multiple `to` URLs](/reference/#to), and Pomerium will load balance between the endpoints. This allows Pomerium to fill the role of an edge proxy without the need for additional HTTP load balancers. * Active [health checks](/reference/#health-checks) and passive [outlier detection](/reference/#outlier-detection) -* Configurable [load balancing algorithms](/reference/#load-balancing-policy) +* Configurable [load balancing policies](/reference/#load-balancing-policy) +* Configurable [load balancing weight](/reference/#to) See [Load Balancing](/docs/topics/load-balancing) for more information on using this feature set. diff --git a/docs/reference/readme.md b/docs/reference/readme.md index 507ca0750..33315b92b 100644 --- a/docs/reference/readme.md +++ b/docs/reference/readme.md @@ -1273,10 +1273,10 @@ Either `redirect` or `to` must be set. ### To - `yaml`/`json` setting: `to` -- Type: `URL` or list of `URL`s (must contain a scheme and hostname) +- Type: `URL` or list of `URL`s (must contain a scheme and hostname) with an optional weight - Schemes: `http`, `https`, `tcp` - Optional -- Example: `http://verify` , `https://192.1.20.12:8080`, `http://neverssl.com`, `https://verify.pomerium.com/anything/`, `["http://a", "http://b"] +- Example: `http://verify` , `https://192.1.20.12:8080`, `http://neverssl.com`, `https://verify.pomerium.com/anything/`, `["http://a", "http://b"]`, `["http://a,10", "http://b,20"]` `To` is the destination(s) of a proxied request. It can be an internal resource, or an external resource. Multiple upstream resources can be targeted by using a list instead of a single URL: @@ -1287,6 +1287,8 @@ Either `redirect` or `to` must be set. - https://b.example.com ``` +A load balancing weight may be associated with a particular upstream by appending `,[weight]` to the URL. The exact behavior depends on your [`lb_policy`](#load-balancing-policy) setting. See [Load Balancing](/docs/topics/load-balancing) for example [configurations](/docs/topics/load-balancing.html#load-balancing-weight). + Must be `tcp` if `from` is `tcp+https`. :::warning diff --git a/docs/reference/settings.yaml b/docs/reference/settings.yaml index c14ab774c..e0c1f8c83 100644 --- a/docs/reference/settings.yaml +++ b/docs/reference/settings.yaml @@ -1402,10 +1402,10 @@ settings: keys: ["to"] attributes: | - `yaml`/`json` setting: `to` - - Type: `URL` or list of `URL`s (must contain a scheme and hostname) + - Type: `URL` or list of `URL`s (must contain a scheme and hostname) with an optional weight - Schemes: `http`, `https`, `tcp` - Optional - - Example: `http://verify` , `https://192.1.20.12:8080`, `http://neverssl.com`, `https://verify.pomerium.com/anything/`, `["http://a", "http://b"] + - Example: `http://verify` , `https://192.1.20.12:8080`, `http://neverssl.com`, `https://verify.pomerium.com/anything/`, `["http://a", "http://b"]`, `["http://a,10", "http://b,20"]` doc: | `To` is the destination(s) of a proxied request. It can be an internal resource, or an external resource. Multiple upstream resources can be targeted by using a list instead of a single URL: @@ -1416,6 +1416,8 @@ settings: - https://b.example.com ``` + A load balancing weight may be associated with a particular upstream by appending `,[weight]` to the URL. The exact behavior depends on your [`lb_policy`](#load-balancing-policy) setting. See [Load Balancing](/docs/topics/load-balancing) for example [configurations](/docs/topics/load-balancing.html#load-balancing-weight). + Must be `tcp` if `from` is `tcp+https`. :::warning