From edd0d4be5ac13f00e7b071e6542266b6e54a45eb Mon Sep 17 00:00:00 2001 From: "R.B. Boyer" Date: Mon, 8 Jul 2019 21:11:19 -0500 Subject: [PATCH] Initial L7 Documentation (#6056) --- website/raw-assets/l7-traffic-stages.fig | Bin 0 -> 12890 bytes .../assets/images/l7-traffic-stages.svg | 49 ++++ .../config-entries/proxy-defaults.html.md | 60 +++++ .../config-entries/service-defaults.html.md | 46 ++++ .../config-entries/service-resolver.html.md | 185 ++++++++++++++ .../config-entries/service-router.html.md | 233 ++++++++++++++++++ .../config-entries/service-splitter.html.md | 108 ++++++++ .../source/docs/agent/config_entries.html.md | 56 +---- .../connect/l7-traffic-management.html.md | 118 +++++++++ .../source/docs/connect/observability.html.md | 4 +- website/source/docs/connect/proxies/envoy.md | 14 +- website/source/layouts/docs.erb | 33 ++- 12 files changed, 847 insertions(+), 59 deletions(-) create mode 100644 website/raw-assets/l7-traffic-stages.fig create mode 100644 website/source/assets/images/l7-traffic-stages.svg create mode 100644 website/source/docs/agent/config-entries/proxy-defaults.html.md create mode 100644 website/source/docs/agent/config-entries/service-defaults.html.md create mode 100644 website/source/docs/agent/config-entries/service-resolver.html.md create mode 100644 website/source/docs/agent/config-entries/service-router.html.md create mode 100644 website/source/docs/agent/config-entries/service-splitter.html.md create mode 100644 website/source/docs/connect/l7-traffic-management.html.md diff --git a/website/raw-assets/l7-traffic-stages.fig b/website/raw-assets/l7-traffic-stages.fig new file mode 100644 index 0000000000000000000000000000000000000000..7907af8e2bb680471c2f66f6df94a84a73a74b62 GIT binary patch literal 12890 zcmV-gGNsLCX=g2KX?JM>0001y6953UTI+)&SyjKcl1{(oxw|YYA|fIpD$cHmfQVEl zm852pRJN+pJ+rPGs*_5mc9K-As`N~+h=}+?L_|bHMMOkIMMOkJd@G{zNBKMVQIGCk z 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 Ef + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/website/source/docs/agent/config-entries/proxy-defaults.html.md b/website/source/docs/agent/config-entries/proxy-defaults.html.md new file mode 100644 index 0000000000..ba847bbb23 --- /dev/null +++ b/website/source/docs/agent/config-entries/proxy-defaults.html.md @@ -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`. diff --git a/website/source/docs/agent/config-entries/service-defaults.html.md b/website/source/docs/agent/config-entries/service-defaults.html.md new file mode 100644 index 0000000000..680276c74c --- /dev/null +++ b/website/source/docs/agent/config-entries/service-defaults.html.md @@ -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: )` - 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` + (beta)](/docs/agent/config-entries/service-splitter.html) and + [`service-router` + (beta)](/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. diff --git a/website/source/docs/agent/config-entries/service-resolver.html.md b/website/source/docs/agent/config-entries/service-resolver.html.md new file mode 100644 index 0000000000..d0a6a782d9 --- /dev/null +++ b/website/source/docs/agent/config-entries/service-resolver.html.md @@ -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 (beta) + +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: )` - 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: )` - 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)` - 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) + diff --git a/website/source/docs/agent/config-entries/service-router.html.md b/website/source/docs/agent/config-entries/service-router.html.md new file mode 100644 index 0000000000..59860b6597 --- /dev/null +++ b/website/source/docs/agent/config-entries/service-router.html.md @@ -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 (beta) + +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: )` - Set to the name of the service being configured. + +- `Routes` `(array)` - 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: )` - A set of criteria that can + match incoming L7 requests. If empty or omitted it acts as a catch-all. + + - `HTTP` `(ServiceRouteHTTPMatch: )` - 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)` - 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: )` - 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)` - 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: )` - The name of the query parameter to + match on. + + - `Value` `(string: )` - 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: )` - 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)` - 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) diff --git a/website/source/docs/agent/config-entries/service-splitter.html.md b/website/source/docs/agent/config-entries/service-splitter.html.md new file mode 100644 index 0000000000..778d24cf48 --- /dev/null +++ b/website/source/docs/agent/config-entries/service-splitter.html.md @@ -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 (beta) + +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: )` - Set to the name of the service being configured. + +- `Splits` `(array)` - 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) diff --git a/website/source/docs/agent/config_entries.html.md b/website/source/docs/agent/config_entries.html.md index 4135a33c26..7a6323e2ab 100644 --- a/website/source/docs/agent/config_entries.html.md +++ b/website/source/docs/agent/config_entries.html.md @@ -12,7 +12,8 @@ Configuration entries can be created to provide cluster-wide defaults for various aspects of Consul. Every configuration entry has at least two fields: `Kind` and `Name`. Those two fields are used to uniquely identify a configuration entry. When put into configuration files, configuration entries -can be specified as HCL or JSON objects. +can be specified as HCL or JSON objects using either `snake_case` or `CamelCase` +for key names. Example: @@ -21,53 +22,22 @@ Kind = "" Name = "" ``` -The two supported `Kind` configuration entries are detailed below. +The supported `Kind` names for configuration entries are: -## Configuration Entry Kinds +* [`service-router` (beta)](/docs/agent/config-entries/service-router.html) - defines +where to send layer 7 traffic based on the HTTP route -### Proxy Defaults - `proxy-defaults` +* [`service-splitter` (beta)](/docs/agent/config-entries/service-splitter.html) - defines +how to divide requests for a single HTTP route based on percentages -Proxy defaults allow for configuring global config defaults across all services -for Connect proxy configuration. Currently, only one global entry is supported. +* [`service-resolver` (beta)](/docs/agent/config-entries/service-resolver.html) - matches +service instances with a specific Connect upstream discovery requests -```hcl -Kind = "proxy-defaults" -Name = "global" -Config { - local_connect_timeout_ms = 1000 - handshake_timeout_ms = 10000 -} -``` - -* `Kind` - Must be set to `proxy-defaults` - -* `Name` - Must be set to `global` - -* `Config` - 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 Builtin Proxy](/docs/connect/proxies/built-in.html) - -### Service Defaults - `service-defaults` - -Service defaults control default global values for a service, such as its -protocol. - -```hcl -Kind = "service-defaults" -Name = "web" -Protocol = "http" -``` - -* `Kind` - Must be set to `service-defaults` - -* `Name` - Set to the name of the service being configured. +* [`service-defaults`](/docs/agent/config-entries/service-defaults.html) - configures +defaults for all the instances of a given service -* `Protocol` - Sets the protocol of the service. This is used by Connect proxies - for things like observability features. +* [`proxy-defaults`](/docs/agent/config-entries/proxy-defaults.html) - controls +proxy configuration ## Managing Configuration Entries diff --git a/website/source/docs/connect/l7-traffic-management.html.md b/website/source/docs/connect/l7-traffic-management.html.md new file mode 100644 index 0000000000..0a2b2fa04a --- /dev/null +++ b/website/source/docs/connect/l7-traffic-management.html.md @@ -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 (beta) + +-> **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. + +![diagram showing l7 traffic discovery stages: routing to splitting to resolution](/assets/images/l7-traffic-stages.svg) + +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`. diff --git a/website/source/docs/connect/observability.html.md b/website/source/docs/connect/observability.html.md index 84af9b2b10..680655b662 100644 --- a/website/source/docs/connect/observability.html.md +++ b/website/source/docs/connect/observability.html.md @@ -7,7 +7,7 @@ description: |- Consul Connect. --- -## Observability +# Observability In order to take advantage of Connect's L7 observability features you will need to: @@ -44,7 +44,7 @@ Find other possible metrics syncs in the [Connect Envoy documentation](/docs/con ### Service Protocol -You can specify the [service protocol](/docs/agent/config_entries.html#protocol) +You can specify the [service protocol](/docs/agent/config-entries/service-defaults.html#protocol) in the `service-defaults` configuration entry. You can override it in the [service registration](/docs/agent/services.html). By default, proxies only give you L4 metrics. This protocol allows proxies to handle requests at the right L7 diff --git a/website/source/docs/connect/proxies/envoy.md b/website/source/docs/connect/proxies/envoy.md index 5f6dd44654..7afac49f85 100644 --- a/website/source/docs/connect/proxies/envoy.md +++ b/website/source/docs/connect/proxies/envoy.md @@ -95,7 +95,7 @@ the ability to control some parts of the bootstrap config via proxy configuration options. Users can add the following configuration items to the [global `proxy-defaults` -configuration entry](/docs/agent/config_entries.html#proxy-defaults-proxy-defaults) or override them directly in the `proxy.config` field +configuration entry](/docs/agent/config-entries/proxy-defaults.html) or override them directly in the `proxy.config` field of a [proxy service definition](/docs/connect/registration/service-registration.html) or [`sidecar_service`](/docs/connect/registration/sidecar-service.html) block. @@ -104,7 +104,7 @@ definition](/docs/connect/registration/service-registration.html) or StatsD listener that Envoy should deliver metrics to. For example, this may be `udp://127.0.0.1:8125` if every host has a local StatsD listener. In this case users can configure this property once in the [global `proxy-defaults` -configuration entry](/docs/agent/config_entries.html#proxy-defaults-proxy-defaults) for convenience. Currently, TCP is not supported. +configuration entry](/docs/agent/config-entries/proxy-defaults.html) for convenience. Currently, TCP is not supported. ~> **Note:** currently the url **must use an ip address** not a dns name due to the way Envoy is setup for StatsD. @@ -115,7 +115,7 @@ configuration entry](/docs/agent/config_entries.html#proxy-defaults-proxy-defaul pod in a Kubernetes cluster to learn of a pod-specific IP address for StatsD when the Envoy instance is bootstrapped while still allowing global configuration of all proxies to use StatsD in the [global `proxy-defaults` -configuration entry](/docs/agent/config_entries.html#proxy-defaults-proxy-defaults). The env variable must contain a full valid URL +configuration entry](/docs/agent/config-entries/proxy-defaults.html). The env variable must contain a full valid URL value as specified above and nothing else. It is not currently possible to use environment variables as only part of the URL. @@ -153,7 +153,7 @@ to configure appropriate proxy settings for that service's proxies and also for the upstream listeners of any downstream service. Users can define a service's protocol in its [`service-defaults` configuration -entry](/docs/agent/config_entries.html#service-defaults-service-defaults). Agents with +entry](/docs/agent/config-entries/service-defaults.html). Agents with [`enable_central_service_config`](/docs/agent/options.html#enable_central_service_config) set to true will automatically discover the protocol when configuring a proxy for a service. The proxy will discover the main protocol of the service it @@ -171,7 +171,7 @@ actually registered. These fields may also be overridden explicitly in the [proxy service definition](/docs/connect/registration/service-registration.html), or defined in the [global `proxy-defaults` configuration -entry](/docs/agent/config_entries.html#proxy-defaults-proxy-defaults) to act as +entry](/docs/agent/config-entries/proxy-defaults.html) to act as defaults that are inherited by all services. @@ -282,7 +282,7 @@ with no `@type` field. Users may add the following configuration items to the [global `proxy-defaults` configuration -entry](/docs/agent/config_entries.html#proxy-defaults-proxy-defaults) or +entry](/docs/agent/config-entries/proxy-defaults.html) or override them directly in the `proxy.config` field of a [proxy service definition](/docs/connect/registration/service-registration.html) or [`sidecar_service`](/docs/connect/registration/sidecar-service.html) block. @@ -318,7 +318,7 @@ definition](/docs/connect/registration/service-registration.html) or Users may add the following configuration items to the [global `proxy-defaults` configuration -entry](/docs/agent/config_entries.html#proxy-defaults-proxy-defaults) or +entry](/docs/agent/config-entries/proxy-defaults.html) or override them directly in the `proxy.config` field of a [proxy service definition](/docs/connect/registration/service-registration.html) or [`sidecar_service`](/docs/connect/registration/sidecar-service.html) block. diff --git a/website/source/layouts/docs.erb b/website/source/layouts/docs.erb index 00fe1956b3..0063822e12 100644 --- a/website/source/layouts/docs.erb +++ b/website/source/layouts/docs.erb @@ -414,6 +414,23 @@ > Configuration Entries + > Cloud Auto-join @@ -477,13 +494,15 @@ > Observability - - > - Intentions - Security Policies - - > - Architecture - + > + L7 Traffic Management (beta) + + > + Intentions - Security Policies + + > + Architecture + > Supported Proxies