mirror of https://github.com/hashicorp/consul
R.B. Boyer
5 years ago
committed by
GitHub
12 changed files with 847 additions and 59 deletions
Binary file not shown.
|
After Width: | Height: | Size: 19 KiB |
@ -0,0 +1,60 @@
|
||||
--- |
||||
layout: "docs" |
||||
page_title: "Configuration Entry Kind: Proxy Defaults" |
||||
sidebar_current: "docs-agent-cfg_entries-proxy_defaults" |
||||
description: |- |
||||
The proxy-defaults config entry kind allows for configuring global config defaults across all services for Connect proxy configuration. Currently, only one global entry is supported. |
||||
--- |
||||
|
||||
# Proxy Defaults |
||||
|
||||
The `proxy-defaults` config entry kind allows for configuring global config |
||||
defaults across all services for Connect proxy configuration. Currently, only |
||||
one global entry is supported. |
||||
|
||||
## Sample Config Entries |
||||
|
||||
Set the default protocol for all sidecar proxies: |
||||
|
||||
```hcl |
||||
kind = "proxy-defaults" |
||||
name = "global" |
||||
config { |
||||
protocol = "http" |
||||
} |
||||
``` |
||||
|
||||
Set proxy-specific defaults: |
||||
|
||||
```hcl |
||||
kind = "proxy-defaults" |
||||
name = "global" |
||||
config { |
||||
local_connect_timeout_ms = 1000 |
||||
handshake_timeout_ms = 10000 |
||||
} |
||||
``` |
||||
|
||||
## Available Fields |
||||
|
||||
- `Kind` - Must be set to `proxy-defaults` |
||||
|
||||
- `Name` - Must be set to `global` |
||||
|
||||
- `Config` `(map[string]arbitrary)` - An arbitrary map of configuration values used by Connect proxies. |
||||
The available configurations depend on the Connect proxy you use. Any values |
||||
that your proxy allows can be configured globally here. To |
||||
explore these options please see the documentation for your chosen proxy. |
||||
|
||||
* [Envoy](/docs/connect/proxies/envoy.html#bootstrap-configuration) |
||||
* [Consul's built-in proxy](/docs/connect/proxies/built-in.html) |
||||
|
||||
## ACLs |
||||
|
||||
Configuration entries may be protected by |
||||
[ACLs](https://learn.hashicorp.com/consul/security-networking/production-acls). |
||||
|
||||
Reading a `proxy-defaults` config entry requires no specific privileges. |
||||
|
||||
Creating, updating, or deleting a `proxy-defaults` config entry requires |
||||
`operator:write`. |
||||
@ -0,0 +1,46 @@
|
||||
--- |
||||
layout: "docs" |
||||
page_title: "Configuration Entry Kind: Service Defaults" |
||||
sidebar_current: "docs-agent-cfg_entries-service_defaults" |
||||
description: |- |
||||
The service-defaults config entry kind controls default global values for a service, such as its protocol. |
||||
--- |
||||
|
||||
# Service Defaults |
||||
|
||||
The `service-defaults` config entry kind controls default global values for a |
||||
service, such as its protocol. |
||||
|
||||
## Sample Config Entries |
||||
|
||||
Set the default protocol for a service to HTTP: |
||||
|
||||
```hcl |
||||
Kind = "service-defaults" |
||||
Name = "web" |
||||
Protocol = "http" |
||||
``` |
||||
|
||||
## Available Fields |
||||
|
||||
- `Kind` - Must be set to `service-defaults` |
||||
|
||||
- `Name` `(string: <required>)` - Set to the name of the service being configured. |
||||
|
||||
- `Protocol` `(string: "tcp")` - Sets the protocol of the service. This is used |
||||
by Connect proxies for things like observability features and to unlock usage |
||||
of the [`service-splitter` |
||||
<sup>(beta)</sup>](/docs/agent/config-entries/service-splitter.html) and |
||||
[`service-router` |
||||
<sup>(beta)</sup>](/docs/agent/config-entries/service-router.html) config |
||||
entries for a service. |
||||
|
||||
## ACLs |
||||
|
||||
Configuration entries may be protected by |
||||
[ACLs](https://learn.hashicorp.com/consul/security-networking/production-acls). |
||||
|
||||
Reading a `service-defaults` config entry requires `service:read` on itself. |
||||
|
||||
Creating, updating, or deleting a `service-defaults` config entry requires |
||||
`service:write` on itself. |
||||
@ -0,0 +1,185 @@
|
||||
--- |
||||
layout: "docs" |
||||
page_title: "Configuration Entry Kind: Service Resolver (beta)" |
||||
sidebar_current: "docs-agent-cfg_entries-service_resolver" |
||||
description: |- |
||||
The `service-resolver` config entry kind controls which service instances should satisfy Connect upstream discovery requests for a given service name. |
||||
--- |
||||
|
||||
# Service Resolver <sup>(beta)</sup> |
||||
|
||||
The `service-resolver` config entry kind controls which service instances |
||||
should satisfy Connect upstream discovery requests for a given service name. |
||||
|
||||
If no resolver config is defined the chain assumes 100% of traffic goes to the |
||||
healthy instances of the default service in the current datacenter+namespace |
||||
and discovery terminates. |
||||
|
||||
## Interaction with other Config Entries |
||||
|
||||
- Service resolver config entries are a component of [L7 Traffic |
||||
Management](/docs/connect/l7-traffic-management.html). |
||||
|
||||
## Sample Config Entries |
||||
|
||||
Create service subsets based on a version metadata and override the defaults: |
||||
|
||||
```hcl |
||||
kind = "service-resolver" |
||||
name = "web" |
||||
default_subset = "v1" |
||||
subsets = { |
||||
"v1" = { |
||||
filter = "Service.Meta.version == v1" |
||||
} |
||||
"v2" = { |
||||
filter = "Service.Meta.version == v2" |
||||
} |
||||
} |
||||
``` |
||||
|
||||
Expose a set of services in another datacenter as a virtual service: |
||||
|
||||
```hcl |
||||
kind = "service-resolver" |
||||
name = "web-dc2" |
||||
redirect { |
||||
service = "web" |
||||
datacenter = "dc2" |
||||
} |
||||
``` |
||||
|
||||
Enable failover for all subsets: |
||||
|
||||
```hcl |
||||
kind = "service-resolver" |
||||
name = "web" |
||||
connect_timeout = "15s" |
||||
failover = { |
||||
"*" = { |
||||
datacenters = ["dc3", "dc4"] |
||||
} |
||||
} |
||||
``` |
||||
|
||||
Representation of the defaults when a resolver is not configured: |
||||
|
||||
```hcl |
||||
kind = "service-resolver" |
||||
name = "web" |
||||
``` |
||||
|
||||
## Available Fields |
||||
|
||||
- `Kind` - Must be set to `service-resolver` |
||||
|
||||
- `Name` `(string: <required>)` - Set to the name of the service being configured. |
||||
|
||||
- `ConnectTimeout` `(duration: 0s)` - The timeout for establishing new network |
||||
connections to this service. |
||||
|
||||
- `DefaultSubset` `(string: "")` - The subset to use when no explicit subset is |
||||
requested. If empty the unnamed subset is used. |
||||
|
||||
- `Subsets` `(map[string]ServiceResolverSubset)` - A map of subset name to |
||||
subset definition for all usable named subsets of this service. The map key |
||||
is the name of the subset and all names must be valid DNS subdomain elements. |
||||
|
||||
This may be empty, in which case only the unnamed default subset will be |
||||
usable. |
||||
|
||||
- `Filter` `(string: "")` - The |
||||
[filter expression](/api/features/filtering.html) to be used for selecting |
||||
instances of the requested service. If empty all healthy instances are |
||||
returned. |
||||
|
||||
- `OnlyPassing` `(bool: false)` - Specifies the behavior of the resolver's |
||||
health check filtering. If this is set to false, the results will include |
||||
instances with checks in the passing as well as the warning states. If this |
||||
is set to true, only instances with checks in the passing state will be |
||||
returned. |
||||
|
||||
- `Redirect` `(ServiceResolverRedirect: <optional>)` - When configured, all |
||||
attempts to resolve the service this resolver defines will be substituted for |
||||
the supplied redirect EXCEPT when the redirect has already been applied. |
||||
|
||||
When substituting the supplied redirect into the all other fields besides |
||||
`Kind`, `Name`, and `Redirect` will be ignored. |
||||
|
||||
- `Service` `(string: "")` - A service to resolve instead of the current |
||||
service. |
||||
|
||||
- `ServiceSubset` `(string: "")` - A named subset of the given service to |
||||
resolve instead of one defined as that service's DefaultSubset If empty the |
||||
default subset is used. |
||||
|
||||
If this is specified at least one of Service, Datacenter, or Namespace |
||||
should be configured. |
||||
|
||||
- `Namespace` `(string: "")` - The namespace to resolve the service from |
||||
instead of the current one. |
||||
|
||||
- `Datacenter` `(string: "")` - The datacenter to resolve the service from |
||||
instead of the current one. |
||||
|
||||
- `Failover` `(map[string]ServiceResolverFailover`) - Controls when and how to |
||||
reroute traffic to an alternate pool of service instances. |
||||
|
||||
The map is keyed by the service subset it applies to and the special |
||||
string `"*"` is a wildcard that applies to any subset not otherwise |
||||
specified here. |
||||
|
||||
`Service`, `ServiceSubset`, `Namespace`, and `Datacenters` cannot all be |
||||
empty at once. |
||||
|
||||
- `Service` `(string: "")` - The service to resolve instead of the default as |
||||
the failover group of instances during failover. |
||||
|
||||
- `ServiceSubset` `(string: "")` - The named subset of the requested service |
||||
to resolve as the failover group of instances. If empty the default subset |
||||
for the requested service is used. |
||||
|
||||
- `Namespace` `(string: "")` - The namespace to resolve the requested service |
||||
from to form the failover group of instances. If empty the current |
||||
namespace is used. |
||||
|
||||
- `Datacenters` `(array<string>)` - A fixed list of datacenters to try during |
||||
failover. |
||||
|
||||
- `OverprovisioningFactor` `(int: 0)` - OverprovisioningFactor is a pass |
||||
through for envoy's |
||||
[`overprovisioning_factor`](https://www.envoyproxy.io/docs/envoy/v1.10.0/intro/arch_overview/load_balancing/priority) |
||||
value. |
||||
|
||||
If omitted the overprovisioning factor value will be set so high as to |
||||
imply binary failover (all or nothing). |
||||
|
||||
## Service Subsets |
||||
|
||||
A service subset assigns a concrete name to a specific subset of discoverable |
||||
service instances within a datacenter, such as `"version2"` or `"canary"`. |
||||
|
||||
A service subset name is useful only when composed with an actual service name, |
||||
a specific datacenter, and namespace. |
||||
|
||||
All services have an unnamed default subset that will return all healthy |
||||
instances unfiltered. |
||||
|
||||
Subsets are defined in `service-resolver` configuration entries, but are |
||||
referenced by their names throughout the other configuration entry kinds. |
||||
|
||||
## ACLs |
||||
|
||||
Configuration entries may be protected by |
||||
[ACLs](https://learn.hashicorp.com/consul/security-networking/production-acls). |
||||
|
||||
Reading a `service-resolver` config entry requires `service:read` on itself. |
||||
|
||||
Creating, updating, or deleting a `service-resolver` config entry requires |
||||
`service:write` on itself and `service:read` on any other service referenced by |
||||
name in these fields: |
||||
|
||||
- [`Redirect.Service`](#service) |
||||
|
||||
- [`Failover[].Service`](#service-1) |
||||
|
||||
@ -0,0 +1,233 @@
|
||||
--- |
||||
layout: "docs" |
||||
page_title: "Configuration Entry Kind: Service Router (beta)" |
||||
sidebar_current: "docs-agent-cfg_entries-service_router" |
||||
description: |- |
||||
The service-router config entry kind controls Connect traffic routing and manipulation at networking layer 7 (e.g. HTTP). |
||||
--- |
||||
|
||||
# Service Router <sup>(beta)</sup> |
||||
|
||||
The `service-router` config entry kind controls Connect traffic routing and |
||||
manipulation at networking layer 7 (e.g. HTTP). |
||||
|
||||
If a router is not explicitly configured or is configured with no routes then |
||||
the system behaves as if a router were configured sending all traffic to a |
||||
service of the same name. |
||||
|
||||
## Interaction with other Config Entries |
||||
|
||||
- Service router config entries are a component of [L7 Traffic |
||||
Management](/docs/connect/l7-traffic-management.html). |
||||
|
||||
- Service router config entries are restricted to only services that define |
||||
their protocol as http-based via a corresponding |
||||
[`service-defaults`](/docs/agent/config-entries/service-defaults.html) config |
||||
entry or globally via |
||||
[`proxy-defaults`](/docs/agent/config-entries/proxy-defaults.html) . |
||||
|
||||
- Any route destination that omits the `ServiceSubset` field is eligible for |
||||
splitting via a |
||||
[`service-splitter`](/docs/agent/config-entries/service-splitter.html) should |
||||
one be configured for that service, otherwise resolution proceeds according |
||||
to any configured |
||||
[`service-resolver`](/docs/agent/config-entries/service-resolver.html). |
||||
|
||||
## Sample Config Entries |
||||
|
||||
Route HTTP requests with a path starting with `/admin` to a different service: |
||||
|
||||
```hcl |
||||
kind = "service-router" |
||||
name = "web" |
||||
routes = [ |
||||
{ |
||||
match { |
||||
http { |
||||
path_prefix = "/admin" |
||||
} |
||||
} |
||||
|
||||
destination { |
||||
service = "admin" |
||||
} |
||||
}, |
||||
# NOTE: a default catch-all will send unmatched traffic to "web" |
||||
] |
||||
``` |
||||
|
||||
Route HTTP requests with a special url parameter or header to a canary subset: |
||||
|
||||
```hcl |
||||
kind = "service-router" |
||||
name = "web" |
||||
routes = [ |
||||
{ |
||||
match { |
||||
http { |
||||
header = [ |
||||
{ |
||||
name = "x-debug" |
||||
exact = "1" |
||||
}, |
||||
] |
||||
} |
||||
} |
||||
destination { |
||||
service = "web" |
||||
service_subset = "canary" |
||||
} |
||||
}, |
||||
{ |
||||
match { |
||||
http { |
||||
query_param = [ |
||||
{ |
||||
name = "x-debug" |
||||
value = "1" |
||||
}, |
||||
] |
||||
} |
||||
} |
||||
destination { |
||||
service = "web" |
||||
service_subset = "canary" |
||||
} |
||||
}, |
||||
# NOTE: a default catch-all will send unmatched traffic to "web" |
||||
] |
||||
``` |
||||
|
||||
## Available Fields |
||||
|
||||
- `Kind` - Must be set to `service-router` |
||||
|
||||
- `Name` `(string: <required>)` - Set to the name of the service being configured. |
||||
|
||||
- `Routes` `(array<ServiceRoute>)` - The list of routes to consider when |
||||
processing L7 requests. The first route to match in the list is terminal and |
||||
stops further evaluation. Traffic that fails to match any of the provided |
||||
routes will be routed to the default service. |
||||
|
||||
- `Match` `(ServiceRouteMatch: <optional>)` - A set of criteria that can |
||||
match incoming L7 requests. If empty or omitted it acts as a catch-all. |
||||
|
||||
- `HTTP` `(ServiceRouteHTTPMatch: <optional>)` - A set of http-specific match criteria. |
||||
|
||||
- `PathExact` `(string: "")` - Exact path to match on the HTTP request path. |
||||
|
||||
At most only one of `PathExact`, `PathPrefix`, or `PathRegex` may be configured. |
||||
|
||||
- `PathPrefix` `(string: "")` - Path prefix to match on the HTTP request path. |
||||
|
||||
At most only one of `PathExact`, `PathPrefix`, or `PathRegex` may be configured. |
||||
|
||||
- `PathRegex` `(string: "")` - Regular expression to match on the HTTP |
||||
request path. |
||||
|
||||
The syntax when using the Envoy proxy is [documented here](https://en.cppreference.com/w/cpp/regex/ecmascript). |
||||
|
||||
At most only one of `PathExact`, `PathPrefix`, or `PathRegex` may be configured. |
||||
|
||||
- `Header` `(array<ServiceRouteHTTPMatchHeader>)` - A set of criteria |
||||
that can match on HTTP request headers. If more than one is configured |
||||
all must match for the overall match to apply. |
||||
|
||||
- `Name` `(string: <required>)` - Name of the header to match on. |
||||
|
||||
- `Present` `(bool: false)` - Match if the header with the given name |
||||
is present with any value. |
||||
|
||||
At most only one of `Exact`, `Prefix`, `Suffix`, `Regex`, or |
||||
`Present` may be configured. |
||||
|
||||
- `Exact` `(string: "")` - Match if the header with the given name is |
||||
this value. |
||||
|
||||
At most only one of `Exact`, `Prefix`, `Suffix`, `Regex`, or |
||||
`Present` may be configured. |
||||
|
||||
- `Prefix` `(string: "")` - Match if the header with the given name has |
||||
this prefix. |
||||
|
||||
At most only one of `Exact`, `Prefix`, `Suffix`, `Regex`, or |
||||
`Present` may be configured. |
||||
|
||||
- `Suffix` `(string: "")` - Match if the header with the given name has |
||||
this suffix. |
||||
|
||||
At most only one of `Exact`, `Prefix`, `Suffix`, `Regex`, or |
||||
`Present` may be configured. |
||||
|
||||
- `Regex` `(string: "")` - Match if the header with the given name |
||||
matches this pattern. |
||||
|
||||
The syntax when using the Envoy proxy is [documented here](https://en.cppreference.com/w/cpp/regex/ecmascript). |
||||
|
||||
At most only one of `Exact`, `Prefix`, `Suffix`, `Regex`, or |
||||
`Present` may be configured. |
||||
|
||||
- `Invert` `(bool: false)` - Inverts the logic of the match. |
||||
|
||||
- `QueryParam` `(array<ServiceRouteHTTPMatchQueryParam>)` - A set of |
||||
criteria that can match on HTTP query parameters. If more than one is |
||||
configured all must match for the overall match to apply. |
||||
|
||||
- `Name` `(string: <required>)` - The name of the query parameter to |
||||
match on. |
||||
|
||||
- `Value` `(string: <required>)` - String to match against the query |
||||
parameter value. The behavior changes with the definition of the |
||||
`Regex` field. |
||||
|
||||
- `Regex` `(bool: false)` - Controls how the `Value` field is used. If |
||||
`Regex` is `false` then `Value` matches exactly. If `Regex` is |
||||
`true` then `Value` matches as a regular expression pattern. |
||||
|
||||
The syntax when using the Envoy proxy is [documented |
||||
here](https://en.cppreference.com/w/cpp/regex/ecmascript). |
||||
|
||||
- `Destination` `(ServiceRouteDestination: <optional>)` - Controls how to |
||||
proxy the actual matching request to a service. |
||||
|
||||
- `Service` `(string: "")` - The service to resolve instead of the default |
||||
service. If empty then the default service name is used. |
||||
|
||||
- `ServiceSubset` `(string: "")` - A named subset of the given service to |
||||
resolve instead of one defined as that service's `DefaultSubset`. If |
||||
empty the default subset is used. |
||||
|
||||
- `Namespace` `(string: "")` - The namespace to resolve the service from |
||||
instead of the current namespace. If empty the current namespace is |
||||
assumed. |
||||
|
||||
- `PrefixRewrite` `(string: "")` - Defines how to rewrite the http request |
||||
path before proxying it to its final destination. |
||||
|
||||
This requires that either `Match.HTTP.PathPrefix` or |
||||
`Match.HTTP.PathExact` be configured on this route. |
||||
|
||||
- `RequestTimeout` `(duration: 0s)` - The total amount of time permitted |
||||
for the entire downstream request (and retries) to be processed. |
||||
|
||||
- `NumRetries` `(int: 0)` - The number of times to retry the request when a |
||||
retryable result occurs. |
||||
|
||||
- `RetryOnConnectFailure` `(bool: false)` - Allows for connection failure |
||||
errors to trigger a retry. |
||||
|
||||
- `RetryOnStatusCodes` `(array<int>)` - A flat list of http response status |
||||
codes that are eligible for retry. |
||||
|
||||
## ACLs |
||||
|
||||
Configuration entries may be protected by |
||||
[ACLs](https://learn.hashicorp.com/consul/security-networking/production-acls). |
||||
|
||||
Reading a `service-router` config entry requires `service:read` on itself. |
||||
|
||||
Creating, updating, or deleting a `service-router` config entry requires |
||||
`service:write` on itself and `service:read` on any other service referenced by |
||||
name in these fields: |
||||
|
||||
- [`Routes[].Destination.Service`](#service) |
||||
@ -0,0 +1,108 @@
|
||||
--- |
||||
layout: "docs" |
||||
page_title: "Configuration Entry Kind: Service Splitter (beta)" |
||||
sidebar_current: "docs-agent-cfg_entries-service_splitter" |
||||
description: |- |
||||
The service-splitter config entry kind controls how to split incoming Connect 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). |
||||
--- |
||||
|
||||
# Service Splitter <sup>(beta)</sup> |
||||
|
||||
The `service-splitter` config entry kind controls how to split incoming Connect |
||||
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). |
||||
|
||||
If no splitter config is defined for a service it is assumed 100% of traffic |
||||
flows to a service with the same name and discovery continues on to the |
||||
resolution stage. |
||||
|
||||
## Interaction with other Config Entries |
||||
|
||||
- Service splitter config entries are a component of [L7 Traffic |
||||
Management](/docs/connect/l7-traffic-management.html). |
||||
|
||||
- Service splitter config entries are restricted to only services that define |
||||
their protocol as http-based via a corresponding |
||||
[`service-defaults`](/docs/agent/config-entries/service-defaults.html) config |
||||
entry or globally via |
||||
[`proxy-defaults`](/docs/agent/config-entries/proxy-defaults.html) . |
||||
|
||||
- Any split destination that specifies a different `Service` field and omits |
||||
the `ServiceSubset` field is eligible for further splitting should a splitter |
||||
be configured for that other service, otherwise resolution proceeds according |
||||
to any configured |
||||
[`service-resolver`](/docs/agent/config-entries/service-resolver.html). |
||||
|
||||
## Sample Config Entries |
||||
|
||||
Split traffic between two subsets of the same service: |
||||
|
||||
```hcl |
||||
kind = "service-splitter" |
||||
name = "web" |
||||
splits = [ |
||||
{ |
||||
weight = 90 |
||||
service_subset = "v1" |
||||
}, |
||||
{ |
||||
weight = 10 |
||||
service_subset = "v2" |
||||
}, |
||||
] |
||||
``` |
||||
|
||||
Split traffic between two services: |
||||
|
||||
```hcl |
||||
kind = "service-splitter" |
||||
name = "web" |
||||
splits = [ |
||||
{ |
||||
weight = 50 |
||||
# will default to service with same name as config entry ("web") |
||||
}, |
||||
{ |
||||
weight = 10 |
||||
service = "web-rewrite" |
||||
}, |
||||
] |
||||
``` |
||||
|
||||
## Available Fields |
||||
|
||||
- `Kind` - Must be set to `service-splitter` |
||||
|
||||
- `Name` `(string: <required>)` - Set to the name of the service being configured. |
||||
|
||||
- `Splits` `(array<ServiceSplit>)` - Defines how much traffic to send to which |
||||
set of service instances during a traffic split. The sum of weights across |
||||
all splits must add up to 100. |
||||
|
||||
- `Weight` `(float32: 0)` - A value between 0 and 100 reflecting what portion |
||||
of traffic should be directed to this split. The smallest representable |
||||
weight is 1/10000 or .01% |
||||
|
||||
- `Service` `(string: "")` - The service to resolve instead of the default. |
||||
|
||||
- `ServiceSubset` `(string: "")` - A named subset of the given service to |
||||
resolve instead of one defined as that service's `DefaultSubset`. If empty |
||||
the default subset is used. |
||||
|
||||
- `Namespace` `(string: "")` - The namespace to resolve the service from |
||||
instead of the current namespace. If empty the current namespace is |
||||
assumed. |
||||
|
||||
## ACLs |
||||
|
||||
Configuration entries may be protected by |
||||
[ACLs](https://learn.hashicorp.com/consul/security-networking/production-acls). |
||||
|
||||
Reading a `service-splitter` config entry requires `service:read` on itself. |
||||
|
||||
Creating, updating, or deleting a `service-splitter` config entry requires |
||||
`service:write` on itself and `service:read` on any other service referenced by |
||||
name in these fields: |
||||
|
||||
- [`Splits[].Service`](#service) |
||||
@ -0,0 +1,118 @@
|
||||
--- |
||||
layout: "docs" |
||||
page_title: "Connect - L7 Traffic Management (beta)" |
||||
sidebar_current: "docs-connect-l7_traffic_management" |
||||
description: |- |
||||
Layer 7 traffic management allows operators to divide L7 traffic between different subsets of service instances when using Connect. |
||||
--- |
||||
|
||||
# L7 Traffic Management <sup>(beta)</sup> |
||||
|
||||
-> **Note:** This feature is not compatible with the |
||||
[built-in proxy](/docs/connect/proxies/built-in.html) |
||||
or [native proxies](/docs/connect/native.html). |
||||
|
||||
Layer 7 traffic management allows operators to divide L7 traffic between |
||||
different |
||||
[subsets](/docs/agent/config-entries/service-resolver.html#service-subsets) of |
||||
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. |
||||
|
||||
## Stages |
||||
|
||||
Connect proxy upstreams are discovered using a series of stages: routing, |
||||
splitting, and resolution. These stages represent different ways of managing L7 |
||||
traffic. |
||||
|
||||
 |
||||
|
||||
Each stage of this discovery process can be dynamically reconfigured via various |
||||
[configuration entries](/docs/agent/config_entries.html). When a configuration |
||||
entry is missing, that stage will fall back on reasonable default behavior. |
||||
|
||||
### Routing |
||||
|
||||
A [`service-router`](/docs/agent/config-entries/service-router.html) config |
||||
entry kind is the first configurable stage. |
||||
|
||||
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. |
||||
|
||||
[Examples](/docs/agent/config-entries/service-router.html#sample-config-entries) |
||||
can be found in the `service-router` documentation. |
||||
|
||||
### Splitting |
||||
|
||||
A [`service-splitter`](/docs/agent/config-entries/service-splitter.html) config |
||||
entry kind is the next stage after routing. |
||||
|
||||
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: |
||||
|
||||
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% |
||||
|
||||
[Examples](/docs/agent/config-entries/service-splitter.html#sample-config-entries) |
||||
can be found in the `service-splitter` documentation. |
||||
|
||||
### Resolution |
||||
|
||||
A [`service-resolver`](/docs/agent/config-entries/service-resolver.html) config |
||||
entry kind is the last stage. |
||||
|
||||
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 |
||||
datacenter are unhealthy. |
||||
|
||||
- Configure service subsets based on `Service.Meta.version` values. |
||||
|
||||
- Send all traffic for `web` that does not specify a service subset to the |
||||
`version1` subset. |
||||
|
||||
- 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` |
||||
in `dc2`. This can be referenced in upstreams or in other config entries. |
||||
|
||||
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. |
||||
|
||||
[Examples](/docs/agent/config-entries/service-resolver.html#sample-config-entries) |
||||
can be found in the `service-resolver` documentation. |
||||
|
||||
-> **Note:** `service-resolver` config entries kinds function at L4 (unlike |
||||
`service-router` and `service-splitter` kinds). These can be created for |
||||
services of any protocol such as `tcp`. |
||||
Loading…
Reference in new issue