mirror of https://github.com/status-im/consul.git
Docs/ce 470 locality aware (#19071)
* updated nav; renamed L7 traffic folder * Added locality-aware routing to traffic mgmt overview * Added route to local upstreams topic * Updated agent configuration reference * Added locality param to services conf ref * Added locality param to conf entries * mentioned traffic management in proxies overview * added locality-aware to failover overview * added docs for service rate limiting * updated service defaults conf entry * Apply suggestions from code review Co-authored-by: Chris S. Kim <ckim@hashicorp.com> * Apply suggestions from code review Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com> Co-authored-by: Chris S. Kim <ckim@hashicorp.com> * updated links and added redirects --------- Co-authored-by: Chris S. Kim <ckim@hashicorp.com> Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com>
This commit is contained in:
trujillo-adam
GitHub
parent
af3439b53d
commit
a9747dc38c
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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 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
|
||||
|
|
|
|||
|
|
@ -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).
|
||||
|
||||
<Warning>
|
||||
|
||||
|
|
@ -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)
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
@ -89,6 +91,8 @@ The following list outlines field hierarchy, language-specific data types, and r
|
|||
- [`localPathPort`](#spec-expose-paths): number | `0`
|
||||
- [`listenerPort`](#spec-expose-paths): number | `0`
|
||||
- [`protocol`](#spec-expose-paths): string | `http`
|
||||
- [`prioritizeByLocality`](#prioritizebylocality): map | <EnterpriseAlert inline/>
|
||||
- [`mode`](#prioritizebylocality): string | `failover`
|
||||
- [`failoverPolicy`](#spec-failoverpolicy): map
|
||||
- [`mode`](#spec-failoverpolicy-mode): string
|
||||
- [`accessLogs`](#spec-accesslogs): map
|
||||
|
|
@ -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: <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.
|
||||
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: <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.
|
||||
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:
|
||||
|
||||
|
|
|
|||
File diff suppressed because it is too large
Load Diff
|
|
@ -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 <EnterpriseAlert inline />
|
||||
- [`Datacenter`](#redirect-datacenter): string
|
||||
- [`Peer`](#redirect-peer): string
|
||||
- [`PrioritizeByLocality`](#prioritizebylocality): map <EnterpriseAlert inline/>
|
||||
- [`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 <EnterpriseAlert inline />
|
||||
- [`datacenter`](#spec-redirect-datacenter): string
|
||||
- [`peer`](#spec-redirect-peer): string
|
||||
- [`prioritizeByLocality`](#spec-prioritizebylocality): map | <EnterpriseAlert inline/>
|
||||
- [`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 = "<destination-peer>"
|
||||
}
|
||||
|
||||
PrioritizeByLocality = {
|
||||
Mode = "failover"
|
||||
}
|
||||
|
||||
Failover = { ## requires at least one of the following: Service, ServiceSubset, Namespace, Targets, Datacenters, SamenessGroup
|
||||
<local-subset-name> = {
|
||||
Targets = [
|
||||
|
|
@ -238,7 +246,6 @@ LoadBalancer = {
|
|||
}
|
||||
},
|
||||
"DefaultSubset ":"<subset01-name>",
|
||||
|
||||
"Redirect":{
|
||||
"Service":"<destination-service>",
|
||||
"ServiceSubset":"<destination-subset>",
|
||||
|
|
@ -248,7 +255,9 @@ LoadBalancer = {
|
|||
"Datacenter":"<destination-datacenter>",
|
||||
"Peer":"<destination-peer>"
|
||||
},
|
||||
|
||||
"PrioritizeByLocality" : {
|
||||
"Mode": "failover"
|
||||
},
|
||||
"Failover":{ // requires at least one of the following": Service, ServiceSubset, Namespace, Targets, Datacenters, SamenessGroup
|
||||
"<local=subset-name>":{
|
||||
"Targets":[
|
||||
|
|
@ -322,6 +331,8 @@ spec:
|
|||
partition: <partitionName>
|
||||
samenessGroup: <samenessGroupName>
|
||||
peer: <peerName>
|
||||
prioritizeByLocality:
|
||||
mode: failover
|
||||
failover: # requires at least one of the following: service, serviceSubset, namespace, targets, datacenters, samenessGroup
|
||||
<localSubsetName>:
|
||||
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.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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<br/> query | Sameness groups |
|
||||
| --- | :---: | :---: | :---: |
|
||||
| <nobr>**Supports WAN federation**</nobr> | ✅ | ✅ | ❌ |
|
||||
| **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.
|
||||
|
||||
|
|
@ -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:
|
||||
|
||||
|
|
@ -78,3 +78,7 @@ 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.
|
||||
|
||||
## 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.
|
||||
|
|
@ -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:
|
||||
|
||||
<Tabs>
|
||||
<Tab heading="VMs" group="vms">
|
||||
|
||||
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.
|
||||
|
||||
</Tab>
|
||||
<Tab heading="Kubernetes" group="k8s">
|
||||
|
||||
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.
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
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:
|
||||
|
||||
<Tabs>
|
||||
<Tab heading="VMs" group="vms">
|
||||
|
||||
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.
|
||||
|
||||
</Tab>
|
||||
<Tab heading="Kubernetes" group="k8s">
|
||||
|
||||
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.
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
Refer to the [service defaults configuration entry reference](/consul/docs/connect/config-entries/service-defaults) for additional specifications and example configurations.
|
||||
|
||||
|
|
@ -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.
|
||||
|
||||
<EnterpriseAlert> This feature is available in Consul Enterprise. </EnterpriseAlert>
|
||||
|
||||
## 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.
|
||||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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:
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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).
|
||||
|
||||
<Warning>
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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:
|
||||
|
||||
|
|
|
|||
|
|
@ -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 <EnterpriseAlert inline/>
|
||||
- [`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 | <EnterpriseAlert inline />
|
||||
- [`namespace`](#namespace): string | <EnterpriseAlert inline />
|
||||
|
||||
## 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 = {
|
|||
|
||||
</CodeTabs>
|
||||
|
||||
### 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 {
|
|||
|
||||
</CodeTabs>
|
||||
|
||||
### 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 {
|
|||
|
||||
</CodeTabs>
|
||||
|
||||
### 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 {
|
|||
|
||||
</CodeTabs>
|
||||
|
||||
### 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` <EnterpriseAlert inline/>
|
||||
|
||||
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.
|
||||
|
||||
|
|
|
|||
|
|
@ -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"
|
||||
|
|
|
|||
|
|
@ -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,
|
||||
},
|
||||
]
|
||||
|
|
|
|||
Loading…
Reference in New Issue