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
hashicorp · Aug 21, 2019 · 65fc93e · 65fc93e
1 parent 33c09f8
commit 65fc93e
Show file tree

Hide file tree

Showing 2 changed files with 105 additions and 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
@@ -146,14 +146,6 @@ name = "web"
   - `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

diff --git 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: <optional>)` - A set of criteria that can
-    match incoming L7 requests. If empty or omitted it acts as a catch-all.
+    - `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](#serviceroutehttpmatch).
+
+    - `Destination` `(ServiceRouteDestination: <optional>)` - Controls [how to
+      proxy](#serviceroutedestination) the matching request(s) to a
+      service.
+
+### `ServiceRouteHTTPMatch`
+
+- `PathExact` `(string: "")` - Exact path to match on the HTTP request path.
+
+    At most only one of `PathExact`, `PathPrefix`, or `PathRegex` may be configured.
 
-    - `HTTP` `(ServiceRouteHTTPMatch: <optional>)` - A set of http-specific match criteria.
+- `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.
 
-      - `PathPrefix` `(string: "")` - Path prefix 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.
+      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.
 
-      - `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.
 
-        - `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.
 
-        - `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.
+    - `Exact` `(string: "")` - Match if the header with the given name is this
+      value.
 
-        - `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.
+    - `Prefix` `(string: "")` - Match if the header with the given name has
+      this prefix.
 
-        - `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.
 
-            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.
 
-        - `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.
 
-            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.
 
-        - `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).
 
-            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.
+    - `Invert` `(bool: false)` - Inverts the logic of the match.
 
-        - `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.
 
-      - `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.
 
-        - `Name` `(string: <required>)` - The name of the query parameter to
-          match on.
+    - `Present` `(bool: false)` - Match if the query parameter with the given
+      name is present with any value.
 
-        - `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.
+    - `Exact` `(string: "")` - Match if the query parameter with the given name
+      is this value.
 
-        - `Exact` `(string: "")` - Match if the query parameter with the given
-          name is this 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.
-
-        - `Regex` `(string: "")` - Match if the query parameter with the given
-          name matches this pattern.
+    - `Regex` `(string: "")` - Match if the query parameter 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).
+        The syntax when using the Envoy proxy is [documented here](https://en.cppreference.com/w/cpp/regex/ecmascript).
 
-            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<string>)` - A list of HTTP methods for which this match 
-        applies. If unspecified all http methods are matched.
+- `Methods` `(array<string>)` - A list of HTTP methods for which this match
+  applies. If unspecified all http methods are matched.
 
-  - `Destination` `(ServiceRouteDestination: <optional>)` - Controls how to
-    proxy the actual matching request to a service.
+### `ServiceRouteDestination`
 
-      - `Service` `(string: "")` - The service to resolve instead of the default
-        service. If empty then the default service name is used.
+- `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.
+- `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.
 
-      - `Namespace` `(string: "")` - The namespace to resolve the service from
-        instead of the current namespace. If empty the current namespace is
-        assumed.
+- `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.
+- `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.
+      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.
+- `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.
+- `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.
+- `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.
+- `RetryOnStatusCodes` `(array<int>)` - A flat list of http response status
+  codes that are eligible for retry.
 
 ## ACLs