hashicorp · trujillo-adam · Oct 6, 2023 · Oct 5, 2023 · Oct 5, 2023 · Oct 5, 2023
@@ -1280,6 +1280,10 @@ 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 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.    
+
 ## DNS and Domain Parameters
 
 - `dns_config` This object allows a number of sub-keys

@@ -49,6 +49,8 @@ The following list outlines field hierarchy, language-specific data types, and r
       - [`LocalPathPort`](#expose-paths): number | `0` 
       - [`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
 - [`AccessLogs`](#accesslogs): map
@@ -82,22 +84,24 @@ The following list outlines field hierarchy, language-specific data types, and r
    - [`mutualTLSMode`](#spec-mutualtlsmode): string 
    - [`meshGateway`](#spec-meshgateway): map
       - [`mode`](#spec-meshgateway): string
-   - [`expose`](#spec-expose): map
-      - [`checks`](#spec-expose-checks): boolean | `false`
-      - [`paths`](#spec-expose-paths): list
+  - [`expose`](#spec-expose): map
+     - [`checks`](#spec-expose-checks): boolean | `false`
+     - [`paths`](#spec-expose-paths): list
          - [`path`](#spec-expose-paths): string | must begin with `/` 
          - [`localPathPort`](#spec-expose-paths): number | `0` 
          - [`listenerPort`](#spec-expose-paths): number | `0` 
          - [`protocol`](#spec-expose-paths): string | `http` 
-   - [`failoverPolicy`](#spec-failoverpolicy): map
+  - [`prioritizeByLocality`](#prioritizebylocality): map | <EnterpriseAlert inline/>
+    - [`mode`](#prioritizebylocality): string | `failover` 
+  - [`failoverPolicy`](#spec-failoverpolicy): map
       - [`mode`](#spec-failoverpolicy-mode): string
-   - [`accessLogs`](#spec-accesslogs): map
-      - [`enabled`](#spec-accesslogs): boolean | `false`
-      - [`disableListenerLogs`](#spec-accesslogs): boolean | `false`
-      - [`type`](#spec-accesslogs): string | `stdout`
-      - [`path`](#spec-accesslogs): string
-      - [`jsonFormat`](#spec-accesslogs): string 
-      - [`textFormat`](#spec-accesslogs): string 
+  - [`accessLogs`](#spec-accesslogs): map
+     - [`enabled`](#spec-accesslogs): boolean | `false`
+     - [`disableListenerLogs`](#spec-accesslogs): boolean | `false`
+     - [`type`](#spec-accesslogs): string | `stdout`
+     - [`path`](#spec-accesslogs): string
+     - [`jsonFormat`](#spec-accesslogs): string 
+     - [`textFormat`](#spec-accesslogs): string 
 
 </Tab>
 
@@ -151,6 +155,9 @@ Expose {
     }
   ]
 }
+PrioritizeByLocality = {
+   Mode = "failover"
+}
 AccessLogs {
   Enabled              = < true | false >
   DisableListenerLogs  = < true | false , disables listener access logs for unrecognized traffic>
@@ -458,6 +465,17 @@ The following table describes the parameters for each map you can define in the
 | `ListenPort` | Specifies the port where the proxy listens for connections. The port must be available. If the port is unavailable, Envoy does not expose a listener for the path and the proxy registration still succeeds. | Integer | `0` |
 | `Protocol` | Specifies the protocol of the listener. You can configure one of the following values: <li>`http`</li><li>`http2`: Use with gRPC traffic</li> | String | `http` |
 
+### `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:
+
+- `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.
+
+#### 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/failover) for additional information.
@@ -690,6 +708,18 @@ The following table describes the parameters for each map you can define in the
 | `listenPort` | Specifies the port where the proxy listens for connections. The port must be available. If the port is unavailable, Envoy does not expose a listener for the path and the proxy registration still succeeds. | Integer | `0` |
 | `protocol` | Specifies the protocol of the listener. You can configure one of the following values: <li>`http`</li><li>`http2`: Use with gRPC traffic</li> | String | `http` |
 
+### `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:
+
+- `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.
+
+#### 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/failover) for additional information.