2019-08-07 19:55:04 +00:00
---
2020-04-07 18:55:19 +00:00
layout: docs
2022-09-16 15:28:32 +00:00
page_title: Service Mesh Traffic Management - Discovery Chain
2020-04-07 18:55:19 +00:00
description: >-
2022-09-16 15:28:32 +00:00
The discovery chain compiles service router, splitter, and resolver configuration entries to direct traffic to specific instances in a service mesh. Learn about compiled discovery chain results, including discovery graph nodes and targets.
2019-08-07 19:55:04 +00:00
---
2022-09-13 20:26:51 +00:00
# Discovery Chain for Service Mesh Traffic Management
2019-08-07 19:55:04 +00:00
2020-04-07 23:56:08 +00:00
-> **1.6.0+:** This feature is available in Consul versions 1.6.0 and newer.
2023-01-25 16:52:43 +00:00
~> This topic is part of a [low-level API](/consul/api-docs/discovery-chain)
2023-05-05 17:41:40 +00:00
primarily targeted at developers building external [Consul service mesh proxy
2023-01-25 16:52:43 +00:00
integrations](/consul/docs/connect/proxies/integrate).
2019-08-07 19:55:04 +00:00
The service discovery process can be modeled as a "discovery chain" which
passes through three distinct stages: routing, splitting, and resolution. Each
of these stages is controlled by a set of [configuration
2023-01-25 16:52:43 +00:00
entries](/consul/docs/agent/config-entries). By configuring different phases of
2019-08-07 19:55:04 +00:00
the discovery chain a user can control how proxy upstreams are ultimately
resolved to specific instances for load balancing.
-> **Note:** The discovery chain is currently only used to discover
2023-05-05 17:41:40 +00:00
[service mesh](/consul/docs/connect) proxy upstreams.
2019-08-07 19:55:04 +00:00
## Configuration
The configuration entries used in the discovery chain are designed to be simple
to read and modify for narrowly tailored changes, but at discovery-time the
various configuration entries interact in more complex ways. For example:
2023-01-25 16:52:43 +00:00
- If a [`service-resolver`](/consul/docs/connect/config-entries/service-resolver)
2019-08-07 19:55:04 +00:00
is created with a [service
2023-01-25 16:52:43 +00:00
redirect](/consul/docs/connect/config-entries/service-resolver#service) defined,
2019-08-07 19:55:04 +00:00
then all references made to the original service in any other configuration
entry is replaced with the redirect destination.
2023-01-25 16:52:43 +00:00
- If a [`service-resolver`](/consul/docs/connect/config-entries/service-resolver)
2019-08-07 19:55:04 +00:00
is created with a [default
2023-01-25 16:52:43 +00:00
subset](/consul/docs/connect/config-entries/service-resolver#defaultsubset)
2019-08-07 19:55:04 +00:00
defined then all references made to the original service in any other
configuration entry that did not specify a subset will be replaced with the
default.
2023-01-25 16:52:43 +00:00
- If a [`service-splitter`](/consul/docs/connect/config-entries/service-splitter)
2019-08-07 19:55:04 +00:00
is created with a [service
2023-01-25 16:52:43 +00:00
split](/consul/docs/connect/config-entries/service-splitter#splits), and the target service has its
2020-04-06 20:27:35 +00:00
own `service-splitter` then the overall effect is flattened and only a single
2019-08-07 19:55:04 +00:00
aggregate traffic split is ultimately configured in the proxy.
2023-01-25 16:52:43 +00:00
- [`service-resolver`](/consul/docs/connect/config-entries/service-resolver)
2019-08-07 19:55:04 +00:00
redirect loops must be rejected as invalid.
2023-01-25 16:52:43 +00:00
- [`service-router`](/consul/docs/connect/config-entries/service-router) and
[`service-splitter`](/consul/docs/connect/config-entries/service-splitter)
2019-08-07 19:55:04 +00:00
configuration entries require an L7 compatible protocol be set for the
service via either a
2023-01-25 16:52:43 +00:00
[`service-defaults`](/consul/docs/connect/config-entries/service-defaults) or
[`proxy-defaults`](/consul/docs/connect/config-entries/proxy-defaults) config
2019-08-07 19:55:04 +00:00
entry. Violations must be rejected as invalid.
2023-09-06 23:55:18 +00:00
- When an [upstream
configuration](/consul/docs/connect/proxies/proxy-config-reference#upstream-configuration-reference)
`datacenter` parameter is defined, any configuration entry that does not explicitly
refer to a desired datacenter uses the value defined in the upstream.
2019-08-07 19:55:04 +00:00
## Compilation
To correctly interpret a collection of configuration entries as a valid
discovery chain, we first compile them into a form more directly usable by the
2023-05-05 17:41:40 +00:00
layers responsible for configuring service mesh sidecar proxies.
2019-08-07 19:55:04 +00:00
You can interact with the compiler directly using the [discovery-chain
2023-01-25 16:52:43 +00:00
API](/consul/api-docs/discovery-chain).
2019-08-07 19:55:04 +00:00
### Compilation Parameters
2020-04-06 20:27:35 +00:00
- **Service Name** - The service being discovered by name.
- **Datacenter** - The datacenter to use as the basis of compilation.
- **Overrides** - Discovery-time tweaks to apply when compiling. These should
2019-08-07 19:55:04 +00:00
be derived from either the
2023-09-06 23:55:18 +00:00
[proxy](/consul/docs/connect/proxies/proxy-config-reference#complete-configuration-example)
2019-08-07 19:55:04 +00:00
or
2023-09-06 23:55:18 +00:00
[upstream](/consul/docs/connect/proxies/proxy-config-reference#upstream-configuration-reference)
2019-08-07 19:55:04 +00:00
configurations if either are set.
### Compilation Results
The response is a single wrapped `CompiledDiscoveryChain` field:
```json
{
"Chain": {...<CompiledDiscoveryChain>...}
}
```
#### `CompiledDiscoveryChain`
The chain encodes a digraph of [nodes](#discoverygraphnode) and
[targets](#discoverytarget). Nodes are the compiled representation of various
discovery chain stages and targets are instructions on how to use the [health
2023-05-05 17:41:40 +00:00
API](/consul/api-docs/health#list-nodes-for-mesh-capable-service) to retrieve
2019-08-07 19:55:04 +00:00
relevant service instance lists.
You should traverse the nodes starting with [`StartNode`](#startnode). The
nodes can be resolved by name using the [`Nodes`](#nodes) field. Targets can be
resolved by name using the [`Targets`](#targets) field.
- `ServiceName` `(string)` - The requested service.
2021-12-14 20:37:34 +00:00
- `Partition` `(string)` - The requested partition.
2019-08-07 19:55:04 +00:00
- `Namespace` `(string)` - The requested namespace.
- `Datacenter` `(string)` - The requested datacenter.
- `CustomizationHash` `(string: <optional>)` - A unique hash of any overrides
that affected the compilation of the discovery chain.
2020-04-06 20:27:35 +00:00
If set, this value should be used to prefix/suffix any generated load
balancer data plane objects to avoid sharing customized and non-customized
versions.
2019-08-07 19:55:04 +00:00
2022-03-30 15:04:18 +00:00
- `Default` `(bool: <optional>)` - Indicates if this discovery chain is based on no
`service-resolver`, `service-splitter`, or `service-router` config entries.
2019-08-07 19:55:04 +00:00
- `Protocol` `(string)` - The overall protocol shared by everything in the
chain.
2022-03-30 15:04:18 +00:00
- `ServiceMeta` `(map<string|string>)` - The metadata from the underlying `service-defaults` config
entry for the service named `ServiceName`.
2019-08-07 19:55:04 +00:00
- `StartNode` `(string)` - The first key into the `Nodes` map that should be
followed when traversing the discovery chain.
- `Nodes` `(map<string|DiscoveryGraphNode>)` - All nodes available for traversal in
the chain keyed by a unique name. You can walk this by starting with
`StartNode`.
2020-04-06 20:27:35 +00:00
-> The names should be treated as opaque values and are only guaranteed to be
consistent within a single compilation.
2019-08-07 19:55:04 +00:00
- `Targets` `(map<string|DiscoveryTarget>)` - A list of all targets used in this chain.
2020-04-06 20:27:35 +00:00
-> The names should be treated as opaque values and are only guaranteed to be
consistent within a single compilation.
2019-08-07 19:55:04 +00:00
#### `DiscoveryGraphNode`
A single node in the compiled discovery chain.
- `Type` `(string)` - The type of the node. Valid values are: `router`,
`splitter`, and `resolver`.
- `Name` `(string)` - The unique name of the node.
- `Routes` `(array<DiscoveryRoute>)` - Only set for `Type:router`. List of routes to
render.
- `Definition` `(ServiceRoute)` - Relevant portion of underlying
`service-router`
2023-01-25 16:52:43 +00:00
[route](/consul/docs/connect/config-entries/service-router#routes).
2019-08-07 19:55:04 +00:00
- `NextNode` `(string)` - The name of the next node in the chain in [`Nodes`](#nodes).
- `Splits` `(array<DiscoverySplit>)` - Only set for `Type:splitter`. List of traffic
splits.
- `Weight` `(float32)` - Copy of underlying `service-splitter`
2023-01-25 16:52:43 +00:00
[`weight`](/consul/docs/connect/config-entries/service-splitter#weight) field.
2019-08-07 19:55:04 +00:00
- `NextNode` `(string)` - The name of the next node in the chain in [`Nodes`](#nodes).
- `Resolver` `(DiscoveryResolver: <optional>)` - Only set for `Type:resolver`. How
to resolve the service instances.
- `Default` `(bool)` - Set to true if no `service-resolver` config entry is
defined for this node and the default was synthesized.
- `ConnectTimeout` `(duration)` - Copy of the underlying `service-resolver`
2023-01-25 16:52:43 +00:00
[`ConnectTimeout`](/consul/docs/connect/config-entries/service-resolver#connecttimeout)
2019-08-07 19:55:04 +00:00
field. If one is not defined the default of `5s` is returned.
- `Target` `(string)` - The name of the target to use found in [`Targets`](#targets).
- `Failover` `(DiscoveryFailover: <optional>)` - Compiled form of the
underlying `service-resolver`
2023-01-25 16:52:43 +00:00
[`Failover`](/consul/docs/connect/config-entries/service-resolver#failover)
2019-08-07 19:55:04 +00:00
definition to use for this request.
- `Targets` `(array<string>)` - List of targets found in
[`Targets`](#targets) to failover to in order of preference.
2020-12-08 23:24:36 +00:00
2020-09-02 15:10:50 +00:00
- `LoadBalancer` `(LoadBalancer: <optional>`) - Copy of the underlying `service-resolver`
2023-01-25 16:52:43 +00:00
[`LoadBalancer`](/consul/docs/connect/config-entries/service-resolver#loadbalancer) field.
2020-12-08 23:24:36 +00:00
2020-09-02 15:10:50 +00:00
If a `service-splitter` splits between services with differing `LoadBalancer` configuration
2020-12-08 23:24:36 +00:00
the first hash-based load balancing policy is copied.
2019-08-07 19:55:04 +00:00
#### `DiscoveryTarget`
- `ID` `(string)` - The unique name of this target.
- `Service` `(string)` - The service to query when resolving a list of service instances.
- `ServiceSubset` `(string: <optional>)` - The
2023-01-25 16:52:43 +00:00
[subset](/consul/docs/connect/config-entries/service-resolver#service-subsets) of
2019-08-07 19:55:04 +00:00
the service to resolve.
2021-12-14 20:37:34 +00:00
- `Partition` `(string)` - The partition to use when resolving a list of service instances.
2019-08-07 19:55:04 +00:00
- `Namespace` `(string)` - The namespace to use when resolving a list of service instances.
- `Datacenter` `(string)` - The datacenter to use when resolving a list of service instances.
- `Subset` `(ServiceResolverSubset)` - Copy of the underlying
`service-resolver`
2023-01-25 16:52:43 +00:00
[`Subsets`](/consul/docs/connect/config-entries/service-resolver#subsets)
2019-08-07 19:55:04 +00:00
definition for this target.
2020-04-06 20:27:35 +00:00
- `Filter` `(string: "")` - The
2023-01-25 16:52:43 +00:00
[filter expression](/consul/api-docs/features/filtering) to be used for selecting
2019-08-07 19:55:04 +00:00
instances of the requested service. If empty all healthy instances are
returned.
- `OnlyPassing` `(bool: false)` - Specifies the behavior of the resolver's
health check interpretation. If this is set to false, instances with checks
in the passing as well as the warning states will be considered healthy. If
this is set to true, only instances with checks in the passing state will
be considered healthy.
- `MeshGateway` `(MeshGatewayConfig)` - The [mesh gateway
2023-05-05 17:41:40 +00:00
configuration](/consul/docs/connect/gateways/mesh-gateway#service-mesh-proxy-configuration)
2019-08-07 19:55:04 +00:00
to use when connecting to this target's service instances.
- `Mode` `(string: "")` - One of `none`, `local`, or `remote`.
- `External` `(bool: false)` - True if this target is outside of this consul cluster.
2022-04-07 21:58:21 +00:00
- `ConnectTimeout` `(duration)` - Copy of the underlying `service-resolver`
2023-01-25 16:52:43 +00:00
[`ConnectTimeout`](/consul/docs/connect/config-entries/service-resolver#connecttimeout)
2022-04-07 21:58:21 +00:00
field. If one is not defined the default of `5s` is returned.
2019-08-07 19:55:04 +00:00
- `SNI` `(string)` - This value should be used as the
[SNI](https://en.wikipedia.org/wiki/Server_Name_Indication) value when
connecting to this set of endpoints over TLS.
- `Name` `(string)` - The unique name for this target for use when generating
load balancer objects. This has a structure similar to [SNI](#sni), but will
not be affected by SNI customizations such as
2023-01-25 16:52:43 +00:00
[`ExternalSNI`](/consul/docs/connect/config-entries/service-defaults#externalsni).
