Skip to content

Commit

Permalink
link fixes + tab fixes
Browse files Browse the repository at this point in the history
  • Loading branch information
@boruszak
boruszak committed Apr 26, 2023
1 parent 3de651d commit dae246f
Showing 1 changed file with 62 additions and 23 deletions.
85 changes: 62 additions & 23 deletions website/content/docs/connect/config-entries/service-router.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -128,7 +128,7 @@ When every field is defined, a service router configuration entry has the follow

```hcl
Kind = "service-router" ## required
Name = "<service-name>" ## required
Name = "<service-name>" ## required
Namespace = "<namespace-configuration-applies-to>"
Partition = "<partition-configuration-applies-to>"
Meta = {
Expand Down Expand Up @@ -259,7 +259,7 @@ Routes = [
"ServiceSubset": "<service-subset-at-destination>",
"Namespace": "<namespace-at-destination>",
"Partition": "<partition-at-destination>",
"PrefixRewrite": "<new-prefix-after-routing>", // required specifying either Routes.Match.HTTP.PathPrefix or Routes.Match.HTTP.PathExact
"PrefixRewrite": "<new-prefix-after-routing>", // required specifying either Routes.Match.HTTP.PathPrefix or Routes.Match.HTTP.PathExact
"RequestTimeout": 0,
"IdleTimeout": 0,
"NumRetries": 1,
Expand Down Expand Up @@ -413,7 +413,7 @@ Defines the possible routes for L7 requests. Consul evaluates traffic against th
| Parameter | Description | Data type | Default |
| :------------ | :-------------------------------------------------------------------------------- | --------- | ------- |
| `Match` | The criteria the configuration entry uses to identify requests. Refer to [`Routes[].Match`](#routes-match) for additional configuration parameters. | Map | None |
| `Destination` | The target service to route matching requests to and behavior the request should follow. Refer to [`Routes`](#routes-destination) for additional configuration parameters. | Map | None |
| `Destination` | The target service to route matching requests to and behavior the request should follow. Refer to [`Routes.Destination`](#routes-destination) for additional configuration parameters. | Map | None |

### `Routes[].Match`

Expand Down Expand Up @@ -672,8 +672,8 @@ Defines the possible routes for L7 requests. Consul evaluates traffic against th

| Parameter | Description | Data type | Default |
| :------------ | :-------------------------------------------------------------------------------- | --------- | ------- |
| `match` | The criteria the configuration entry uses to identify requests. Refer to [`routes[].match`](#spec-routes-match) for additional configuration parameters. | Map | None |
| `destination` | The target service to route matching requests to and behavior the request should follow. Refer to [`routes`](#spec-routes-destination) for additional configuration parameters. | Map | None |
| `match` | The criteria the configuration entry uses to identify requests. Refer to [`spec.routes[].match`](#spec-routes-match) for additional configuration parameters. | Map | None |
| `destination` | The target service to route matching requests to and behavior the request should follow. Refer to [`spec.routes[].destination`](#spec-routes-destination) for additional configuration parameters. | Map | None |

### `spec.routes[].match`

Expand All @@ -686,7 +686,7 @@ Describes a set of criteria that Consul compares incoming L7 traffic with. If em

| Parameter | Description | Data type | Default |
| :-------- | :------------------------------------------------------------------------------------------------------------------------------------- | --------- | ------- |
| `http` | A set of HTTP-specific match criteria. Refer to [`routes[].match{}.http`](#spec-routes-match-http) for additional configuration parameters. | Map | None |
| `http` | A set of HTTP-specific match criteria. Refer to [`spec.routes[].match.http`](#spec-routes-match-http) for additional configuration parameters. | Map | None |

### `spec.routes[].match.http`

Expand All @@ -704,9 +704,9 @@ When matching on the HTTP request path, you can only match on one path at a time
| `pathExact` | Specifies the exact path to match on the HTTP request path. When using this field, do not configure `pathPrefix` or `pathRegex` in the same HTTP object. | String | None |
| `pathPrefix` | Specifies the path prefix to match on the HTTP request path. When using this field, do not configure `pathExact` or `pathRegex` in the same HTTP object. | String | None |
| `pathRegex` | Specifies a regular expression to match on the HTTP request path. When using this field, do not configure `pathExact` or `pathPrefix` in the same HTTP object. The syntax for the regular expression field is proxy-specific. When [using Envoy](/consul/docs/connect/proxies/envoy), refer to [the documentation for Envoy v1.11.2 or newer](https://github.com/google/re2/wiki/Syntax) or [the documentation for Envoy v1.11.1 or older](https://en.cppreference.com/w/cpp/regex/ecmascript), depending on the version of Envoy you use. | String | None |
| `methods` | Specifies HTTP methods that the match applies to. Refer to [`routes[].match{}.http{}.methods`](#spec-routes-march-http-methods) for additional configuration parameters. | List | None |
| `header` | Specifies information to match to in the HTTP request header. When using this field, do not configure `present`, `exact`, `prefix`, `suffix`, or `regex` in the same HTTP object. You can use only one of these fields at a time when configuring match criteria for HTTP headers, as they are mutually exclusive with one another. Refer to [`routes[].match{}.HTTP{}.header`](#spec-routes-match-http-header) for additional configuration parameters. | List | None |
| `queryParam` | Specifies information to match to on HTTP query parameters. When using this field, do not configure `present`, `exact`, or `regex` in the same HTTP object. Refer to [`routes[].match{}.HTTP{}.queryParam](#spec-routes-match-http-queryparam) for additional configuration parameters. | List | None |
| `methods` | Specifies HTTP methods that the match applies to. Refer to [`spec.routes[].match.http.methods`](#spec-routes-match-http-methods) for additional configuration parameters. | List | None |
| `header` | Specifies information to match to in the HTTP request header. When using this field, do not configure `present`, `exact`, `prefix`, `suffix`, or `regex` in the same HTTP object. You can use only one of these fields at a time when configuring match criteria for HTTP headers, as they are mutually exclusive with one another. Refer to [`spec.routes[].match.http.header`](#spec-routes-match-http-header) for additional configuration parameters. | List | None |
| `queryParam` | Specifies information to match to on HTTP query parameters. When using this field, do not configure `present`, `exact`, or `regex` in the same HTTP object. Refer to [`spec.routes[].match.http.queryParam](#spec-routes-match-http-queryparam) for additional configuration parameters. | List | None |

### `spec.routes[].match.http.methods`

Expand Down Expand Up @@ -739,7 +739,7 @@ When using this field, do not configure `present`, `exact`, `prefix`, `suffix`,

| Parameter | Description | Data type | Default |
| :-------- | :------------------------------------------------------------------------------------------------------------------------------------- | --------- | ------- |
| `name` | Specifies the name of the HTTP header to match. This field is required when using [`routes[].match{}.http{}.header`](#spec-routes-match-http-header). | String | None |
| `name` | Specifies the name of the HTTP header to match. This field is required when using [`spec.routes[].match.http.header`](#spec-routes-match-http-header). | String | None |
| `present` | Specifies that a request matches when the value in the `Name` field is present anywhere in the HTTP header. When using this field, do not configure `exact`, `prefix`, `suffix`, or `regex` in the same HTTP object. | Boolean | `false` |
| `exact` | Specifies that a request matches when the header with the given name is this exact value. When using this field, do not configure `present`, `prefix`, `suffix`, or `regex` in the same HTTP object. | String | None |
| `prefix` | Specifies that a request matches when the header with the given name has this prefix. When using this field, do not configure `present`, `exact`, `suffix`, or `regex` in the same HTTP object. | String | None |
Expand All @@ -760,7 +760,7 @@ When using this field, do not configure `present`, `exact`, and `regex` in a sin

| Parameter | Description | Data type | Default |
| :-------- | :------------------------------------------------------------------------------------------------------------------------------------- | --------- | ------- |
| `name` | Specifies the name of the HTTP query parameter to match. This value is required when using [`routes[].match{}.http{}.queryParam`](#spec-routes-match-http-queryparam). | String | None |
| `name` | Specifies the name of the HTTP query parameter to match. This value is required when using [`spec.routes[].match.http.queryParam`](#spec-routes-match-http-queryparam). | String | None |
| `present` | Specifies that a request matches when the value in the `name` field is present anywhere in the HTTP query parameter. When using this field, do not configure `exact` or `regex` in the same map. | Boolean | `false` |
| `exact` | Specifies that a request matches when the query parameter with the given name is this exact value. When using this field, do not configure `present` or `regex` in the same map. | String | None |
| `regex` | Specifies that a request matches when the query parameter with the given name matches this regular expression. When using this field, do not configure `present` or `exact` in the same map. The syntax for the regular expression field is proxy-specific. When [using Envoy](/consul/docs/connect/proxies/envoy), refer to [the documentation for Envoy v1.11.2 or newer](https://github.com/google/re2/wiki/Syntax) or [the documentation for Envoy v1.11.1 or older](https://en.cppreference.com/w/cpp/regex/ecmascript), depending on the version of Envoy you use. | String | None |
Expand All @@ -780,15 +780,15 @@ Specifies the target service to route matching requests to, as well as behavior
| `serviceSubset` | Specifies a named subset of the given service to resolve instead of the one defined as that service's `defaultSubset` in the [service resolver configuration entry](/consul/docs/connect/config-entries/service-resolver). If empty, the default subset is used. | String | None |
| `namespace` <EnterpriseAlert inline /> | Specifies the Consul namespace to resolve the service from instead of the current namespace. If empty, the current namespace is used. | String | None |
| `partition` <EnterpriseAlert inline /> | Specifies the Consul admin partition to resolve the service from instead of the current partition. If empty, the current partition is used. | String | None |
| `prefixRewrite` | Specifies rewrites to the HTTP request path before proxying it to its final destination. This field requires that either [`match.http.pathPrefix`](#match-http-pathprefix) or [`match.http.pathExact`](#match-http-pathexact) be configured on this route. | String | None |
| `prefixRewrite` | Specifies rewrites to the HTTP request path before proxying it to its final destination. This field requires that either [`spec.routes[].match.http.pathPrefix`](#spec-routes-match-http-pathprefix) or [`spec.routes[].match.http.pathExact`](#spec-routes-match-http-pathexact) be configured on this route. | String | None |
| `requestTimeout` | Specifies the total amount of time permitted for the entire downstream request to be processed, including retry attempts. | Integer | `0` |
| `idleTimeout` | Specifies the total amount of time permitted for the request stream to be idle. | Integer | `0` |
| `numRetries` | Specifies the number of times to retry the request when a retry condition occurs. Configure this field and other retry fields in `destination` to configure the logic for retry attempts. For examples, refer to the [retry logic example configurations](#retry-logic). You cannot set the value to `0`. To disable retries, unset all other retry settings: `retryOnConnectFailure`, `retryOn`, `retryOnStatusCodes`. | Integer | `1` |
| `retryOnConnectFailure` | Specifies that connection failure errors that trigger a retry request. Configure this field and other retry fields in `destination` to configure the logic for retry attempts. For examples, refer to the [retry logic example configurations](#retry-logic). | Boolean | `false` |
| `retryOn` | Specifies a list of conditions for Consul to retry requests. Use this field to configure advanced logic for retry attempts. Refer to [`routes[].destination{}.RetryOn[]`](#spec-routes-destination-retryon) for additional configuration parameters. | List | None |
| `retryOnStatusCodes` | Specifies a list of integers for [HTTP response status codes](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status) that trigger a retry request. Configure this field and other retry fields in `destination` to configure the logic for retry attempts. For examples, refer to the [retry logic example configurations](#retry-logic).
| `requestHeaders` | Specifies a set of HTTP-specific header modification rules applied to requests routed with the service router. Refer to [`routes[].destination{}.requestHeaders`](#spec-routes-destination-requestheaders) for additional configuration parameters. | Map | None |
| `responseHeaders` | Specifies a set of HTTP-specific header modification rules applied to responses routed with the service router. Refer to [`routes[].destination{}.responseHeaders`](#spec-routes-destination-responseheaders) for additional configuration parameters. | Map | None |
| `requestHeaders` | Specifies a set of HTTP-specific header modification rules applied to requests routed with the service router. Refer to [`spec.routes[].destination.requestHeaders`](#spec-routes-destination-requestheaders) for additional configuration parameters. | Map | None |
| `responseHeaders` | Specifies a set of HTTP-specific header modification rules applied to responses routed with the service router. Refer to [`spec.routes[].destination.responseHeaders`](#spec-routes-destination-responseheaders) for additional configuration parameters. | Map | None |

### `spec.routes[].destination.retryOn[]`

Expand Down Expand Up @@ -874,7 +874,8 @@ The following examples demonstrate common service router configuration patterns

The following example routes HTTP requests with `/admin` at the start of their path to a service named `admin`.

<CodeTabs tabs={[ "HCL", "Kubernetes YAML", "JSON" ]}>
<Tabs>
<Tab heading="HCL" group="hcl">

```hcl
Kind = "service-router"
Expand All @@ -894,6 +895,10 @@ Routes = [
]
```

</Tab>

<Tab heading="YAML" group="yaml">

```yaml
apiVersion: consul.hashicorp.com/v1alpha1
kind: ServiceRouter
Expand All @@ -908,6 +913,10 @@ spec:
service: admin
```

</Tab>

<Tab heading="JSON" group="json">

```json
{
"Kind": "service-router",
Expand All @@ -927,13 +936,15 @@ spec:
}
```

</CodeTabs>
</Tab>
</Tabs>

### Match a header and query parameter

The following example routes HTTP traffic to the `web` service to a subset of `canary` instances when the requests have `x-debug` in either the header or the URL parameter.

<CodeTabs tabs={[ "HCL", "Kubernetes YAML", "JSON" ]}>
<Tabs>
<Tab heading="HCL" group="hcl">

```hcl
Kind = "service-router"
Expand Down Expand Up @@ -974,6 +985,10 @@ Routes = [
]
```

</Tab>

<Tab heading="YAML" group="yaml">

```yaml
apiVersion: consul.hashicorp.com/v1alpha1
kind: ServiceRouter
Expand All @@ -999,6 +1014,10 @@ spec:
serviceSubset: canary
```

</Tab>

<Tab heading="JSON" group="json">

```json
{
"Kind": "service-router",
Expand Down Expand Up @@ -1040,13 +1059,15 @@ spec:
}
```

</CodeTabs>
</Tab>
</Tabs>

### gRPC routing

The following example routes gRPC requests to the `invoice-generator`service when they come from an HTTP path that is exact match for `mycompany.BillingService/GenerateInvoice`. Because gRPC method calls use HTTP/2, you can use an HTTP path match rule to re-route traffic.

<CodeTabs tabs={[ "HCL", "Kubernetes YAML", "JSON" ]}>
<Tabs>
<Tab heading="HCL" group="hcl">

```hcl
Kind = "service-router"
Expand All @@ -1066,6 +1087,10 @@ Routes = [
]
```

</Tab>

<Tab heading="YAML" group="yaml">

```yaml
apiVersion: consul.hashicorp.com/v1alpha1
kind: ServiceRouter
Expand All @@ -1080,6 +1105,10 @@ spec:
service: invoice-generator
```

</Tab>

<Tab heading="JSON" group="json">

```json
{
"Kind": "service-router",
Expand All @@ -1099,7 +1128,8 @@ spec:
}
```

</CodeTabs>
</Tab>
</Tabs>

### Retry logic

Expand All @@ -1108,8 +1138,8 @@ The following example configures Consul so that when a request for the `orders`
- If it originates from the `/coffees` path, the request routes to the `products` service, times out after 15 seconds, and attempts 5 retries.
- If it originates from the `/orders` path, the request routes to the `procurement` services, times out after 10 seconds, and attempts 3 retries.

<CodeTabs tabs={[ "HCL", "Kubernetes YAML", "JSON" ]}>

<Tabs>
<Tab heading="HCL" group="hcl">

```hcl
Kind = "service-router"
Expand Down Expand Up @@ -1148,6 +1178,10 @@ Routes = [
]
```

</Tab>

<Tab heading="YAML" group="yaml">

```yaml
apiVersion: consul.hashicorp.com/v1alpha1
kind: ServiceRouter
Expand Down Expand Up @@ -1175,6 +1209,9 @@ spec:
retryOn: ['reset']
```

</Tab>

<Tab heading="JSON" group="json">

```json
{
Expand Down Expand Up @@ -1213,4 +1250,6 @@ spec:
}
```
</CodeTabs>

</Tab>
</Tabs>

0 comments on commit dae246f

Please sign in to comment.