From 65fc93ea33de5f163610794bc4cdc8a2c420c9e2 Mon Sep 17 00:00:00 2001 From: "R.B. Boyer" Date: Wed, 21 Aug 2019 12:17:38 -0500 Subject: [PATCH] docs: fixing L7 config entries documentation (#6358) - add service-router example involving gRPC - fix indentation on service-router page by splitting it up - remove reference to removed setting --- .../config-entries/service-resolver.html.md | 8 - .../config-entries/service-router.html.md | 184 ++++++++++-------- 2 files changed, 105 insertions(+), 87 deletions(-) diff --git a/website/source/docs/agent/config-entries/service-resolver.html.md b/website/source/docs/agent/config-entries/service-resolver.html.md index b37f781c1d..7c17a7caeb 100644 --- a/website/source/docs/agent/config-entries/service-resolver.html.md +++ b/website/source/docs/agent/config-entries/service-resolver.html.md @@ -146,14 +146,6 @@ name = "web" - `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 diff --git a/website/source/docs/agent/config-entries/service-router.html.md b/website/source/docs/agent/config-entries/service-router.html.md index 5fd84e9c46..c67d5d5a53 100644 --- a/website/source/docs/agent/config-entries/service-router.html.md +++ b/website/source/docs/agent/config-entries/service-router.html.md @@ -98,6 +98,28 @@ routes = [ ] ``` +Re-route a gRPC method to another service. Since gRPC method calls [are +HTTP2](https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-HTTP2.md), we can use an HTTP path match rule to re-route traffic: + +```hcl +kind = "service-router" +name = "billing" +routes = [ + { + match { + http { + path_exact = "/mycompany.BillingService/GenerateInvoice" + } + } + + destination { + service = "invoice-generator" + } + }, + # NOTE: a default catch-all will send unmatched traffic to "billing" +] +``` + ## Available Fields - `Kind` - Must be set to `service-router` @@ -109,124 +131,128 @@ routes = [ 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. + - `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. + - `HTTP` `(ServiceRouteHTTPMatch: )` - A set of + [http-specific match criteria](#serviceroutehttpmatch). - - `PathExact` `(string: "")` - Exact path to match on the HTTP request path. + - `Destination` `(ServiceRouteDestination: )` - Controls [how to + proxy](#serviceroutedestination) the matching request(s) to a + service. - At most only one of `PathExact`, `PathPrefix`, or `PathRegex` may be configured. +### `ServiceRouteHTTPMatch` - - `PathPrefix` `(string: "")` - Path prefix to match on the HTTP request path. +- `PathExact` `(string: "")` - Exact path to match on the HTTP request path. - At most only one of `PathExact`, `PathPrefix`, or `PathRegex` may be configured. + 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. +- `PathPrefix` `(string: "")` - Path prefix to match on the HTTP request path. - - `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. + At most only one of `PathExact`, `PathPrefix`, or `PathRegex` may be configured. - - `Name` `(string: )` - Name of the header to match on. +- `PathRegex` `(string: "")` - Regular expression to match on the HTTP + request path. - - `Present` `(bool: false)` - Match if the header with the given name - is present with any value. + 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. + At most only one of `PathExact`, `PathPrefix`, or `PathRegex` may be configured. - - `Exact` `(string: "")` - Match if the header with the given name is - this value. +- `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. - At most only one of `Exact`, `Prefix`, `Suffix`, `Regex`, or - `Present` may be configured. + - `Name` `(string: )` - Name of the header to match. - - `Prefix` `(string: "")` - Match if the header with the given name has - this prefix. + - `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. + 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. + - `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. + 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. + - `Prefix` `(string: "")` - Match if the header with the given name has + this prefix. - 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. - 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. - - `Invert` `(bool: false)` - Inverts the logic of the match. + At most only one of `Exact`, `Prefix`, `Suffix`, `Regex`, or `Present` + may be configured. - - `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. + - `Regex` `(string: "")` - Match if the header with the given name matches + this pattern. - - `Name` `(string: )` - The name of the query parameter to - match on. + The syntax when using the Envoy proxy is [documented here](https://en.cppreference.com/w/cpp/regex/ecmascript). - - `Present` `(bool: false)` - Match if the query parameter with the given name - is present with any value. + At most only one of `Exact`, `Prefix`, `Suffix`, `Regex`, or `Present` + may be configured. - At most only one of `Exact`, `Regex`, or `Present` may be configured. + - `Invert` `(bool: false)` - Inverts the logic of the match. - - `Exact` `(string: "")` - Match if the query parameter with the given - name is this value. +- `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. - At most only one of `Exact`, `Regex`, or `Present` may be configured. - - - `Regex` `(string: "")` - Match if the query parameter with the given - name matches this pattern. + - `Name` `(string: )` - The name of the query parameter to match on. - The syntax when using the Envoy proxy is [documented here](https://en.cppreference.com/w/cpp/regex/ecmascript). + - `Present` `(bool: false)` - Match if the query parameter with the given + name is present with any value. - At most only one of `Exact`, `Regex`, or `Present` may be configured. + At most only one of `Exact`, `Regex`, or `Present` may be configured. - - `Methods` `(array)` - A list of HTTP methods for which this match - applies. If unspecified all http methods are matched. + - `Exact` `(string: "")` - Match if the query parameter with the given name + is this value. - - `Destination` `(ServiceRouteDestination: )` - Controls how to - proxy the actual matching request to a service. + At most only one of `Exact`, `Regex`, or `Present` may be configured. - - `Service` `(string: "")` - The service to resolve instead of the default - service. If empty then the default service name is used. + - `Regex` `(string: "")` - Match if the query parameter with the given name + matches this pattern. - - `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. + The syntax when using the Envoy proxy is [documented here](https://en.cppreference.com/w/cpp/regex/ecmascript). - - `Namespace` `(string: "")` - The namespace to resolve the service from - instead of the current namespace. If empty the current namespace is - assumed. + At most only one of `Exact`, `Regex`, or `Present` may be configured. - - `PrefixRewrite` `(string: "")` - Defines how to rewrite the http request - path before proxying it to its final destination. +- `Methods` `(array)` - A list of HTTP methods for which this match + applies. If unspecified all http methods are matched. - This requires that either `Match.HTTP.PathPrefix` or - `Match.HTTP.PathExact` be configured on this route. +### `ServiceRouteDestination` - - `RequestTimeout` `(duration: 0s)` - The total amount of time permitted - for the entire downstream request (and retries) to be processed. +- `Service` `(string: "")` - The service to resolve instead of the default + service. If empty then the default service name is used. - - `NumRetries` `(int: 0)` - The number of times to retry the request when a - retryable result occurs. +- `ServiceSubset` `(string: "")` - A named subset of the given service to + resolve instead of the one defined as that service's `DefaultSubset`. If empty, + the default subset is used. - - `RetryOnConnectFailure` `(bool: false)` - Allows for connection failure - errors to trigger a retry. +- `Namespace` `(string: "")` - The namespace to resolve the service from + instead of the current namespace. If empty the current namespace is assumed. - - `RetryOnStatusCodes` `(array)` - A flat list of http response status - codes that are eligible for retry. +- `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