[NET-5916] Update locality-aware routing docs (#19529)

* docs: Update locality-aware routing docs - Align locality-aware routing documentation to the recommended use of the feature and incorporate engineer feedback. - Remove docs for unreleased multi-cluster failover feature. - Fix minor typos and formatting in examples. * docs: Fix rate limit docs typo
hashicorp · hc-github-team-consul-core · Nov 13, 2023 · Oct 13, 2023 · Oct 13, 2023 · Oct 13, 2023
commit c9f2a6add44119f04b21ddde32de8ee52b00c9d5
@@ -1284,9 +1284,9 @@ subsystem that provides Consul's service mesh capabilities.
         corresponding to the NIST P-\* curves of the same name.
       - `private_key_type = rsa`: `2048, 4096`
 
-- `locality` <EnterpriseAlert inline/>: Specifies a map of configurations that set the region and zone of the Consul agent. When specified on server agents, `locality` applies to all partitions on the server. When specified on clients, `locality` applies to all services registered to the client. Configure this field to enable Consul to route traffic to the nearest physical service instance. Refer to [Route traffic to local upstreams](/consul/docs/connect/manage-traffic/route-to-local-upstreams) for additional information.
-  - `region`:  String value that specifies the region where the Consul agent is running. Consul matches this value to regions defined for services in the network. When service agent regions match, Consul is able to prioritize routes between the agent and the service in the same region over healthy service instances in other regions. When multiple healthy service instances are available in the local region, Consul prioritizes services that match the agent's `zone`. You must specify values that are consistent with how regions are defined in your network, for example `us-west-1` for networks in AWS.
-  - `zone`: String value that specifies the availability zone where the Consul agent is running. Consul matches this value to zones defined for services in the region. When service agent zones match, Consul is able to prioritize routes between the agent and the service in the same zone over healthy service instances in other zones. When multiple healthy service instances are available in the local zone, Consul distributes traffic equally the services. You must specify values that are consistent with how zones are defined in your network, for example `us-west-1a` for networks in AWS.    
+- `locality` <EnterpriseAlert inline/>: Specifies a map of configurations that set the region and zone of the Consul agent. When specified on server agents, `locality` applies to all partitions on the server. When specified on clients, `locality` applies to all services registered to the client. Configure this field to enable Consul to route traffic to the nearest physical service instance. This field is intended for use primarily with VM and Nomad workloads. Refer to [Route traffic to local upstreams](/consul/docs/connect/manage-traffic/route-to-local-upstreams) for additional information.
+  - `region`:  String value that specifies the region where the Consul agent is running. Consul assigns this value to services registered to that agent. When service proxy regions match, Consul is able to prioritize routes between service instances in the same region over instances in other regions. You must specify values that are consistent with how regions are defined in your network, for example `us-west-1` for networks in AWS.
+  - `zone`: String value that specifies the availability zone where the Consul agent is running. Consul assigns this value to services registered to that agent. When service proxy regions match, Consul is able to prioritize routes between service instances in the same region and zone over instances in other regions and zones. When healthy service instances are available in multiple zones within the most-local region, Consul prioritizes instances that also match the downstream proxy's `zone`. You must specify values that are consistent with how zones are defined in your network, for example `us-west-1a` for networks in AWS.
 
 ## DNS and Domain Parameters
 

@@ -50,9 +50,7 @@ The following list outlines field hierarchy, language-specific data types, and r
       - [`ListenerPort`](#expose-paths): number | `0` 
       - [`Protocol`](#expose-paths): string | `http` 
 - [`PrioritizeByLocality`](#prioritizebylocality): map | <EnterpriseAlert inline/>
-  - [`Mode`](#prioritizebylocality): string | `failover`
-- [`FailoverPolicy`](#failoverpolicy): map
-   - [`Mode`](#failoverpolicy-mode): string
+   - [`Mode`](#prioritizebylocality): string | `failover`
 - [`AccessLogs`](#accesslogs): map
    - [`Enabled`](#accesslogs): boolean | `false`
    - [`DisableListenerLogs`](#accesslogs): boolean | `false`
@@ -92,9 +90,7 @@ The following list outlines field hierarchy, language-specific data types, and r
          - [`listenerPort`](#spec-expose-paths): number | `0` 
          - [`protocol`](#spec-expose-paths): string | `http` 
   - [`prioritizeByLocality`](#prioritizebylocality): map | <EnterpriseAlert inline/>
-    - [`mode`](#prioritizebylocality): string | `failover` 
-  - [`failoverPolicy`](#spec-failoverpolicy): map
-      - [`mode`](#spec-failoverpolicy-mode): string
+     - [`mode`](#prioritizebylocality): string | `failover`
   - [`accessLogs`](#spec-accesslogs): map
      - [`enabled`](#spec-accesslogs): boolean | `false`
      - [`disableListenerLogs`](#spec-accesslogs): boolean | `false`
@@ -467,29 +463,15 @@ The following table describes the parameters for each map you can define in the
 
 ### `PrioritizeByLocality` 
 
-Sets a default `mode` for proxies that allows them to prioritize upstream targets that are in the same geographic area. You can specify the following string values for the `mode` field:
+Sets a mode for the service that allows instances to prioritize upstream targets that are in the same network region and zone. You can specify the following string values for the `mode` field:
 
-- `failover`: If the upstream target that a service is connected to becomes unreachable, the service prioritizes a healthy upstream with the same `locality` configuration. Refer to [Route traffic to local upstreams](/consul/docs/connect/manage-traffic/route-to-local-upstreams) for additional information.
+- `failover`: If the upstream targets that a service is connected to become unreachable, the service prioritizes healthy upstream instances with matching `Locality` configuration. Refer to [Route traffic to local upstreams](/consul/docs/connect/manage-traffic/route-to-local-upstreams) for additional information.
 
 #### Values
 
 - Default: None
 - Data type: Map
 
-### `FailoverPolicy`
-
-Sets the failover policy `mode` field for all proxies. The failover policy mode defines how Consul directs traffic to failover service instances if the primary instance becomes unreachable. For example, you can direct Consul to send failover traffic to local service instances. Refer to [Failover overview](/consul/docs/connect/manage-traffic/failover) for additional information.
-
-You can specify the following string values for the `mode` field:
-
-- `default`: Envoy sends failover traffic to the first failover target with healthy instances.  
-- `order-by-locality`: Envoy prioritizes failover targets that are closer to the downstream service. Envoy deterministically orders failover targets that are the same distance from the local proxy. 
-
-#### Values
-
-- Default: None
-- Data type: Map containing the `mode` field
-
 ### `AccessLogs`
 
 Specifies [Envoy access logger](https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/observability/access_logging.html?highlight=access%20logs) configurations for all proxies in the service mesh, including gateways. This field also configures access logs on [Envoy's administration interface](https://www.envoyproxy.io/docs/envoy/latest/operations/admin.html?highlight=administration%20logs).
@@ -710,30 +692,15 @@ The following table describes the parameters for each map you can define in the
 
 ### `spec.prioritizeByLocality`
 
-Sets a default `mode` for proxies that allows them to prioritize upstream targets that are in the same geographic area. You can specify the following string values for the `mode` field:
+Sets a mode for the service that allows instances to prioritize upstream targets that are in the same network region and zone. You can specify the following string values for the `mode` field:
 
-- `failover`: If the upstream target that a service is connected to becomes unreachable, the service prioritizes a healthy upstream with the same `locality` configuration. Refer to [Route traffic to local upstreams](/consul/docs/connect/manage-traffic/route-to-local-upstreams) for additional information.
+- `failover`: If the upstream targets that a service is connected to become unreachable, the service prioritizes healthy upstream instances with matching `locality` configuration. Refer to [Route traffic to local upstreams](/consul/docs/connect/manage-traffic/route-to-local-upstreams) for additional information.
 
 #### Values
 
 - Default: None
 - Data type: Map
 
-
-### `spec.failoverPolicy`
-
-Sets the failover policy `mode` field for all proxies. The failover policy mode defines how Consul directs traffic to failover service instances if the primary instance becomes unreachable. For example, you can direct Consul to send failover traffic to local service instances. Refer to [Failover overview](/consul/docs/connect/manage-traffic/failover) for additional information.
-
-You can specify the following string values for the `mode` field:
-
-- `default`: Envoy sends failover traffic to the first failover target with healthy instances.  
-- `order-by-locality`: Envoy prioritizes failover targets that are closer to the downstream service. Envoy deterministically orders failover targets that are the same distance from the local proxy. 
-
-#### Values
-
-- Default: None
-- Data type: Map containing the `mode` field
-
 ### `spec.accessLogs`
 
 Specifies [Envoy access logger](https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/observability/access_logging.html?highlight=access%20logs) configurations for all proxies in the service mesh, including gateways. This field also configures access logs on [Envoy's administration interface](https://www.envoyproxy.io/docs/envoy/latest/operations/admin.html?highlight=administration%20logs).

@@ -205,7 +205,7 @@ BalanceInboundConnections = "exact_balance"
 Mode                      = "<mode for directing traffic>"
 RateLimits = {
   InstanceLevel = {
-    RequestsPerScond = <average number of requests allowed to the service per second>
+    RequestsPerSecond = <average number of requests allowed to the service per second>
     RequestsMaxBurst = <max number of concurrent requests allowed to the service>
     Routes = [		# Configure RequestsPerSecond and one route matching parameter for each member of the list
       {
@@ -318,7 +318,7 @@ spec:
   mode: <mode for directing traffic>
   rateLimits:
     instanceLevel:
-      requestsPerScond: <average number of requests allowed to the service per second>
+      requestsPerSecond: <average number of requests allowed to the service per second>
       requestsMaxBurst: <max number of concurrent requests allowed to the service>
       routes: 		# Configure RequestsPerSecond and one route matching parameter for each member of the list
       - pathExact: "<limits apply paths that match this value>"
@@ -409,7 +409,7 @@ spec:
 	"Mode": "<mode for directing traffic>",
   "RateLimits": {
     "InstanceLevel": {
-      "RequestsPerScond": 100,
+      "RequestsPerSecond": 100,
       "RequestsMaxBurst": 200,
       "Routes": [
         {
@@ -623,7 +623,7 @@ Map containing a set of request rate limit configurations for instances of the s
 - Default: None
 - Data type: Map
 
-### `RateLimits{}.InstanceLevel{}.RequestsPerScond`
+### `RateLimits{}.InstanceLevel{}.RequestsPerSecond`
 
 Specifies the average number of requests per second allowed to the service. If the [`RequestsMaxBurst`](#ratelimits-instancelevel-requestsmaxburst) parameter is set, the number of requests per second to the service can temporarily exceed the limit specified in the `RequestsPerSecond` up to the value specified in `RequestsMaxBurst`. Internally, this is the refill rate of the token bucket used for rate limiting.
 

@@ -39,7 +39,7 @@ The following list outlines field hierarchy, language-specific data types, and r
   - [`Datacenter`](#redirect-datacenter): string
   - [`Peer`](#redirect-peer): string
 - [`PrioritizeByLocality`](#prioritizebylocality): map <EnterpriseAlert inline/>
-   - [`Mode`](#prioritizebylocality): string | `failover`
+  - [`Mode`](#prioritizebylocality): string | `failover`
 - [`Failover`](#failover): map
   - [`Service`](#failover-service): string
   - [`ServiceSubset`](#failover-servicesubset): string
@@ -171,7 +171,7 @@ Redirect = {
 }
 
 PrioritizeByLocality = {
-   Mode = "failover"
+ Mode = "failover"
 }
 
 Failover = {                   ## requires at least one of the following: Service, ServiceSubset, Namespace, Targets, Datacenters, SamenessGroup
@@ -195,12 +195,12 @@ Failover = {                   ## requires at least one of the following: Servic
 
 LoadBalancer = {
  Policy = "random"
-  LeastRequestConfig = {                     ## requires Policy = "least_request"
+ LeastRequestConfig = {                     ## requires Policy = "least_request"
    ChoiceCount = 2
-  RingHashConfig = {                         ## requires Policy = "ring_hash"
-   MinimumRingSize = 1024
-   MaximumRingSize = 8192
  }
+ RingHashConfig = {                         ## requires Policy = "ring_hash"
+  MinimumRingSize = 1024
+  MaximumRingSize = 8192
  }
  HashPolicies = [
    {
@@ -257,7 +257,7 @@ LoadBalancer = {
   },
   "PrioritizeByLocality" : {
    "Mode":  "failover"
-},
+  },
   "Failover":{                   // requires at least one of the following": Service, ServiceSubset, Namespace, Targets, Datacenters, SamenessGroup
    "<local=subset-name>":{
      "Targets":[
@@ -552,9 +552,9 @@ Specifies the cluster with an active cluster peering connection at the redirect
 
 ### `PrioritizeByLocality` 
 
-Sets a mode for the service that allows instances to prioritize upstream targets that are in the same geographic area. You can specify the following string values for the `mode` field:
+Sets a mode for the service that allows instances to prioritize upstream targets that are in the same network region and zone. You can specify the following string values for the `mode` field:
 
-- `Failover`: If the upstream target that a service is connected to becomes unreachable, the service prioritizes a healthy upstream with the same `Locality` configuration. Refer to [Route traffic to local upstreams](/consul/docs/connect/manage-traffic/route-to-local-upstreams) for additional information.
+- `failover`: If the upstream targets that a service is connected to become unreachable, the service prioritizes healthy upstream instances with matching `Locality` configuration. Refer to [Route traffic to local upstreams](/consul/docs/connect/manage-traffic/route-to-local-upstreams) for additional information.
 
 #### Values
 
@@ -1023,11 +1023,11 @@ Specifies the cluster with an active cluster peering connection at the redirect
 - Default: None
 - Data type: String
 
-### `spec.prioritizeByLocality` 
+### `spec.prioritizeByLocality`
 
-Sets a mode for the service that allows instances to prioritize upstream targets that are in the same geographic area. You can specify the following string values for the `mode` field:
+Sets a mode for the service that allows instances to prioritize upstream targets that are in the same network region and zone. You can specify the following string values for the `mode` field:
 
-- `failover`: If the upstream target that a service is connected to becomes unreachable, the service prioritizes a healthy upstream with the same `locality` configuration. Refer to [Route traffic to local upstreams](/consul/docs/connect/manage-traffic/route-to-local-upstreams) for additional information.
+- `failover`: If the upstream targets that a service is connected to become unreachable, the service prioritizes healthy upstream instances with matching `locality` configuration. Refer to [Route traffic to local upstreams](/consul/docs/connect/manage-traffic/route-to-local-upstreams) for additional information.
 
 #### Values
 

@@ -51,4 +51,4 @@ You can configure a sameness group so that it functions as the default for failo
 
 ## Locality-aware routing
 
-By default, Consul balances traffic to all healthy upstream instances in the cluster, even if the instances are in different network regions and zones. You can configure Consul to route requests to upstreams in the same geographic region, which reduces latency and transfer costs. Refer to [Route traffic to local upstreams](/consul/docs/connect/manage-traffic/route-to-local-upstreams) for additional information.
+By default, Consul balances traffic to all healthy upstream instances in the cluster, even if the instances are in different network regions and zones. You can configure Consul to route requests to upstreams in the same region and zone, which reduces latency and transfer costs. Refer to [Route traffic to local upstreams](/consul/docs/connect/manage-traffic/route-to-local-upstreams) for additional information.
@@ -81,4 +81,4 @@ Service resolver configuration entries can also process network layer, also call
 
 ## Locality-aware routing
 
-By default, Consul balances traffic to all healthy upstream instances in the cluster, even if the instances are in different availability zones. You can configure Consul to route requests to upstreams in the same network zone, which reduces latency and transfer costs. Refer to [Route traffic to local upstreams](/consul/docs/connect/manage-traffic/route-to-local-upstreams) for additional information.
+By default, Consul balances traffic to all healthy upstream instances in the cluster, even if the instances are in different network regions and zones. You can configure Consul to route requests to upstreams in the same region and zone, which reduces latency and transfer costs. Refer to [Route traffic to local upstreams](/consul/docs/connect/manage-traffic/route-to-local-upstreams) for additional information.