From 58a018c20bc892d81ae83b849c8dca1e9d3aea50 Mon Sep 17 00:00:00 2001 From: freddygv Date: Fri, 28 Aug 2020 14:46:13 -0600 Subject: [PATCH] Add documentation for resolver LB cfg --- agent/structs/config_entry_discoverychain.go | 6 +- api/config_entry_discoverychain.go | 4 +- .../agent/config-entries/service-resolver.mdx | 68 ++++++++++++++++++- 3 files changed, 71 insertions(+), 7 deletions(-) diff --git a/agent/structs/config_entry_discoverychain.go b/agent/structs/config_entry_discoverychain.go index c87b46f00..79a33cb48 100644 --- a/agent/structs/config_entry_discoverychain.go +++ b/agent/structs/config_entry_discoverychain.go @@ -1028,10 +1028,10 @@ func (l LoadBalancer) IsHashBased() bool { // RingHashConfig contains configuration for the "ring_hash" policy type type RingHashConfig struct { - // MinimumRingSize determines the minimum number of hashes per destination host + // MinimumRingSize determines the minimum number of entries in the hash ring MinimumRingSize uint64 `json:",omitempty" alias:"minimum_ring_size"` - // MaximumRingSize determines the maximum number of hashes per destination host + // MaximumRingSize determines the maximum number of entries in the hash ring MaximumRingSize uint64 `json:",omitempty" alias:"maximum_ring_size"` } @@ -1058,7 +1058,7 @@ type HashPolicy struct { FieldMatchValue string `json:",omitempty" alias:"field_value"` // SourceAddress determines whether the hash should be of the source IP rather than of a field and field value. - // Cannot be specified along with Field and FieldMatchValue. + // Cannot be specified along with Field or FieldMatchValue. SourceAddress bool `json:",omitempty" alias:"source_address"` // Terminal will short circuit the computation of the hash when multiple hash policies are present. diff --git a/api/config_entry_discoverychain.go b/api/config_entry_discoverychain.go index 0bfd3dde2..5e1636fe8 100644 --- a/api/config_entry_discoverychain.go +++ b/api/config_entry_discoverychain.go @@ -228,10 +228,10 @@ type LoadBalancer struct { // RingHashConfig contains configuration for the "ring_hash" policy type type RingHashConfig struct { - // MinimumRingSize determines the minimum number of hashes per destination host + // MinimumRingSize determines the minimum number of entries in the hash ring MinimumRingSize uint64 `json:",omitempty" alias:"minimum_ring_size"` - // MaximumRingSize determines the maximum number of hashes per destination host + // MaximumRingSize determines the maximum number of entries in the hash ring MaximumRingSize uint64 `json:",omitempty" alias:"maximum_ring_size"` } diff --git a/website/pages/docs/agent/config-entries/service-resolver.mdx b/website/pages/docs/agent/config-entries/service-resolver.mdx index 7c418604a..d0cd54988 100644 --- a/website/pages/docs/agent/config-entries/service-resolver.mdx +++ b/website/pages/docs/agent/config-entries/service-resolver.mdx @@ -72,6 +72,23 @@ Kind = "service-resolver" Name = "web" ``` +Apply consistent load balancing for requests based on `x-user-id` header: + +```hcl +Kind = "service-resolver" +Name = "web" + +LoadBalancer = { + Policy = "maglev" + HashPolicies = [ + { + Field = "header" + FieldMatchValue = "x-user-id" + } + ] +} +``` + ## Available Fields - `Kind` - Must be set to `service-resolver` @@ -117,8 +134,8 @@ Name = "web" resolve instead of one defined as that service's DefaultSubset If empty the default subset is used. - If this is specified at least one of Service, Datacenter, or Namespace - should be configured. + If this is specified at least one of Service, Datacenter, or Namespace + should be configured. - `Namespace` `(string: "")` - The namespace to resolve the service from instead of the current one. @@ -149,6 +166,53 @@ Name = "web" - `Datacenters` `(array)` - A fixed list of datacenters to try during failover. + +- `LoadBalancer` `(LoadBalancer`) - Determines the load balancing policy and + configuration for services issuing requests to this upstream. + This option is available in Consul versions 1.8.4 and newer. + + **Note:** The options below are specific to Envoy proxy. + + - `Policy` `(string: "")` - The load balancing policy used to select a host. + One of: `random`, `round_robin`, `least_request`, `ring_hash`, `maglev`. + + - `RingHashConfig` `(RingHashConfig)` - Configuration for the `ring_hash` + policy type. + + - `MinimumRingRize` `(int: 1024)` - Determines the minimum number of entries + in the hash ring. + + - `MaximumRingRize` `(int: 8192)` - Determines the maximum number of entries + in the hash ring. + + - `LeastRequestConfig` `(LeastRequestConfig)` - Configuration for the `least_request` + policy type. + + - `ChoiceCount` `(int: 2)` - Determines the number of random healthy hosts + from which to select the one with the least requests. + + - `HashPolicies` `(array)` - a list of hash policies to use for + hashing load balancing algorithms. Hash policies are evaluated individually + and combined such that identical lists result in the same hash. + If no hash policies are present, or none are successfully evaluated, + then a random backend host will be selected. + + - `Field` `(string: "")` - The attribute type to hash on. + Must be one of `header`,`cookie`, or `query_parameter`. + Cannot be specified along with `SourceAddress`. + + - `FieldMatchValue` `(string: "")` - The value to hash. + ie. header name, cookie name, URL query parameter name. + Cannot be specified along with `SourceAddress`. + + - `SourceAddress` `(bool: false)` - Determines whether the hash should be of the source IP + address rather than of a field and field value. + Cannot be specified along with `Field` or `FieldMatchValue`. + + - `Terminal` `(bool: false)` - Will short circuit the computation of the hash + when multiple hash policies are present. If a hash is computed when a + Terminal policy is evaluated, then that hash will be used and subsequent + hash policies will be ignored. ## Service Subsets