docs: add load balancing weight documentation (#1883)

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)

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.
 

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

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