2019-07-09 02:11:19 +00:00
|
|
|
---
|
2020-04-07 18:55:19 +00:00
|
|
|
layout: docs
|
|
|
|
|
page_title: Connect - L7 Traffic Management
|
|
|
|
|
description: >-
|
|
|
|
|
Layer 7 traffic management allows operators to divide L7 traffic between
|
|
|
|
|
different subsets of service instances when using Connect.
|
2019-07-09 02:11:19 +00:00
|
|
|
---
|
|
|
|
|
|
2020-04-06 20:27:35 +00:00
|
|
|
-> **1.6.0+:** This feature is available in Consul versions 1.6.0 and newer.
|
2019-07-09 02:11:19 +00:00
|
|
|
|
2019-08-21 21:23:08 +00:00
|
|
|
# L7 Traffic Management
|
2019-07-09 02:11:19 +00:00
|
|
|
|
|
|
|
|
Layer 7 traffic management allows operators to divide L7 traffic between
|
|
|
|
|
different
|
2021-01-13 20:48:48 +00:00
|
|
|
[subsets](/docs/connect/config-entries/service-resolver#service-subsets) of
|
2019-07-09 02:11:19 +00:00
|
|
|
service instances when using Connect.
|
|
|
|
|
|
|
|
|
|
There are many ways you may wish to carve up a single datacenter's pool of
|
|
|
|
|
services beyond simply returning all healthy instances for load balancing.
|
|
|
|
|
Canary testing, A/B tests, blue/green deploys, and soft multi-tenancy
|
|
|
|
|
(prod/qa/staging sharing compute resources) all require some mechanism of
|
|
|
|
|
carving out portions of the Consul catalog smaller than the level of a single
|
|
|
|
|
service and configuring when that subset should receive traffic.
|
|
|
|
|
|
2020-04-06 20:27:35 +00:00
|
|
|
-> **Note:** This feature is not compatible with the
|
2020-04-09 23:46:54 +00:00
|
|
|
[built-in proxy](/docs/connect/proxies/built-in),
|
|
|
|
|
[native proxies](/docs/connect/native),
|
|
|
|
|
and some [Envoy proxy escape hatches](/docs/connect/proxies/envoy#escape-hatch-overrides).
|
2019-08-21 21:23:08 +00:00
|
|
|
|
2019-07-09 02:11:19 +00:00
|
|
|
## Stages
|
|
|
|
|
|
|
|
|
|
Connect proxy upstreams are discovered using a series of stages: routing,
|
|
|
|
|
splitting, and resolution. These stages represent different ways of managing L7
|
|
|
|
|
traffic.
|
|
|
|
|
|
2022-01-10 19:34:00 +00:00
|
|
|
|
2019-07-09 02:11:19 +00:00
|
|
|
|
|
|
|
|
Each stage of this discovery process can be dynamically reconfigured via various
|
2020-10-14 15:23:05 +00:00
|
|
|
[configuration entries](/docs/agent/config-entries). When a configuration
|
2019-07-09 02:11:19 +00:00
|
|
|
entry is missing, that stage will fall back on reasonable default behavior.
|
|
|
|
|
|
|
|
|
|
### Routing
|
|
|
|
|
|
2021-01-13 20:48:48 +00:00
|
|
|
A [`service-router`](/docs/connect/config-entries/service-router) config
|
2019-07-09 02:11:19 +00:00
|
|
|
entry kind is the first configurable stage.
|
|
|
|
|
|
2022-01-10 19:34:00 +00:00
|
|
|
|
|
|
|
|
|
2019-07-09 02:11:19 +00:00
|
|
|
A router config entry allows for a user to intercept traffic using L7 criteria
|
|
|
|
|
such as path prefixes or http headers, and change behavior such as by sending
|
|
|
|
|
traffic to a different service or service subset.
|
|
|
|
|
|
|
|
|
|
These config entries may only reference `service-splitter` or
|
|
|
|
|
`service-resolver` entries.
|
|
|
|
|
|
2021-01-13 20:48:48 +00:00
|
|
|
[Examples](/docs/connect/config-entries/service-router#sample-config-entries)
|
2019-07-09 02:11:19 +00:00
|
|
|
can be found in the `service-router` documentation.
|
|
|
|
|
|
|
|
|
|
### Splitting
|
|
|
|
|
|
2021-01-13 20:48:48 +00:00
|
|
|
A [`service-splitter`](/docs/connect/config-entries/service-splitter) config
|
2019-07-09 02:11:19 +00:00
|
|
|
entry kind is the next stage after routing.
|
|
|
|
|
|
2022-01-10 19:34:00 +00:00
|
|
|
|
|
|
|
|
|
2019-07-09 02:11:19 +00:00
|
|
|
A splitter config entry allows for a user to choose to split incoming requests
|
|
|
|
|
across different subsets of a single service (like during staged canary
|
|
|
|
|
rollouts), or perhaps across different services (like during a v2 rewrite or
|
|
|
|
|
other type of codebase migration).
|
|
|
|
|
|
|
|
|
|
These config entries may only reference `service-splitter` or
|
|
|
|
|
`service-resolver` entries.
|
|
|
|
|
|
|
|
|
|
If one splitter references another splitter the overall effects are flattened
|
|
|
|
|
into one effective splitter config entry which reflects the multiplicative
|
|
|
|
|
union. For instance:
|
|
|
|
|
|
2020-04-06 20:27:35 +00:00
|
|
|
splitter[A]: A_v1=50%, A_v2=50%
|
|
|
|
|
splitter[B]: A=50%, B=50%
|
|
|
|
|
---------------------
|
|
|
|
|
splitter[effective_B]: A_v1=25%, A_v2=25%, B=50%
|
2019-07-09 02:11:19 +00:00
|
|
|
|
2021-01-13 20:48:48 +00:00
|
|
|
[Examples](/docs/connect/config-entries/service-splitter#sample-config-entries)
|
2019-07-09 02:11:19 +00:00
|
|
|
can be found in the `service-splitter` documentation.
|
|
|
|
|
|
|
|
|
|
### Resolution
|
|
|
|
|
|
2021-01-13 20:48:48 +00:00
|
|
|
A [`service-resolver`](/docs/connect/config-entries/service-resolver) config
|
2019-07-09 02:11:19 +00:00
|
|
|
entry kind is the last stage.
|
|
|
|
|
|
2022-01-10 19:34:00 +00:00
|
|
|
|
|
|
|
|
|
2019-07-09 02:11:19 +00:00
|
|
|
A resolver config entry allows for a user to define which instances of a
|
|
|
|
|
service should satisfy discovery requests for the provided name.
|
|
|
|
|
|
|
|
|
|
Examples of things you can do with resolver config entries:
|
|
|
|
|
|
|
|
|
|
- Control where to send traffic if all instances of `api` in the current
|
2020-04-06 20:27:35 +00:00
|
|
|
datacenter are unhealthy.
|
2019-07-09 02:11:19 +00:00
|
|
|
|
|
|
|
|
- Configure service subsets based on `Service.Meta.version` values.
|
|
|
|
|
|
|
|
|
|
- Send all traffic for `web` that does not specify a service subset to the
|
2020-04-06 20:27:35 +00:00
|
|
|
`version1` subset.
|
2019-07-09 02:11:19 +00:00
|
|
|
|
|
|
|
|
- Send all traffic for `api` to `new-api`.
|
|
|
|
|
|
|
|
|
|
- Send all traffic for `api` in all datacenters to instances of `api` in `dc2`.
|
|
|
|
|
|
|
|
|
|
- Create a "virtual service" `api-dc2` that sends traffic to instances of `api`
|
2020-04-06 20:27:35 +00:00
|
|
|
in `dc2`. This can be referenced in upstreams or in other config entries.
|
2019-07-09 02:11:19 +00:00
|
|
|
|
|
|
|
|
If no resolver config is defined for a service it is assumed 100% of traffic
|
|
|
|
|
flows to the healthy instances of a service with the same name in the current
|
|
|
|
|
datacenter/namespace and discovery terminates.
|
|
|
|
|
|
|
|
|
|
This should feel similar in spirit to various uses of Prepared Queries, but is
|
|
|
|
|
not intended to be a drop-in replacement currently.
|
|
|
|
|
|
|
|
|
|
These config entries may only reference other `service-resolver` entries.
|
|
|
|
|
|
2021-01-13 20:48:48 +00:00
|
|
|
[Examples](/docs/connect/config-entries/service-resolver#sample-config-entries)
|
2019-07-09 02:11:19 +00:00
|
|
|
can be found in the `service-resolver` documentation.
|
|
|
|
|
|
2021-11-08 14:11:36 +00:00
|
|
|
-> **Note:** `service-resolver` config entries kinds can function at L4 (unlike
|
2019-07-09 02:11:19 +00:00
|
|
|
`service-router` and `service-splitter` kinds). These can be created for
|
2022-01-10 19:34:00 +00:00
|
|
|
services of any protocol such as `tcp`.
|
