diff --git a/website/content/api-docs/discovery-chain.mdx b/website/content/api-docs/discovery-chain.mdx index bef03ac12e..ecde4b3146 100644 --- a/website/content/api-docs/discovery-chain.mdx +++ b/website/content/api-docs/discovery-chain.mdx @@ -13,13 +13,13 @@ description: The /discovery-chain endpoints are for interacting with the discove high-level proxy integration APIs may obviate the need for this API over time. The `/discovery-chain` endpoint returns the compiled [discovery -chain](/consul/docs/connect/l7-traffic/discovery-chain) for a service. +chain](/consul/docs/connect/manage-traffic/discovery-chain) for a service. This will fetch all related [configuration entries](/consul/docs/agent/config-entries) and render them into a form suitable for use by a [service mesh proxy](/consul/docs/connect/proxies) implementation. This is a key component of [L7 Traffic -Management](/consul/docs/connect/l7-traffic). +Management](/consul/docs/connect/manage-traffic). ## Read Compiled Discovery Chain @@ -98,7 +98,7 @@ The table below shows this endpoint's support for ### Sample Compilations Full documentation for the output fields is found on the [discovery chain -internals](/consul/docs/connect/l7-traffic/discovery-chain#compileddiscoverychain) +internals](/consul/docs/connect/manage-traffic/discovery-chain#compileddiscoverychain) page. #### Multi-Datacenter Failover diff --git a/website/content/docs/agent/config/config-files.mdx b/website/content/docs/agent/config/config-files.mdx index f2a4aad6ac..869d6f990b 100644 --- a/website/content/docs/agent/config/config-files.mdx +++ b/website/content/docs/agent/config/config-files.mdx @@ -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` : 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. + ## DNS and Domain Parameters - `dns_config` This object allows a number of sub-keys diff --git a/website/content/docs/connect/cluster-peering/usage/create-sameness-groups.mdx b/website/content/docs/connect/cluster-peering/usage/create-sameness-groups.mdx index 1afae3a9c9..2797ac53a3 100644 --- a/website/content/docs/connect/cluster-peering/usage/create-sameness-groups.mdx +++ b/website/content/docs/connect/cluster-peering/usage/create-sameness-groups.mdx @@ -6,7 +6,7 @@ description: |- # Create sameness groups -This topic describes how to designate groups of services as functionally identical in your network. Sameness groups are the preferred failover strategy for deployments with cluster peering connections. For more information about sameness groups and failover, refer to [Failover overview](/consul/docs/connect/failover). +This topic describes how to designate groups of services as functionally identical in your network. Sameness groups are the preferred failover strategy for deployments with cluster peering connections. For more information about sameness groups and failover, refer to [Failover overview](/consul/docs/connect/manage-traffic/failover). @@ -304,4 +304,4 @@ After creating a sameness group, you can use them with static Consul DNS lookups - [Static Consul DNS lookups](/consul/docs/services/discovery/dns-static-lookups) - [Dynamic Consul DNS lookups](/consul/docs/services/discovery/dns-dynamic-lookups) -- [Failover overview](/consul/docs/connect/failover) +- [Failover overview](/consul/docs/connect/manage-traffic/failover) diff --git a/website/content/docs/connect/cluster-peering/usage/peering-traffic-management.mdx b/website/content/docs/connect/cluster-peering/usage/peering-traffic-management.mdx index 240b56dc97..63942e5bde 100644 --- a/website/content/docs/connect/cluster-peering/usage/peering-traffic-management.mdx +++ b/website/content/docs/connect/cluster-peering/usage/peering-traffic-management.mdx @@ -13,7 +13,7 @@ For Kubernetes-specific guidance for managing L7 traffic with cluster peering, r ## Service resolvers for redirects and failover -When you use cluster peering to connect datacenters through their admin partitions, you can use [dynamic traffic management](/consul/docs/connect/l7-traffic) to configure your service mesh so that services automatically forward traffic to services hosted on peer clusters. +When you use cluster peering to connect datacenters through their admin partitions, you can use [dynamic traffic management](/consul/docs/connect/manage-traffic) to configure your service mesh so that services automatically forward traffic to services hosted on peer clusters. However, the `service-splitter` and `service-router` configuration entry kinds do not natively support directly targeting a service instance hosted on a peer. Before you can split or route traffic to a service on a peer, you must define the service hosted on the peer as an upstream service by configuring a failover in the `service-resolver` configuration entry. Then, you can set up a redirect in a second service resolver to interact with the peer service by name. diff --git a/website/content/docs/connect/config-entries/ingress-gateway.mdx b/website/content/docs/connect/config-entries/ingress-gateway.mdx index 5072560358..7b5eb23e17 100644 --- a/website/content/docs/connect/config-entries/ingress-gateway.mdx +++ b/website/content/docs/connect/config-entries/ingress-gateway.mdx @@ -723,7 +723,7 @@ Specifies a list of services that the listener exposes to services outside the m Specifies the name of a service to expose to the listener. You can specify services in the following ways: - Provide the name of a service registered in the Consul catalog. -- Provide the name of a service defined in other configuration entries. Refer to [Service Mesh Traffic Management Overview](/consul/docs/connect/l7-traffic) for additional information. +- Provide the name of a service defined in other configuration entries. Refer to [Service Mesh Traffic Management Overview](/consul/docs/connect/manage-traffic) for additional information. - Provide a `*` wildcard to expose all services in the datacenter. Wild cards are not supported for listeners configured for TCP. Refer to [`Listeners[].Protocol`](#listeners-protocol) for additional information. #### Values @@ -1258,7 +1258,7 @@ Specifies a list of services that the listener exposes to services outside the m Specifies the name of a service to expose to the listener. You can specify services in the following ways: - Provide the name of a service registered in the Consul catalog. -- Provide the name of a service defined in other configuration entries. Refer to [Service Mesh Traffic Management Overview](/consul/docs/connect/l7-traffic) for additional information. Refer to [HTTP listener with path-based routes](#http-listener-with-path-based-routes) for an example. +- Provide the name of a service defined in other configuration entries. Refer to [Service Mesh Traffic Management Overview](/consul/docs/connect/manage-traffic) for additional information. Refer to [HTTP listener with path-based routes](#http-listener-with-path-based-routes) for an example. - Provide a `*` wildcard to expose all services in the datacenter. Wild cards are not supported for listeners configured for TCP. Refer to [`spec.listeners.protocol`](#spec-listeners-protocol) for additional information. #### Values diff --git a/website/content/docs/connect/config-entries/proxy-defaults.mdx b/website/content/docs/connect/config-entries/proxy-defaults.mdx index 406bda83f3..31e436724b 100644 --- a/website/content/docs/connect/config-entries/proxy-defaults.mdx +++ b/website/content/docs/connect/config-entries/proxy-defaults.mdx @@ -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 | + - [`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 | + - [`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 @@ -151,6 +155,9 @@ Expose { } ] } +PrioritizeByLocality = { + Mode = "failover" +} AccessLogs { Enabled = < true | false > DisableListenerLogs = < true | false , disables listener access logs for unrecognized traffic> @@ -458,9 +465,20 @@ 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:
  • `http`
  • `http2`: Use with gRPC traffic
    • | 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. +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: @@ -690,9 +708,21 @@ 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:
  • `http`
  • `http2`: Use with gRPC traffic
    • | 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. +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: diff --git a/website/content/docs/connect/config-entries/service-defaults.mdx b/website/content/docs/connect/config-entries/service-defaults.mdx index caf1aed454..76a1d1af56 100644 --- a/website/content/docs/connect/config-entries/service-defaults.mdx +++ b/website/content/docs/connect/config-entries/service-defaults.mdx @@ -1,11 +1,11 @@ --- layout: docs -page_title: Service Defaults Configuration Reference +page_title: Service defaults configuration entry reference description: -> Use the service-defaults configuration entry to set default configurations for services, such as upstreams, protocols, and namespaces. Learn how to configure service-defaults. --- -# Service Defaults Configuration Reference +# Service defaults configuration reference This topic describes how to configure service defaults configuration entries. The service defaults configuration entry contains common configuration settings for service mesh services, such as upstreams and gateways. Refer to [Define service defaults](/consul/docs/services/usage/define-services#define-service-defaults) for usage information. @@ -23,7 +23,17 @@ The following list outlines field hierarchy, language-specific data types, requi - [`Meta`](#meta): map - [`Protocol`](#protocol): string | `tcp` - [`BalanceInboundConnections`](#balanceinboundconnections): string -- [`Mode`](#mode): string +- [`Mode`](#mode): string +- [`RateLimits`](#ratelimits): map + - [`InstanceLevel`](#ratelimits-instancelevel): map + - [`RequestsPerSecond`](#ratelimits-instancelevel-requestspersecond): number + - [`RequestsMaxBurst`](#ratelimits-instancelevel-requestsmaxburst): number + - [`Routes`](#ratelimits-instancelevel-routes): list maps + - [`PathExact`](#ratelimits-instancelevel-routes): string + - [`PathPrefix`](#ratelimits-instancelevel-routes): string + - [`PathRegex`](#ratelimits-instancelevel-routes): string + - [`RequestsPerSecond`](#ratelimits-instancelevel-routes): number | required + - [`RequestsMaxBurst`](#ratelimits-instancelevel-routes): number - [`UpstreamConfig`](#upstreamconfig): map - [`Overrides`](#upstreamconfig-overrides): map - [`Name`](#upstreamconfig-overrides-name): string @@ -98,7 +108,17 @@ The following list outlines field hierarchy, language-specific data types, requi - [`spec`](#spec): map - [`protocol`](#protocol): string | `tcp` - [`balanceInboundConnections`](#balanceinboundconnections): string - - [`mode`](#mode): string + - [`mode`](#mode): string + - [`rateLimits`](#spec-ratelimits): map + - [`instanceLevel`](#spec-ratelimits-instancelevel): map + - [`requestsPerSecond`](#spec-ratelimits-instancelevel-requestspersecond): number + - [`requestsMaxBurst`](#spec-ratelimits-instancelevel-requestsmaxburst): number + - [`routes`](#spec-ratelimits-instancelevel-routes): list maps + - [`pathExact`](#spec-ratelimits-instancelevel-routes): string + - [`pathPrefix`](#spec-ratelimits-instancelevel-routes): string + - [`pathRegex`](#spec-ratelimits-instancelevel-routes): string + - [`requestsPerSecond`](#spec-ratelimits-instancelevel-routes): number | required + - [`requestsMaxBurst`](#spec-ratelimits-instancelevel-routes): number - [`upstreamConfig`](#upstreamconfig): map - [`overrides`](#upstreamconfig-overrides): list - [`name`](#upstreamconfig-overrides-name): string @@ -183,6 +203,20 @@ Meta = { Protocol = "tcp" BalanceInboundConnections = "exact_balance" Mode = "" +RateLimits = { + InstanceLevel = { + RequestsPerScond = + RequestsMaxBurst = + Routes = [ # Configure RequestsPerSecond and one route matching parameter for each member of the list + { + PathExact = "" + PathPrefix = "" + PathRegex = "" + RequestsPerSecond = + RequestMaxBurst = + } + ] +} UpstreamConfig = { Overrides = { Name = "" @@ -282,6 +316,16 @@ spec: protocol: tcp balanceInboundConnections: exact_balance mode: + rateLimits: + instanceLevel: + requestsPerScond: + requestsMaxBurst: + routes: # Configure RequestsPerSecond and one route matching parameter for each member of the list + - pathExact: "" + pathPrefix: "" + pathRegex: "" + requestsPerSecond: + requestMaxBurst: upstreamConfig: overrides: - name: @@ -363,6 +407,21 @@ spec: "Protocol": "tcp", "BalanceInboundConnections": "exact_balance", "Mode": "", + "RateLimits": { + "InstanceLevel": { + "RequestsPerScond": 100, + "RequestsMaxBurst": 200, + "Routes": [ + { + "PathExact": "", + "PathPrefix": "", + "PathRegex": "", + "RequestsPerSecond": 50, + "RequestMaxBurst": 100 + } + ] + } + }, "UpstreamConfig": { "Overrides": [{ "Name": "", @@ -546,6 +605,66 @@ Specifies a mode for how the service directs inbound and outbound traffic. - `direct`: The proxy's listeners must be dialed directly by the local application and other proxies. - `transparent`: The service captures inbound and outbound traffic and redirects it through the proxy. The mode does not enable the traffic redirection. It instructs Consul to configure Envoy as if traffic is already being redirected. +### `RateLimits` + +Map containing an instance-level configuration for limiting the service's traffic rate. + +#### Values + +- Default: None +- Data type: Map + +### `RateLimits{}.InstanceLevel` + +Map containing a set of request rate limit configurations for instances of the service. + +#### Values + +- Default: None +- Data type: Map + +### `RateLimits{}.InstanceLevel{}.RequestsPerScond` + +Specifies the average number of requests per second allowed to the service. Consul allows requests to the service when the average number of requests per second exceeds this value, but it temporarily lowers the speed of the transactions. You may also specify the [`RequestsMaxBurst`](#ratelimits-instancelevel-requestsmaxburst) parameter. The number of requests per second to the service can exceed the limit specified in the `RequestsPerSecond` parameter, but not the `RequestsMaxBurst` parameter. + +#### Values + +- Default: None +- Data type: Integer + +### `RateLimits{}.InstanceLevel{}.RequestsMaxBurst` + +Specifies the maximum number of concurrent requests momentarily allowed to the service. When the limit is reached, Consul blocks additional requests. You must specify a value equal to or greater than the [`RequestsPerSecond`](#ratelimits-instancelevel-requestspersecond) parameter. If unspecified, this parameter defaults to `RequestsPerSecond`. + +#### Values + +- Default: None +- Data type: Integer + +### `RateLimits{}.InstanceLevel{}.Routes` + +Specifies a list of rate limiting configurations to apply to specific routes to the service. Each member of the `Routes` list must configure the `RequestsPerSecond` parameter and one of the following route-matching parameters: + +- `PathExact` +- `PathPrefix` +- `PathRegex` + +Refer to [Examples](#enable-request-rate-limit-on-a-prefixed-path) for example configurations. + +#### Values + +- Default: None +- Data type: Map + +The following table describes the parameters you can specify in the `Routes` map: + +| Parameter | Description | Data type | Default | +| --- | --- | --- | --- | +| `PathExact` | Specifies the exact path to match on the request path. When using this field, do not configure `PathPrefix` or `PathRegex` in the same `Routes` map. | String | None | +| `PathPrefix` | Specifies the path prefix to match on the request path. When using this field, do not configure `PathExact` or `PathRegex` in the same `Routes` map. | String | None | +| `PathRegex` | Specifies a regular expression to match on the request path. When using this field, do not configure `PathExact` or `PathPrefix` in the same `Routes` map. The syntax is proxy-specific. When [using Envoy](/consul/docs/connect/proxies/envoy), refer to [the documentation for Envoy v1.11.2 or newer](https://github.com/google/re2/wiki/Syntax) or [the documentation for Envoy v1.11.1 or older](https://en.cppreference.com/w/cpp/regex/ecmascript), depending on the version of Envoy you use. | String | None | +| `RequestsPerSecond` | Specifies the average number of requests per second allowed to the service. Consul allows requests to the service when the average number of requests per second exceeds this value, but it temporarily lowers the speed of the transactions. Overrides the [`RequestsPerSecond`](#ratelimits-instancelevel-requestspersecond) parameter specified for the service. | Integer | None | +| `RequestsMaxBurst` | Specifies the maximum number of concurrent requests temporarily allowed to the service. When the limit is reached, Consul blocks additional requests. You must specify a value equal to or greater than the `Routes.RequestsPerSecond` parameter. Overrides the [`RequestsMaxBurst`](#ratelimits-instancelevel-requestsmaxburst) parameter specified for the service. | Integer | None | ### `UpstreamConfig` @@ -598,7 +717,7 @@ Specifies the peer name of the upstream service that the configuration applies t ### `UpstreamConfig.Overrides[].Protocol` Specifies the protocol to use for requests to the upstream listener. -We recommend configuring the protocol in the main [`Protocol`](#protocol) field of the configuration entry so that you can leverage [L7 features](/consul/docs/connect/l7-traffic). Setting the protocol in an upstream configuration limits L7 management functionality. +We recommend configuring the protocol in the main [`Protocol`](#protocol) field of the configuration entry so that you can leverage [L7 features](/consul/docs/connect/manage-traffic). Setting the protocol in an upstream configuration limits L7 management functionality. #### Values @@ -610,7 +729,7 @@ We recommend configuring the protocol in the main [`Protocol`](#protocol) field Specifies how long in milliseconds that the service should attempt to establish an upstream connection before timing out. -We recommend configuring the upstream timeout in the [`connection_timeout`](/consul/docs/connect/config-entries/service-resolver#connecttimeout) field of the `service-resolver` configuration entry for the upstream destination service. Doing so enables you to leverage [L7 features](/consul/docs/connect/l7-traffic). Configuring the timeout in the `service-defaults` upstream configuration limits L7 management functionality. +We recommend configuring the upstream timeout in the [`connection_timeout`](/consul/docs/connect/config-entries/service-resolver#connecttimeout) field of the `service-resolver` configuration entry for the upstream destination service. Doing so enables you to leverage [L7 features](/consul/docs/connect/manage-traffic). Configuring the timeout in the `service-defaults` upstream configuration limits L7 management functionality. #### Values @@ -686,7 +805,7 @@ Specifies configurations that set default upstream settings. For information abo Specifies default protocol for upstream listeners. -We recommend configuring the protocol in the main [`Protocol`](#protocol) field of the configuration entry so that you can leverage [L7 features](/consul/docs/connect/l7-traffic). Setting the protocol in an upstream configuration limits L7 management functionality. +We recommend configuring the protocol in the main [`Protocol`](#protocol) field of the configuration entry so that you can leverage [L7 features](/consul/docs/connect/manage-traffic). Setting the protocol in an upstream configuration limits L7 management functionality. - Default: None - Data type: String @@ -695,7 +814,7 @@ We recommend configuring the protocol in the main [`Protocol`](#protocol) field Specifies how long in milliseconds that all services should continue attempting to establish an upstream connection before timing out. -For non-Kubernetes environments, we recommend configuring the upstream timeout in the [`connection_timeout`](/consul/docs/connect/config-entries/service-resolver#connecttimeout) field of the `service-resolver` configuration entry for the upstream destination service. Doing so enables you to leverage [L7 features](/consul/docs/connect/l7-traffic). Configuring the timeout in the `service-defaults` upstream configuration limits L7 management functionality. +For non-Kubernetes environments, we recommend configuring the upstream timeout in the [`connection_timeout`](/consul/docs/connect/config-entries/service-resolver#connecttimeout) field of the `service-resolver` configuration entry for the upstream destination service. Doing so enables you to leverage [L7 features](/consul/docs/connect/manage-traffic). Configuring the timeout in the `service-defaults` upstream configuration limits L7 management functionality. - Default: `5000` - Data type: Integer @@ -952,6 +1071,67 @@ Specifies a mode for how the service directs inbound and outbound traffic. - `direct`: The proxy's listeners must be dialed directly by the local application and other proxies. - `transparent`: The service captures inbound and outbound traffic and redirects it through the proxy. The mode does not enable the traffic redirection. It instructs Consul to configure Envoy as if traffic is already being redirected. +### `spec.rateLimits` + +Map containing an instance-level configuration for limiting the service's traffic rate. + +#### Values + +- Default: None +- Data type: Map + +### `spec.rateLimits{}.instanceLevel` + +Map containing a set of request rate limit configurations for instances of the service. + +#### Values + +- Default: None +- Data type: Map + +### `spec.rateLimits{}.instanceLevel{}.requestsPerSecond` + +Specifies the average number of requests per second allowed to the service. Consul allows requests to the service when the average number of requests per second exceeds this value, but it temporarily lowers the speed of the transactions. You may also specify the [`requestsMaxBurst`](#spec-ratelimits-instancelevel-requestsmaxburst) parameter. The number of requests per second to the service can exceed the limit specified in the `requestsPerSecond` parameter, but not the `requestsMaxBurst` parameter. + +#### Values + +- Default: None +- Data type: Integer + +### `spec.rateLimits{}.instanceLevel{}.requestsMaxBurst` + +Specifies the maximum number of concurrent requests momentarily allowed to the service. When the limit is reached, Consul blocks additional requests. You must specify a value equal to or greater than the [`requestsPerSecond`](#spec-ratelimits-instancelevel-requestspersecond) parameter. If unspecified, this parameter defaults to `requestsPerSecond`. + +#### Values + +- Default: None +- Data type: Integer + +### `spec.rateLimits{}.instanceLevel{}.routes` + +Specifies a list of rate limiting configurations to apply to specific routes to the service. Each member of the `routes` list must configure the `requestsPerSecond` parameter and one of the following route-matching parameters: + +- `pathExact` +- `pathPrefix` +- `pathRegex` + +Refer to [Examples](#enable-request-rate-limit-on-a-prefixed-path) for example configurations. + +#### Values + +- Default: None +- Data type: Map + +The following table describes the parameters you can specify in the `routes` map: + +| Parameter | Description | Data type | Default | +| --- | --- | --- | --- | +| `pathExact` | Specifies the exact path to match on the request path. When using this field, do not configure `pathPrefix` or `pathRegex` in the same `routes` map. | String | None | +| `pathPrefix` | Specifies the path prefix to match on the request path. When using this field, do not configure `pathExact` or `pathRegex` in the same `routes` map. | String | None | +| `pathRegex` | Specifies a regular expression to match on the request path. When using this field, do not configure `pathExact` or `pathPrefix` in the same `routes` map. The syntax is proxy-specific. When [using Envoy](/consul/docs/connect/proxies/envoy), refer to [the documentation for Envoy v1.11.2 or newer](https://github.com/google/re2/wiki/Syntax) or [the documentation for Envoy v1.11.1 or older](https://en.cppreference.com/w/cpp/regex/ecmascript), depending on the version of Envoy you use. | String | None | +| `requestsPerSecond` | Specifies the average number of requests per second allowed to the service. Consul allows requests to the service when the average number of requests per second exceeds this value, but it temporarily lowers the speed of the transactions. Overrides the [`requestsPerSecond`](#spec-ratelimits-instancelevel-requestspersecond) parameter specified for the service. | Integer | None | +| `requestsMaxBurst` | Specifies the maximum number of concurrent requests temporarily allowed to the service. When the limit is reached, Consul blocks additional requests. You must specify a value equal to or greater than the `routes.requestsPerSecond` parameter. Overrides the [`requestsMaxBurst`](#spec-ratelimits-instancelevel-requestsmaxburst) parameter specified for the service. | Integer | None | + ### `spec.upstreamConfig` Specifies a map that controls default upstream connection settings and custom overrides for individual upstream services. If your network contains federated datacenters, individual upstream configurations apply to all pairs of source and upstream destination services in the network. @@ -1001,7 +1181,7 @@ Specifies the peer name of the upstream service that the configuration applies t ### `spec.upstreamConfig.overrides[].protocol` -Specifies the protocol to use for requests to the upstream listener. We recommend configuring the protocol in the main [`protocol`](#protocol) field of the configuration entry so that you can leverage [L7 features](/consul/docs/connect/l7-traffic). Setting the protocol in an upstream configuration limits L7 management functionality. +Specifies the protocol to use for requests to the upstream listener. We recommend configuring the protocol in the main [`protocol`](#protocol) field of the configuration entry so that you can leverage [L7 features](/consul/docs/connect/manage-traffic). Setting the protocol in an upstream configuration limits L7 management functionality. #### Values @@ -1013,7 +1193,7 @@ Specifies the protocol to use for requests to the upstream listener. We recommen Specifies how long in milliseconds that the service should attempt to establish an upstream connection before timing out. -We recommend configuring the upstream timeout in the [`connectTimeout`](/consul/docs/connect/config-entries/service-resolver#connecttimeout) field of the `ServiceResolver` CRD for the upstream destination service. Doing so enables you to leverage [L7 features](/consul/docs/connect/l7-traffic). Configuring the timeout in the `ServiceDefaults` upstream configuration limits L7 management functionality. +We recommend configuring the upstream timeout in the [`connectTimeout`](/consul/docs/connect/config-entries/service-resolver#connecttimeout) field of the `ServiceResolver` CRD for the upstream destination service. Doing so enables you to leverage [L7 features](/consul/docs/connect/manage-traffic). Configuring the timeout in the `ServiceDefaults` upstream configuration limits L7 management functionality. #### Values @@ -1082,7 +1262,7 @@ Map of configurations that set default upstream configurations for the service. ### `spec.upstreamConfig.defaults.protocol` -Specifies default protocol for upstream listeners. We recommend configuring the protocol in the main [`Protocol`](#protocol) field of the configuration entry so that you can leverage [L7 features](/consul/docs/connect/l7-traffic). Setting the protocol in an upstream configuration limits L7 management functionality. +Specifies default protocol for upstream listeners. We recommend configuring the protocol in the main [`Protocol`](#protocol) field of the configuration entry so that you can leverage [L7 features](/consul/docs/connect/manage-traffic). Setting the protocol in an upstream configuration limits L7 management functionality. #### Values @@ -1093,7 +1273,7 @@ Specifies default protocol for upstream listeners. We recommend configuring the Specifies how long in milliseconds that all services should continue attempting to establish an upstream connection before timing out. -We recommend configuring the upstream timeout in the [`connectTimeout`](/consul/docs/connect/config-entries/service-resolver#connecttimeout) field of the `ServiceResolver` CRD for upstream destination services. Doing so enables you to leverage [L7 features](/consul/docs/connect/l7-traffic). Configuring the timeout in the `ServiceDefaults` upstream configuration limits L7 management functionality. +We recommend configuring the upstream timeout in the [`connectTimeout`](/consul/docs/connect/config-entries/service-resolver#connecttimeout) field of the `ServiceResolver` CRD for upstream destination services. Doing so enables you to leverage [L7 features](/consul/docs/connect/manage-traffic). Configuring the timeout in the `ServiceDefaults` upstream configuration limits L7 management functionality. #### Values @@ -1557,622 +1737,172 @@ Proxy services must be in transparent proxy mode to configure destinations. Refe - + "PathPrefix": "/login", + "RequestsPerSecond": 100, + "RequestsMaxBurst": 500 + } + ] + } + } +} +``` + \ No newline at end of file diff --git a/website/content/docs/connect/config-entries/service-resolver.mdx b/website/content/docs/connect/config-entries/service-resolver.mdx index befdd2f199..14ac35eb43 100644 --- a/website/content/docs/connect/config-entries/service-resolver.mdx +++ b/website/content/docs/connect/config-entries/service-resolver.mdx @@ -9,7 +9,7 @@ description: >- This page provides reference information for service resolver configuration entries. Configure and apply service resolvers to create named subsets of service instances and define their behavior when satisfying upstream requests. -Refer to [L7 traffic management overview](/consul/docs/connect/l7-traffic) for additional information. +Refer to [L7 traffic management overview](/consul/docs/connect/manage-traffic) for additional information. ## Configuration model @@ -38,6 +38,8 @@ The following list outlines field hierarchy, language-specific data types, and r - [`SamenessGroup`](#redirect-samenessgroup): string - [`Datacenter`](#redirect-datacenter): string - [`Peer`](#redirect-peer): string +- [`PrioritizeByLocality`](#prioritizebylocality): map + - [`Mode`](#prioritizebylocality): string | `failover` - [`Failover`](#failover): map - [`Service`](#failover-service): string - [`ServiceSubset`](#failover-servicesubset): string @@ -92,6 +94,8 @@ The following list outlines field hierarchy, language-specific data types, and r - [`samenessGroup`](#spec-redirect-samenessgroup): string - [`datacenter`](#spec-redirect-datacenter): string - [`peer`](#spec-redirect-peer): string + - [`prioritizeByLocality`](#spec-prioritizebylocality): map | + - [`mode`](#spec-prioritizebylocality): string | `failover` - [`failover`](#spec-failover): map - [`service`](#spec-failover-service): string - [`serviceSubset`](#spec-failover-servicesubset): string @@ -166,6 +170,10 @@ Redirect = { Peer = "" } +PrioritizeByLocality = { + Mode = "failover" +} + Failover = { ## requires at least one of the following: Service, ServiceSubset, Namespace, Targets, Datacenters, SamenessGroup = { Targets = [ @@ -238,7 +246,6 @@ LoadBalancer = { } }, "DefaultSubset ":"", - "Redirect":{ "Service":"", "ServiceSubset":"", @@ -248,7 +255,9 @@ LoadBalancer = { "Datacenter":"", "Peer":"" }, - + "PrioritizeByLocality" : { + "Mode": "failover" +}, "Failover":{ // requires at least one of the following": Service, ServiceSubset, Namespace, Targets, Datacenters, SamenessGroup "":{ "Targets":[ @@ -322,6 +331,8 @@ spec: partition: samenessGroup: peer: + prioritizeByLocality: + mode: failover failover: # requires at least one of the following: service, serviceSubset, namespace, targets, datacenters, samenessGroup : targets: @@ -539,6 +550,17 @@ Specifies the cluster with an active cluster peering connection at the redirect - Default: None - Data type: String +### `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: + +- `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 + ### `Failover` Specifies controls for rerouting traffic to an alternate pool of service instances if the target service fails. @@ -1001,6 +1023,17 @@ Specifies the cluster with an active cluster peering connection at the redirect - Default: None - Data type: String +### `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: + +- `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.failover` Specifies controls for rerouting traffic to an alternate pool of service instances if the target service fails. diff --git a/website/content/docs/connect/config-entries/service-router.mdx b/website/content/docs/connect/config-entries/service-router.mdx index fd3e1b04be..2888bc3a79 100644 --- a/website/content/docs/connect/config-entries/service-router.mdx +++ b/website/content/docs/connect/config-entries/service-router.mdx @@ -9,7 +9,7 @@ description: >- This page provides reference information for service router configuration entries. Service routers use L7 network information to redirect a traffic request for a service to one or more specific service instances. -Refer to [L7 traffic management overview](/consul/docs/connect/l7-traffic) for additional information. +Refer to [L7 traffic management overview](/consul/docs/connect/manage-traffic) for additional information. ## Configuration model diff --git a/website/content/docs/connect/gateways/terminating-gateway.mdx b/website/content/docs/connect/gateways/terminating-gateway.mdx index 17a926c0cd..86014850eb 100644 --- a/website/content/docs/connect/gateways/terminating-gateway.mdx +++ b/website/content/docs/connect/gateways/terminating-gateway.mdx @@ -20,7 +20,7 @@ For additional use cases and usage patterns, review the tutorial for [understanding terminating gateways](/consul/tutorials/developer-mesh/service-mesh-terminating-gateways?utm_source=docs). ~> **Known limitations:** Terminating gateways currently do not support targeting service subsets with -[L7 configuration](/consul/docs/connect/l7-traffic). They route to all instances of a service with no capabilities +[L7 configuration](/consul/docs/connect/manage-traffic). They route to all instances of a service with no capabilities for filtering by instance. ## Security Considerations diff --git a/website/content/docs/connect/l7-traffic/discovery-chain.mdx b/website/content/docs/connect/manage-traffic/discovery-chain.mdx similarity index 100% rename from website/content/docs/connect/l7-traffic/discovery-chain.mdx rename to website/content/docs/connect/manage-traffic/discovery-chain.mdx diff --git a/website/content/docs/connect/failover/index.mdx b/website/content/docs/connect/manage-traffic/failover/index.mdx similarity index 73% rename from website/content/docs/connect/failover/index.mdx rename to website/content/docs/connect/manage-traffic/failover/index.mdx index 022b6542a9..cd9a6f8f6c 100644 --- a/website/content/docs/connect/failover/index.mdx +++ b/website/content/docs/connect/manage-traffic/failover/index.mdx @@ -18,11 +18,15 @@ There are several methods for implementing failover strategies between datacente The following table compares these strategies in deployments with multiple datacenters to help you determine the best approach for your service: -| Failover Strategy | Supports WAN Federation | Supports Cluster Peering | Multi-Datacenter Failover Strength | Multi-Datacenter Usage Scenario | -| :---------------: | :---------------------: | :----------------------: | :--------------------------------- | :------------------------------ | -| `Failover` stanza | ✅ | ✅ | Enables more granular logic for failover targeting | Configuring failover for a single service or service subset, especially for testing or debugging purposes | -| Prepared query | ✅ | ❌ | Central policies that can automatically target the nearest datacenter | WAN-federated deployments where a primary datacenter is configured. | -| Sameness groups | ❌ | ✅ | Group size changes without edits to existing member configurations | Cluster peering deployments with consistently named services and namespaces | +| | `Failover` stanza | Prepared
    query | Sameness groups | +| --- | :---: | :---: | :---: | +| **Supports WAN federation** | ✅ | ✅ | ❌ | +| **Supports cluster peering** | ✅ | ❌ | ✅ | +| **Supports locality-aware routing** | ✅ | ❌ | ✅ | +| **Multi-datacenter failover strength** | ✅ | ❌ | ✅ | +| **Multi-datacenter usage scenario** | Enables more granular logic for failover targeting. | Central policies that can automatically target the nearest datacenter. | Group size changes without edits to existing member configurations. | +| **Multi-datacenter usage scenario** | Configuring failover for a single service or service subset, especially for testing or debugging purposes | WAN-federated deployments where a primary datacenter is configured. Prepared queries are not replicated over peer connections. | Cluster peering deployments with consistently named services and namespaces. | + Although cluster peering connections support the [`Failover` field of the prepared query request schema](/consul/api-docs/query#failover) when using Consul's service discovery features to [perform dynamic DNS queries](/consul/docs/services/discovery/dns-dynamic-lookups), they do not support prepared queries for service mesh failover scenarios. @@ -45,3 +49,8 @@ In networks with multiple datacenters or partitions that share a peer connection You can configure sameness groups for this type of network. Sameness groups allow you to define a group of admin partitions where identical services are deployed in identical namespaces. After you configure the sameness group, you can reference the `SamenessGroup` parameter in service resolver, exported service, and service intention configuration entries, enabling you to add or remove cluster peers from the group without making changes to every cluster peer every time. Refer to [Sameness groups usage page](/consul/docs/connect/cluster-peering/usage/create-sameness-groups) for more information. + +## 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. + diff --git a/website/content/docs/connect/l7-traffic/index.mdx b/website/content/docs/connect/manage-traffic/index.mdx similarity index 90% rename from website/content/docs/connect/l7-traffic/index.mdx rename to website/content/docs/connect/manage-traffic/index.mdx index 3fb7b392b8..a9b1bae08d 100644 --- a/website/content/docs/connect/l7-traffic/index.mdx +++ b/website/content/docs/connect/manage-traffic/index.mdx @@ -24,7 +24,7 @@ Consul uses a series of stages to discover service mesh proxy upstreams. Each st - splitting - resolution -For information about integrating service mesh proxy upstream discovery using the discovery chain, refer to [Discovery Chain for Service Mesh Traffic Management](/consul/docs/connect/l7-traffic/discovery-chain). +For information about integrating service mesh proxy upstream discovery using the discovery chain, refer to [Discovery Chain for Service Mesh Traffic Management](/consul/docs/connect/manage-traffic/discovery-chain). The Consul UI shows discovery chain stages in the **Routing** tab of the **Services** page: @@ -77,4 +77,8 @@ Apply a [service resolver configuration entry](/consul/docs/connect/config-entri If no resolver is configured for a service, Consul sends all traffic to healthy instances of the service that have the same name in the current datacenter or specified namespace and ends the discovery chain. -Service resolver configuration entries can also process network layer, also called level 4 (L4), traffic. As a result, you can implement service resolvers for services that communicate over `tcp` and other non-HTTP protocols. \ No newline at end of file +Service resolver configuration entries can also process network layer, also called level 4 (L4), traffic. As a result, you can implement service resolvers for services that communicate over `tcp` and other non-HTTP protocols. + +## 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/traffic-management/route-to-local-upstreams) for additional information. diff --git a/website/content/docs/connect/manage-traffic/limit-request-rates.mdx b/website/content/docs/connect/manage-traffic/limit-request-rates.mdx new file mode 100644 index 0000000000..d9324dbaa9 --- /dev/null +++ b/website/content/docs/connect/manage-traffic/limit-request-rates.mdx @@ -0,0 +1,76 @@ +--- +layout: docs +page_title: Limit request rates to services in the mesh +description: Learn how to limit the rate of requests to services in a Consul service mesh. Rate limits on requests improves network resilience and availability +--- + +# Limit request rates to services in the mesh + +This topic describes how to configure Consul to limit the request rate to services in the mesh. + +## Introduction + +Consul allows you to configure settings to limit the rate of HTTP requests a service receives from sources in the mesh. Limiting request rates is one strategy for building a resilient and highly-available network. + +Consul applies rate limits per service instance. As an example, if you specify a rate limit of 100 requests per second (RPS) for a service and five instances of the service are available, the service accepts a total of 500 RPS, which equals 100 RPS per instance. + +You can limit request rates for all traffic to a service, as well as set rate limits for specific URL paths on a service. When multiple rate limits are configured on a service, Consul applies the limit configured for the first matching path. As a result, the maximum RPS for a service is equal to the number of service instances deployed for a service multiplied by either the rate limit configured for that service or the rate limit for the path. + +## Requirements + +Consul v1.17.0 or later + +## Limit request rates to a service on all paths + +Specify request rate limits in the service defaults configuration entry. Create or edit the existing service defaults configuration entry for your service and specify the following fields: + + + + +1. `RateLimits.InstanceLevel.RequestPerSecond`: Set an average number of requests per second that Consul should allow to the service. The number of requests may momentarily exceed this value up to the value specified in the `RequestsMaxBurst` parameter, but Consul temporarily lowers the speed of the transactions. +1. `RateLimits.InstanceLevel.RequestsMaxBurst`: Set the maximum number of concurrent requests that Consul momentarily allows to the service. Consul blocks any additional requests over this limit. + + + + +1. `spec.rateLimits.instanceLevel.requestPerSecond`: Set an average number of requests per second that Consul should allow to the service. The number of requests may momentarily exceed this value up to the value specified in the `requestsMaxBurst` parameter, but Consul temporarily lowers the speed of the transactions. +1. `spec.rateLimits.instanceLevel.requestsMaxBurst`: Set the maximum number of concurrent requests that Consul momentarily allows to the service. Consul blocks any additional requests over this limit. + + + + +Refer to the [service defaults configuration entry reference](/consul/docs/connect/config-entries/service-defaults) for additional specifications and example configurations. + +## Specify request rate limits for specific paths + +Specify request rate limits in the service defaults configuration entry. Create or edit the existing service defaults configuration entry for your service and configure the following parameters: + + + + +1. Add a `RateLimits.InstanceLevel.Routes` block to the configuration entry. The block contains the limits and matching criteria for determining which paths to set limits on. +1. In the `Routes` block, configure one of the following match criteria to determine which path to set the limits on: + - `PathExact`: Specifies the exact path to match on the request path. + - `PathPrefix`: Specifies the path prefix to match on the request path. + - `PathRegex`: Specifies a regular expression to match on the request path. +1. Configure the limits you want to enforce in the `Routes` block as well. You can configure the following parameters: + - `RequestsPerSecond`: Set an average number of requests per second that Consul should allow to the service through the matching path. The number of requests may momentarily exceed this value up to the value specified in the `RequestsMaxBurst` parameter, but Consul temporarily lowers the speed of the transactions. This configuration overrides the value specified in `RateLimits.InstanceLevel.RequestPerSecond` field of the configuration entry. + - `RequestsMaxBurst`: Set the maximum number of concurrent requests that Consul momentarily allows to the service through the matching path. Consul blocks any additional requests over this limit. This configuration overrides the value specified in `RateLimits.InstanceLevel.RequestsMaxBurst` field of the configuration entry. + + + + +1. Add a `spec.rateLimits.instanceLevel.routes` block to the configuration entry. The block contains the limits and matching criteria for determining which paths to set limits on. +1. In the `routes` block, configure one of the following match criteria for enabling Consul to determine which path to set the limits on: + - `pathExact`: Specifies the exact path to match on the request path. When using this field. + - `pathPrefix`: Specifies the path prefix to match on the request path. + - `pathRegex`: Specifies a regular expression to match on the request path. +1. Configure the limits you want to enforce in the `routes` block as well. You can configure the following parameters: + - `requestsPerSecond`: Set an average number of requests per second that Consul should allow to the service through the matching path. The number of requests may momentarily exceed this value up to the value specified in the `requestsMaxBurst` parameter, but Consul temporarily lowers the speed of the transactions. This configuration overrides the value specified in `spec.rateLimits.instanceLevel.requestPerSecond` field of the CRD. + - `requestsMaxBurst`: Set the maximum number of concurrent requests that Consul momentarily allows to the service through the matching path. Consul blocks any additional requests over this limit. This configuration overrides the value specified in `spec.rateLimits.instanceLevel.requestsMaxBurst` field of the CRD. + + + + +Refer to the [service defaults configuration entry reference](/consul/docs/connect/config-entries/service-defaults) for additional specifications and example configurations. + diff --git a/website/content/docs/connect/manage-traffic/route-to-local-upstreams.mdx b/website/content/docs/connect/manage-traffic/route-to-local-upstreams.mdx new file mode 100644 index 0000000000..afe68369de --- /dev/null +++ b/website/content/docs/connect/manage-traffic/route-to-local-upstreams.mdx @@ -0,0 +1,113 @@ +--- +layout: docs +page_title: Route traffic to local upstreams +description: Learn how to configure Consul to route traffic to upstreams in the same region and zone as the downstream service. Routing traffic based on locality can reduce latency and cost. +--- + +# Route traffic to local upstreams + +This topic describes how to configure Consul to prioritize upstream services that are in the same region and zone as the downstream service. You should only follow these instructions when every service within a zone has at least enough capacity to handle requests from downstream services within the same zone. + + This feature is available in Consul Enterprise. + +## Introduction + +By default, Consul balances traffic to all healthy upstream instances in the cluster, even if the instances are in different network zones. You can specify the cloud service provider (CSP) locale for Consul server agents and services registered to the service mesh, which enables several benefits: + +- Consul prioritizes the nearest upstream when routing traffic through the mesh. +- When a service instance in the same partition becomes unhealthy, Consul prioritizes failing over to upstream services that are in the same region as the downstream service. Refer to [Failover](/consul/docs/connect/traffic-management/failover) for additional information about failover strategies in Consul. + +When properly implemented, routing traffic to local upstreams can reduce latency and transfer costs associated with sending requests to other regions. + +### Workflow + +For networks deployed to virtual machines, complete the following steps to route traffic to local upstream services: + +1. Specify the region and zone for your Consul client agents. +1. It is not required, but you can specify the region and zone for your services. Skip this step to allow services to inherit the region and zone configured for the Consul client that the services are registered with. +1. Enable service mesh proxies to route traffic locally within the partition. +1. Start service mesh proxies. + +For Kubernetes-orchestrated networks, Consul automatically populates geographic information about service instances using the `topology.kubernetes.io/region` and `topology.kubernetes.io/zone` annotations from the Kubernetes nodes. As a result, you do not need to specify the regions and zones unless you are implementing a custom Kuberenetes deployment. + +## Specify the locality of your Consul agents + +The `locality` configuration on a Consul client applies to all services registered to the client. + +1. Configure the `locality` block in your Consul client agent configuration files. The `locality` block is a map containing the `region` and `zone` parameters. + + The parameters should match the values for regions and zones defined in your network. Refer to [`locality`](/consul/docs/agent/config/config-files#locality) in the agent configuration reference for additional information. + +1. Start or restart the agent to apply the configuration. Refer to [Starting a Consul agent](/consul/docs/agent#starting-the-consul-agent) for instructions. + +In the following example, the agent is running in the `us-west-1` region and `us-west-1a` zone on AWS: + +```hcl +locality = { + region = "us-west-1" + zone = "us-west-1a" +} +``` + +## Specify the localities of your service instances + +You may only need to configure service localities in service mesh deployments that use [Consul dataplane](/consul/docs/connect/dataplane). This step is optional for networks deployed to virtual machines, which you should allow services to inherit the localities of the Consul agent that they are registered with. + +1. Configure the `locality` block in your service definition. The `locality` block is a map containing the `region` and `zone` parameters. When you start a proxy for the service, Consul passes the locale to the proxy so that it can route traffic accordingly. + + The parameters should match the values for regions and zones defined in your network. Refer to [`locality`](/consul/docs/services/configuration/services-configuration-reference#locality) in the services configuration reference for additional information. + +1. Verify that your service is also configured with a proxy. Refer to [Define service mesh proxy](/consul/docs/connect/proxies/deploy-sidecar-services#define-service-mesh-proxy) for additional information. +Register or re-register the service to apply the configuration. Refer to [Register services and health checks](/consul/docs/services/usage/register-services-checks) for instructions. + +In the following example, the `web` service is available in the `us-west-1` region and `us-west-1a` zone on AWS: + +```hcl +service { + id = "web" + locality = { + region = "us-west-1" + zone = "us-west-1a" + } +} +``` + +## Enable service mesh proxies to route traffic locally + +You can configure the default routing behavior for all proxies in the mesh as well as configure the routing behavior for specific services. + +### Configure default routing behavior + +1. Configure the `PrioritizeByLocality` block in the proxy defaults configuration entry and specify the `failover` mode. This configuration enables proxies in the mesh to use the region and zone defined in the service configuration to route traffic. Refer to [`PrioritizeByLocality`](/consul/docs/connect/config-entries/proxy-defaults#prioritizebylocality) in the proxy defaults reference for details about the configuration. +1. Apply the configuration by either calling the [`/config` HTTP API endpoint](/consul/api-docs/config) or running the [`consul config write` CLI command](/consul/commands/config/write). + + The following example writes a proxy defaults configuration entry from a local HCL file using the CLI: + + ```shell-session + $ consul config write proxy-defaults.hcl + ``` +### Configure routing behavior for individual service + +1. Create a service resolver configuration entry and specify the following fields: + - `Name`: Specify the name of the service that the routing behavior defined in the configuration entry applies to. + - `PrioritizeByLocality`: This block enables proxies in the mesh to use the region and zone defined in the service configuration to route traffic. Set the `mode` inside the block to - `failover`. Refer to [`PrioritizeByLocality`](/consul/docs/connect/config-entries/service-resolver#prioritzebylocality) in the service resolver reference for details about the configuration. +1. Apply the configuration by either calling the [`/config` HTTP API endpoint](/consul/api-docs/config) or running the [`consul config write` CLI command](/consul/commands/config/write). + The following example writes a proxy defaults configuration entry from a local HCL file using the CLI: + + ```shell-session + $ consul config write web-resolver.hcl + ``` + +## Start the proxies in your datacenter + +Envoy requires a bootstrap configuration file before it can start. Use the [`consul connect envoy` command](/consul/commands/connect/envoy) to create the Envoy bootstrap configuration and start the sidecar proxy service. Specify the ID of the sidecar proxy you want to start with the `-sidecar-for` option. + +The following example command starts an Envoy proxy for the `web` proxy service: + +```shell-session +$ consul connect envoy -sidecar-for=web +``` + +For details about operating an Envoy proxy in Consul, refer to the [Envoy proxy reference](/consul/docs/connect/proxies/envoy). + +Use the `/agent/service/register` API endpoint to register sidecars independently from their application services. You must include the `locality` configuration in the payload. Refer to [Register Service](/consul/api-docs/agent/service#register-service) in the API documentation for additional information. diff --git a/website/content/docs/connect/proxies/envoy.mdx b/website/content/docs/connect/proxies/envoy.mdx index f82a996d3a..1b9f270320 100644 --- a/website/content/docs/connect/proxies/envoy.mdx +++ b/website/content/docs/connect/proxies/envoy.mdx @@ -24,7 +24,7 @@ Consul can configure Envoy sidecars to proxy traffic over the following protocol On Consul 1.5.0 and older, Envoy proxies can only proxy TCP traffic at L4. -You can configure some [L7 features](/consul/docs/connect/l7-traffic) in [configuration entries](/consul/docs/agent/config-entries). You can add [custom Envoy configurations](#advanced-configuration) to the [proxy service definition](/consul/docs/connect/proxies/proxy-config-reference), which enables you to leverage Envoy features that are not exposed through configuration entries. You can also use the [Consul Envoy extensions](/consul/docs/connect/proxies/envoy-extensions) to implement Envoy features. +You can configure some [L7 features](/consul/docs/connect/manage-traffic) in [configuration entries](/consul/docs/agent/config-entries). You can add [custom Envoy configurations](#advanced-configuration) to the [proxy service definition](/consul/docs/connect/proxies/proxy-config-reference), which enables you to leverage Envoy features that are not exposed through configuration entries. You can also use the [Consul Envoy extensions](/consul/docs/connect/proxies/envoy-extensions) to implement Envoy features. ~> **Note:** When using Envoy with Consul and not using the [`consul connect envoy` command](/consul/commands/connect/envoy) Envoy must be run with the `--max-obj-name-len` option set to `256` or greater for Envoy versions prior to 1.11.0. @@ -322,7 +322,7 @@ defaults that are inherited by all services. [`service-defaults`](/consul/docs/connect/config-entries/service-defaults) config entry for the service. Configuring it in a proxy config will not fully enable some [L7 - features](/consul/docs/connect/l7-traffic). + features](/consul/docs/connect/manage-traffic). It is supported here for backwards compatibility with Consul versions prior to 1.6.0. - `bind_address` - Override the address Envoy's public listener binds to. By @@ -372,7 +372,7 @@ definition](/consul/docs/connect/proxies/proxy-config-reference) or [`service-defaults`](/consul/docs/connect/config-entries/service-defaults) config entry for the upstream destination service. Configuring it in a proxy upstream config will not fully enable some [L7 - features](/consul/docs/connect/l7-traffic). + features](/consul/docs/connect/manage-traffic). It is supported here for backwards compatibility with Consul versions prior to 1.6.0. - `connect_timeout_ms` - The number of milliseconds to allow when making upstream diff --git a/website/content/docs/connect/proxies/index.mdx b/website/content/docs/connect/proxies/index.mdx index a5c67da46f..839a24a49f 100644 --- a/website/content/docs/connect/proxies/index.mdx +++ b/website/content/docs/connect/proxies/index.mdx @@ -29,6 +29,16 @@ You can configure service mesh proxies to operate as gateway services, which all Refer to [Gateways overview](/consul/docs/connect/gateways) for additional information. +### Dynamic traffic control + +You can configure proxies to dynamically redirect or split traffic to implement a failover strategy, test new features, and roll out new versions of your applications. You can apply a combination of configurations to enable complex scenarios, such as failing over to the geographically nearest service or to services in different network areas that you have designated as being functionally identical. + +Refer to the following topics for additional information: + +- [Service mesh traffic management overview](/consul/docs/connect/manage-traffic) +- [Failover overview](/consul/docs/connect/manage-traffic/failover) + + ## Supported proxies Consul has first-class support for Envoy proxies, which is a highly configurable open source edge service proxy. Consul configures Envoy by optionally exposing a gRPC service on the local agent that serves Envoy's xDS configuration API. Refer to the following documentation for additional information: diff --git a/website/content/docs/connect/proxies/integrate.mdx b/website/content/docs/connect/proxies/integrate.mdx index d00e01d1bd..80708badff 100644 --- a/website/content/docs/connect/proxies/integrate.mdx +++ b/website/content/docs/connect/proxies/integrate.mdx @@ -139,7 +139,7 @@ If you are only implementing L4 support in your proxy, set the fetching the discovery chain so that L7 features, such as HTTP routing rules, are not returned. -For each [target](/consul/docs/connect/l7-traffic/discovery-chain#targets) in the resulting +For each [target](/consul/docs/connect/manage-traffic/discovery-chain#targets) in the resulting discovery chain, a list of healthy, mesh-capable endpoints may be fetched from the [`/v1/health/connect/:service_id`] API endpoint as described in the [Service Discovery](#service-discovery) section. @@ -227,6 +227,6 @@ ID for the name specified in `-sidecar-for` flag. [`api` package]: https://github.com/hashicorp/consul/tree/main/api [`consul/connect/proxy/config.go`]: https://github.com/hashicorp/consul/blob/v1.8.3/connect/proxy/config.go#L187 [`consul/connect/tls.go`]: https://github.com/hashicorp/consul/blob/v1.8.3/connect/tls.go#L232-L237 -[discovery chain]: /consul/docs/connect/l7-traffic/discovery-chain +[discovery chain]: /consul/docs/connect/manage-traffic/discovery-chain [`usecache`]: https://github.com/hashicorp/consul/blob/v1.8.3/api/api.go#L99-L102 [protocol]: /consul/docs/connect/config-entries/service-defaults#protocol diff --git a/website/content/docs/internals/index.mdx b/website/content/docs/internals/index.mdx index 20b3c80571..c4a1d08f6b 100644 --- a/website/content/docs/internals/index.mdx +++ b/website/content/docs/internals/index.mdx @@ -19,7 +19,7 @@ Please review the following documentation to understand how Consul works. - [Sessions](/consul/docs/security/acl/auth-methods/oidc) - [Anti-Entropy](/consul/docs/architecture/anti-entropy) - [Security Model](/consul/docs/security) -- [Discovery Chain](/consul/docs/connect/l7-traffic/discovery-chain) +- [Discovery Chain](/consul/docs/connect/manage-traffic/discovery-chain) You should also be familiar with [Jepsen testing](/consul/docs/architecture/jepsen), before deploying a production datacenter. diff --git a/website/content/docs/k8s/connect/cluster-peering/usage/create-sameness-groups.mdx b/website/content/docs/k8s/connect/cluster-peering/usage/create-sameness-groups.mdx index 8f6fd376a4..8a4260c8a3 100644 --- a/website/content/docs/k8s/connect/cluster-peering/usage/create-sameness-groups.mdx +++ b/website/content/docs/k8s/connect/cluster-peering/usage/create-sameness-groups.mdx @@ -6,7 +6,7 @@ description: |- # Create sameness groups on Kubernetes -This topic describes how to designate groups of services as functionally identical in your network on Consul deployments running Kubernetes. Sameness groups are the preferred failover strategy for deployments with cluster peering connections. For more information about sameness groups and failover, refer to [Failover overview](/consul/docs/connect/failover). +This topic describes how to designate groups of services as functionally identical in your network on Consul deployments running Kubernetes. Sameness groups are the preferred failover strategy for deployments with cluster peering connections. For more information about sameness groups and failover, refer to [Failover overview](/consul/docs/connect/manage-traffic/failover). diff --git a/website/content/docs/k8s/connect/cluster-peering/usage/l7-traffic.mdx b/website/content/docs/k8s/connect/cluster-peering/usage/l7-traffic.mdx index 956298fe3c..0c3b28d693 100644 --- a/website/content/docs/k8s/connect/cluster-peering/usage/l7-traffic.mdx +++ b/website/content/docs/k8s/connect/cluster-peering/usage/l7-traffic.mdx @@ -13,7 +13,7 @@ For general guidance for managing L7 traffic with cluster peering, refer to [Man ## Service resolvers for redirects and failover -When you use cluster peering to connect datacenters through their admin partitions, you can use [dynamic traffic management](/consul/docs/connect/l7-traffic) to configure your service mesh so that services automatically forward traffic to services hosted on peer clusters. +When you use cluster peering to connect datacenters through their admin partitions, you can use [dynamic traffic management](/consul/docs/connect/manage-traffic) to configure your service mesh so that services automatically forward traffic to services hosted on peer clusters. However, the `service-splitter` and `service-router` CRDs do not natively support directly targeting a service instance hosted on a peer. Before you can split or route traffic to a service on a peer, you must define the service hosted on the peer as an upstream service by configuring a failover in a `service-resolver` CRD. Then, you can set up a redirect in a second service resolver to interact with the peer service by name. diff --git a/website/content/docs/k8s/deployment-configurations/multi-cluster/index.mdx b/website/content/docs/k8s/deployment-configurations/multi-cluster/index.mdx index fdf5c6d945..dbffe877c9 100644 --- a/website/content/docs/k8s/deployment-configurations/multi-cluster/index.mdx +++ b/website/content/docs/k8s/deployment-configurations/multi-cluster/index.mdx @@ -13,7 +13,7 @@ with one another. This enables the following features: - Services on all clusters can make calls to each other through Consul Service Mesh. - [Intentions](/consul/docs/connect/intentions) can be used to enforce rules about which services can communicate across all clusters. -- [L7 Routing Rules](/consul/docs/connect/l7-traffic) can enable multi-cluster failover +- [L7 Routing Rules](/consul/docs/connect/manage-traffic) can enable multi-cluster failover and traffic splitting. - The Consul UI has a drop-down menu that lets you navigate between datacenters. diff --git a/website/content/docs/k8s/l7-traffic/failover-tproxy.mdx b/website/content/docs/k8s/l7-traffic/failover-tproxy.mdx index dc0eb80f7d..b5bd4983a2 100644 --- a/website/content/docs/k8s/l7-traffic/failover-tproxy.mdx +++ b/website/content/docs/k8s/l7-traffic/failover-tproxy.mdx @@ -6,7 +6,7 @@ description: Learn how to define failover services in Consul on Kubernetes when # Configure failover services on Kubernetes -This topic describes how to configure failover service instances in Consul on Kubernetes when proxies are in transparent proxy mode. If a service becomes unhealthy or unresponsive, Consul can use the service resolver configuration entry to send inbound requests to backup services. Service resolvers are part of the service mesh proxy upstream discovery chain. Refer to [Service mesh traffic management](/consul/docs/connect/l7-traffic) for additional information. +This topic describes how to configure failover service instances in Consul on Kubernetes when proxies are in transparent proxy mode. If a service becomes unhealthy or unresponsive, Consul can use the service resolver configuration entry to send inbound requests to backup services. Service resolvers are part of the service mesh proxy upstream discovery chain. Refer to [Service mesh traffic management](/consul/docs/connect/manage-traffic) for additional information. ## Overview diff --git a/website/content/docs/k8s/l7-traffic/route-to-virtual-services.mdx b/website/content/docs/k8s/l7-traffic/route-to-virtual-services.mdx index 0a37462edb..bd8c9e3db3 100644 --- a/website/content/docs/k8s/l7-traffic/route-to-virtual-services.mdx +++ b/website/content/docs/k8s/l7-traffic/route-to-virtual-services.mdx @@ -10,7 +10,7 @@ This topic describes how to define virtual services so that Consul on Kubernetes ## Overview -You can define virtual services in service resolver configuration entries so that downstream applications can send requests to a virtual service using a Consul DNS name in peered clusters. Your applications can send requests to virtual services in the same cluster using KubeDNS. Service resolvers are part of the service mesh proxy upstream discovery chain. Refer to [Service mesh traffic management](/consul/docs/connect/l7-traffic) for additional information. +You can define virtual services in service resolver configuration entries so that downstream applications can send requests to a virtual service using a Consul DNS name in peered clusters. Your applications can send requests to virtual services in the same cluster using KubeDNS. Service resolvers are part of the service mesh proxy upstream discovery chain. Refer to [Service mesh traffic management](/consul/docs/connect/manage-traffic) for additional information. Complete the following steps to configure failover service instances in Consul on Kubernetes when proxies are in transparent proxy mode: diff --git a/website/content/docs/services/configuration/services-configuration-reference.mdx b/website/content/docs/services/configuration/services-configuration-reference.mdx index 1626a02da5..cc0302b773 100644 --- a/website/content/docs/services/configuration/services-configuration-reference.mdx +++ b/website/content/docs/services/configuration/services-configuration-reference.mdx @@ -15,49 +15,52 @@ This topic describes the options you can use to define services for registering The following outline shows how to format the configurations in the root `service` block. Click on a property name to view details about the configuration. - [`name`](#name): string | required -- [`id`](#id): string | optional -- [`address`](#address): string | optional -- [`port`](#port): integer | optional -- [`tags`](#tags): list of strings | optional -- [`meta`](#meta): object | optional - - [_`custom_meta_key`_](#meta): string | optional -- [`tagged_addresses`](#tagged_addresses): object | optional - - [`lan`](#tagged_addresses-lan): object | optional - - [`address`](#tagged_addresses-lan): string | optional - - [`port`](#tagged_addresses-lan): integer | optional - - [`wan`](#tagged_addresses-wan): object | optional - - [`address`](#tagged_addresses-wan): string | optional - - [`port`](#tagged_addresses-wan): integer | optional -- [`socket_path`](#socket_path): string | optional -- [`enable_tag_override`](#enable_tag_override): boolean | optional -- [`checks`](#checks) : list of objects | optional -- [`kind`](#kind): string | optional -- [`proxy`](#proxy): object | optional -- [`connect`](#connect): object | optional - - [`native`](#connect): boolean | optional - - [`sidecar_service`](#connect): object | optional -- [`weights`](#weights): object | optional - - [`passing`](#weights): integer | optional - - [`warning`](#weights): integer | optional +- [`id`](#id): string +- [`address`](#address): string +- [`port`](#port): number +- [`tags`](#tags): list of strings +- [`meta`](#meta): map + - [_`custom_meta_key`_](#meta): string +- [`tagged_addresses`](#tagged_addresses): map + - [`lan`](#tagged_addresses-lan): map + - [`address`](#tagged_addresses-lan): string + - [`port`](#tagged_addresses-lan): number + - [`wan`](#tagged_addresses-wan): map + - [`address`](#tagged_addresses-wan): string + - [`port`](#tagged_addresses-wan): number +- [`socket_path`](#socket_path): string +- [`enable_tag_override`](#enable_tag_override): boolean +- [`checks`](#checks) : list of maps +- [`kind`](#kind): string +- [`proxy`](#proxy): map +- [`connect`](#connect): map + - [`native`](#connect): boolean + - [`sidecar_service`](#connect): object +- [`locality`](#locality): map + - [`region`](#locality): string + - [`zone`](#locality): string +- [`weights`](#weights): map + - [`passing`](#weights): number + - [`warning`](#weights): number - [`token`](#token): string | required if ACLs are enabled -- [`namespace`](#namespace): string | optional | +- [`namespace`](#namespace): string | ## Specification This topic provides details about the configuration parameters. -### name +### `name` Required value that specifies a name for the service. We recommend using valid DNS labels for service definition names for compatibility with external DNSs. The value for this parameter is used as the ID if the `id` parameter is not specified. - Type: string - Default: none -### id +### `id` Specifies an ID for the service. Services on the same node must have unique IDs. We recommend specifying unique values if the default name conflicts with other services. - Type: string - Default: Value of the `name` field. -### address +### `address` String value that specifies a service-specific IP address or hostname. If no value is specified, the IP address of the agent node is used by default. There is no service-side validation of this parameter. @@ -65,13 +68,13 @@ There is no service-side validation of this parameter. - Type: string - Default: IP address of the agent node -### port +### `port` Specifies a port number for the service. To improve service discoverability, we recommend specifying the port number, as well as an address in the [`tagged_addresses`](#tagged_addresses) parameter. - Type: integer - Default: Port number of the agent -### tags +### `tags` Specifies a list of string values that add service-level labels. Tag values are opaque to Consul. We recommend using valid DNS labels for service definition IDs for compatibility with external DNSs. In the following example, the service is tagged as `v2` and `primary`: ```hcl @@ -80,7 +83,7 @@ tags = ["v2", "primary"] Consul uses tags as an anti-entropy mechanism to maintain the state of the cluster. You can disable the anti-entropy feature for a service using the [`enable_tag_override`](#enable_tag_override) setting, which enables external agents to modify tags on services in the catalog. Refer to [Modify anti-entropy synchronization](/consul/docs/services/usage/define-services#modify-anti-entropy-synchronization) for additional usage information. -### meta +### `meta` The `meta` field contains custom key-value pairs that associate semantic metadata with the service. You can specify up to 64 pairs that meet the following requirements: - Keys and values must be strings. @@ -109,7 +112,7 @@ meta = { -### tagged_addresses +### `tagged_addresses` The `tagged_address` field is an object that configures additional addresses for a node or service. Remote agents and services can communicate with the service using a tagged address as an alternative to the address specified in the [`address`](#address) field. You can configure multiple addresses for a node or service. The following tags are supported: - [`lan`](#tagged_addresses-lan): IPv4 LAN address where the node or service is accessible. @@ -120,7 +123,7 @@ The `tagged_address` field is an object that configures additional addresses for - [`wan_ipv4`](#tagged_addresses-wan): IPv4 WAN address where the node or service is accessible when dialed from a remote data center. - [`wan_ipv6`](#tagged_addresses-lan): IPv6 WAN address at which the node or service is accessible when being dialed from a remote data center. -### tagged_addresses.lan +### `tagged_addresses.lan` Object that specifies either an IPv4 or IPv6 LAN address and port number where the service or node is accessible. You can specify one or more of the following fields: - `lan` @@ -184,7 +187,7 @@ service { -### tagged_addresses.virtual +### `tagged_addresses.virtual` Object that specifies a fixed IP address and port number that downstream services in a service mesh can use to connect to the service. The `virtual` field contains the following parameters: - `address` @@ -233,7 +236,7 @@ service { -### tagged_addresses.wan +### `tagged_addresses.wan` Object that specifies either an IPv4 or IPv6 WAN address and port number where the service or node is accessible from a remote datacenter. You can specify one or more of the following fields: - `wan` @@ -297,13 +300,13 @@ service { -### socket_path +### `socket_path` String value that specifies the path to the service socket. Specify this parameter to expose the service to the mesh if the service listens on a Unix Domain socket. - Type: string - Default: none -### enable_tag_override +### `enable_tag_override` Boolean value that determines if the anti-entropy feature for the service is enabled. Set to `true` to allow external Consul agents modify tags on the services in the Consul catalog. The local Consul agent ignores updated tags during subsequent sync operations. @@ -314,10 +317,10 @@ Refer to [Modify anti-entropy synchronization](/consul/docs/services/usage/defin - Type: boolean - Default: `false` -### checks +### `checks` The `checks` block contains an array of objects that define health checks for the service. Health checks perform several safety functions, such as allowing a web balancer to gracefully remove failing nodes and allowing a database to replace a failed secondary. Refer to [Health Check Configuration Reference](/consul/docs/services/configuration/checks-configuration-reference) for information about configuring health checks. -### kind +### `kind` String value that identifies the service as a proxy and determines its role in the service mesh. Do not configure the `kind` parameter for non-proxy service instances. Refer to [Consul Service Mesh](/consul/docs/connect) for additional information. You can specify the following values: @@ -329,10 +332,10 @@ You can specify the following values: For non-service registration roles, the `kind` field has a different context when used to define configuration entries, such as `service-defaults`. Refer to the documentation for the configuration entry you want to implement for additional information. -### proxy +### `proxy` Object that specifies proxy configurations when the service is configured to operate as a proxy in a service mesh. Do not configure the `proxy` parameter for non-proxy service instances. Refer to [Service mesh proxies overview](/consul/docs/connect/proxies) for details about registering your service as a service mesh proxy. Refer to [`kind`](#kind) for information about the types of proxies you can define. Services that you assign proxy roles to are registered as services in the catalog. -### connect +### `connect` Object that configures a Consul service mesh connection. You should only configure the `connect` block of parameters if you are using Consul service mesh. Refer to [Consul Service Mesh](/consul/docs/connect) for additional information. The following table describes the parameters that you can place in the `connect` block: @@ -342,6 +345,20 @@ The following table describes the parameters that you can place in the `connect` | `native` | Boolean value that advertises the service as a native service mesh proxy. Use this parameter to integrate your application with the `connect` API. Refer to [Service Mesh Native App Integration Overview](/consul/docs/connect/native) for additional information. If set to `true`, do not configure a `sidecar_service`. | `false` | | `sidecar_service` | Object that defines a sidecar proxy for the service. Do not configure if `native` is set to `true`. Refer to [Deploy sidecar services](/consul/docs/connect/proxies/deploy-sidecar-services) for usage and configuration details. | Refer to [Sidecar service defaults](/consul/docs/connect/proxies/deploy-sidecar-services#sidecar-service-defaults). | +### `locality` + +Map of configurations that specify the region and zone in the cloud service provider (CSP) where the service is available. 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. + +- Default: None +- Data type: Map + +Services inherit the `locality` configuration of the Consul agent they are registered with, but you can explicitly define locale for your services. The following table describes the parameters you can explicitly configure in the `locality` block: + +| Parameter | Description | Data type | Default | +| --- | --- | --- | --- | +| `region` | Specifies the region where the service instance is available. You can specify values that map to regions as defined in your network, for example `us-west-1` for networks in AWS. Consul matches this value to regions defined for Consul agents and other services in the network. When the region matches an entity, Consul is able to prioritize routes between service instances 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 `zone`. | String | None | +| `zone` | Specifies the zone where the service instance is available. You can specify values that map to zones defined in your network, for example `us-west-1a` for networks in AWS. Consul matches this value to zones defined for Consul agents and other services in the network. When the zone matches an entity, Consul is able to prioritize routes between service instances 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. | String | None | + ### weights Object that configures how the service responds to DNS SRV requests based on the service's health status. Configuring allows service instances with more capacity to respond to DNS SRV requests. It also reduces the load on services with checks in `warning` status by giving passing instances a higher weight. diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index 49dc215b16..786411b979 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -621,15 +621,53 @@ ] }, { - "title": "L7 Traffic Management", + "title": "Manage traffic", "routes": [ { "title": "Overview", - "path": "connect/l7-traffic" + "path": "connect/manage-traffic" }, { - "title": "Discovery Chain", - "path": "connect/l7-traffic/discovery-chain" + "title": "Route traffic to local upstreams", + "path": "connect/manage-traffic/route-to-local-upstreams" + }, + { + "title": "Limit request rates to services", + "path": "connect/manage-traffic/limit-request-rates" + }, + { + "title": "Failover", + "routes": [ + { + "title": "Overview", + "path": "connect/manage-traffic/failover" + }, + { + "title": "Configure failover services for Kubernetes", + "href": "/docs/k8s/l7-traffic/failover-tproxy" + }, + { + "title": "Automate geo-failover with prepared queries", + "href": "/tutorials/developer-discovery/automate-geo-failover" + }, + { + "title": "Configuration", + "routes": [ + { + "title": "Service resolver", + "href": "/consul/docs/connect/config-entries/service-resolver" + }, + { + "title": "Service intentions", + "href": "/consul/docs/connect/config-entries/service-intentions" + } + ] + } + ] + }, + { + "title": "Discovery chain reference", + "path": "connect/manage-traffic/discovery-chain" } ] }, @@ -768,41 +806,6 @@ } ] }, - { - "title": "Failover", - "routes": [ - { - "title": "Overview", - "path": "connect/failover" - }, - { - "title": "Usage", - "routes": [ - { - "title": "Configure failover services for Kubernetes", - "href": "/docs/k8s/l7-traffic/failover-tproxy" - }, - { - "title": "Automate geo-failover with prepared queries", - "href": "/tutorials/developer-discovery/automate-geo-failover" - } - ] - }, - { - "title": "Configuration", - "routes": [ - { - "title": "Service resolver", - "href": "/consul/docs/connect/config-entries/service-resolver" - }, - { - "title": "Service intentions", - "href": "/consul/docs/connect/config-entries/service-intentions" - } - ] - } - ] - }, { "title": "Nomad", "path": "connect/nomad" diff --git a/website/redirects.js b/website/redirects.js index fa2b13bbb3..d60264054b 100644 --- a/website/redirects.js +++ b/website/redirects.js @@ -137,4 +137,19 @@ module.exports = [ destination: '/consul/docs/ecs/reference/compatibility', permanent: true, }, + { + source: '/consul/docs/connect/failover', + destination: '/consul/docs/connect/manage-traffic/failover', + permanent: true, + }, + { + source: '/consul/docs/connect/l7', + destination: '/consul/docs/connect/manage-traffic', + permanent: true, + }, + { + source: '/consul/docs/connect/l7/:slug', + destination: '/consul/docs/connect/manage-traffic/:slug', + permanent: true, + }, ]