diff --git a/website/content/docs/connect/config-entries/service-resolver.mdx b/website/content/docs/connect/config-entries/service-resolver.mdx index 821493bcbf12..999441082ea9 100644 --- a/website/content/docs/connect/config-entries/service-resolver.mdx +++ b/website/content/docs/connect/config-entries/service-resolver.mdx @@ -133,7 +133,7 @@ When every field is defined, a service resolver configuration entry has the foll Kind = "service-resolver" ## required Name = "" Namespace = "" -Partition = "parition-configuration-applies-to>" +Partition = "" Meta = { = "" } @@ -439,7 +439,7 @@ Specifies names for service subsets and the conditions under which service insta | Parameter | Description | Data type | Default | | :------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ------- | - | `Filter` | Specifies an expression that filters the DNS elements of service instances that belong to the subset. If empty, all healthy instances of a service are returned. This expression can filter on the same DNS selectors as the [Health API endpoint](/consul/api-docs/health#filtering-2). | String | None | + | `Filter` | Specifies an expression that filters the DNS elements of service instances that belong to the subset. If empty, all healthy instances of a service are returned. This expression can filter on the same DNS selectors as the [Health API endpoint](/consul/api-docs/health#filtering-2). For more information about creating and using expressions to filter, refer to [filtering](/consul/api-docs/features/filtering). | String | None | | `OnlyPassing` | Determines if instances that return a warning from a health check are allowed to resolve a request. When set to `false`, instances with `passing` and `warning` states are considered healthy. When set to `true`, only instances with a `passing` health check state are considered healthy. | Boolean | `false` | ### `DefaultSubset` @@ -701,7 +701,7 @@ Specifies names for service subsets and the conditions under which service insta | Parameter | Description | Data type | Default | | :------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ------- | - | `filter` | Specifies an expression that filters the DNS elements of service instances that belong to the subset. If empty, all healthy instances of a service are returned. This expression can filter on the same DNS selectors as the [Health API endpoint](/consul/api-docs/health#filtering-2). | String | None | + | `filter` | Specifies an expression that filters the DNS elements of service instances that belong to the subset. If empty, all healthy instances of a service are returned. This expression can filter on the same DNS selectors as the [Health API endpoint](/consul/api-docs/health#filtering-2). For more information about creating and using expressions to filter, refer to [filtering](/consul/api-docs/features/filtering). | String | None | | `onlyPassing` | Determines if instances that return a warning from a health check are allowed to resolve a request. When set to `false`, instances with `passing` and `warning` states are considered healthy. When set to `true`, only instances with a `passing` health check state are considered healthy. | Boolean | `false` | ### `spec.defaultSubset` diff --git a/website/content/docs/connect/config-entries/service-router.mdx b/website/content/docs/connect/config-entries/service-router.mdx index 1a12e3cdf9fa..ca8506a71ad0 100644 --- a/website/content/docs/connect/config-entries/service-router.mdx +++ b/website/content/docs/connect/config-entries/service-router.mdx @@ -1,53 +1,878 @@ --- layout: docs -page_title: Service Router - Configuration Entry Reference -description: >- - The service router configuration entry kind defines where the service mesh routes requests based on L7 network information such as header or path. Use the reference guide to learn about `""service-router""` config entry parameters and how behaviors like request timeouts, retry behavior, header modification, and path rewriting can be applied to a request based on its header or path information. +page_title: Service Router Configuration Entry Reference +description: >- + Service router configuration entries are L7 traffic management tools for redirecting requests for a service to a particular instance or set of instances. Learn how to write `service-router` config entries in HCL or YAML with a specification reference, configuration model, a complete example, and example code by use case. --- -# Service Router Configuration Entry +# Service router configuration entry reference + +This page provides reference information for service router configuration entries. Service routers use L7 network information to redirect a traffic request for a service to one or more specific service instances. + +Refer to [L7 traffic management overview](/consul/docs/connect/l7-traffic) for additional information. + +## Configuration model + +The following list outlines field hierarchy, language-specific data types, and requirements in this configuration entry. Click on a property name to view additional details, including default values. + + + + + +- [`Kind`](#kind): string | required | must be set to `service-router` +- [`Name`](#name): string | required +- [`Namespace`](#namespace): string +- [`Partition`](#partition): string | `default` +- [`Meta`](#meta): map +- [`Routes`](#routes): list + - [`Match`](#routes-match): map + - [‘HTTP`](#routes-match-http): map + - [`PathExact`](#routes-match-http-pathexact): string + - [`PathPrefix`](#routes-match-http-pathprefix): string + - [`PathRegex`](#routes-match-http-pathregex): string + - [`Methods`](#routes-match-http-methods): list + - [`Header`](#routes-match-http-header): list + - [`Name`](#routes-match-http-header-name): string + - [`Present`](#routes-match-http-header-present): boolean | `false` + - [`Exact`](#routes-match-http-header-exact): string + - [`Prefix`](#routes-match-http-header-prefix): string + - [`Suffix`](#routes-match-http-header-suffix): string + - [`Regex`](#routes-match-http-header-regex): string + - [`Invert`](#routes-match-http-header-invert): boolean | `false` + - [`QueryParam`](#routes-match-http-queryparam): list + - [`Name`](#routes-match-http-queryparam-name): string + - [`Present`](#routes-match-http-queryparam-present): boolean | `false` + - [`Exact`](#routes-match-http-queryparam-exact): string + - [`Regex`](#routes-match-http-queryparam-regex): string + - [`Destination`](#routes-destination): map + - [`Service`](#routes-destination-service): string + - [`ServiceSubset`](#routes-destination-servicesubset): string +- [`Namespace`](#routes-destination-namespace): string +- [`Partition`](#routes-destination-partition): string +- [`PrefixRewrite`](#routes-destination-prefixrewrite): string +- [`RequestTimeout`](#routes-destination-requesttimeout): integer | `0` +- [`IdleTimeout`](#routes-destination-idletimeout): integer | `0` +- [`NumRetries`](#routes-destination-numretries): integer | `1` +- [`RetryOnConnectFailure`](#routes-destination-retryonconnectfailure): boolean | `false` +- [`RetryOn`](#routes-destination-retryon): list +- [`RetryOnStatusCodes`](#routes-destination-retryonstatuscodes): list +- [`RequestHeaders`](#routes-destination-requestheaders): map + - [`Add`](#routes-destination-requestheaders): map + - [`Set`](#routes-destination-requestheaders): map + - [`Remove`](#routes-destination-requestheaders): map +- [`ResponseHeaders`](#routes-destination-responseheaders): map + - [`Add`](#routes-destination-responseheaders): map + - [`Set`](#routes-destination-responseheaders): map + - [`Remove`](#routes-destination-responseheaders): map + + + + + +- [`apiVersion`](#apiversion): string | required | must be set to `consul.hashicorp.com/v1alpha1` +- [`kind`](#kind): string | required | must be set to `serviceRouter` +- [`metadata`](#metadata): map | required + - [`name`](#metadata-name): string | required + - [`namespace`](#metadata-namespace): string | optional +- [`spec`](#spec): map | required + - [`routes`](#spec-routes): list + - [`match`](#spec-routes-match): map + - [‘http`](#spec-routes-match-http): map + - [`pathExact`](#spec-routes-match-http-pathexact): string + - [`pathPrefix`](#spec-routes-match-http-pathprefix): string + - [`pathRegex`](#spec-routes-match-http-pathregex): string + - [`methods`](#spec-routes-match-http-methods): list + - [`header`](#spec-routes-match-http-header): list + - [`name`](#spec-routes-match-http-header-name): string + - [`present`](#spec-routes-match-http-header-present): boolean | `false` + - [`exact`](#spec-routes-match-http-header-exact): string + - [`prefix`](#spec-routes-match-http-header-prefix): string + - [`suffix`](#spec-routes-match-http-header-suffix): string + - [`regex`](#spec-routes-match-http-header-regex): string + - [`invert`](#spec-routes-match-http-header-invert): boolean + - [`queryParam`](#spec-routes-match-http-queryparam): list + - [`name`](#spec-routes-match-http-queryparam-name): string + - [`present`](#spec-routes-match-http-queryparam-present): boolean | `false` + - [`regex`](#spec-routes-match-http-queryparam-regex): string + - [`destination`](#spec-routes-destination): map + - [`service`](#spec-routes-destination-service): string + - [`serviceSubset`](#spec-routes-destination-servicesubset): string + - [`namespace`](#spec-routes-destination-namespace): string + - [`partition`](#spec-routes-destination-partition): string + - [`prefixRewrite`](#spec-routes-destination-prefixrewrite): string + - [`requestTimeout`](#spec-routes-destination-requesttimeout): integer | `0` + - [`numRetries`](#spec-routes-destination-numretries): integer | `0` + - [`numRetries`](#spec-routes-destination-numretries): integer | `1` + - [`retryOnConnectFailure`](#spec-routes-destination-retryonconnectfailure): boolean | `false` + - [`retryOn`](#spec-routes-destination-retryon): list + - [`retryOnStatusCodes`](#spec-routes-destination-retryonstatuscodes): list + - [`requestHeaders`](#spec-routes-destination-requestheaders): map + - [`add`](#spec-routes-destination-requestheaders): map + - [`set`](#spec-routes-destination-requestheaders): map + - [`remove`](#spec-routes-destination-requestheaders): map + - [`responseHeaders`](#spec-routes-destination-responseheaders): map + - [`add`](#spec-routes-destination-responseheaders): map + - [`set`](#spec-routes-destination-responseheaders): map + - [`remove`](#spec-routes-destination-responseheaders): map + + + + +## Complete configuration + +When every field is defined, a service router configuration entry has the following form: + + + + -The `service-router` config entry kind (`ServiceRouter` on Kubernetes) controls Connect traffic routing and -manipulation at networking layer 7 (e.g. HTTP). +```hcl +Kind = "service-router" ## required +Name = "" ## required +Namespace = "" +Partition = "" +Meta = { + = "" +} + + +Routes = [ + { + Match { + HTTP { + PathExact = "" ## cannot specify with PathPrefix or PathRegex + }, + HTTP { + PathPrefix = "" ## cannot specify with PathExact or PathRegex + }, + HTTP { + PathRegex = "" ## cannot specify with PathPrefix or PathExact + }, + HTTP { + Methods = ["GET", "POST", "PUT"] + }, + HTTP { + Header = [ ## do not specify Present, Exact, Prefix, Suffix, and Regex in a single Header + { + Name = "" ## required when specifying Routes.Match.HTTP.Header + Present = false + Exact = "" + Prefix = "" + Suffix = "" + Regex = "" + Invert = false + } + ] + } + HTTP { + QueryParam = [ ## do not specify Present, Exact, and Regex in a single QueryParam + Name = "" ## required when specifying Routes.Match.HTTP.Header + Present = false + Exact = "" + Regex = "" + ] + } + }, + + + Destination { + Service = "" + ServiceSubset = "" + Namespace = "" + Partition = "" + PrefixRewrite = "" ## required specifying either Routes.Match.HTTP.PathPrefix or Routes.Match.HTTP.PathExact + RequestTimeout = 0 + IdleTimeout = 0 + NumRetries = 1 + RetryOnConnectFailure = false + RetryOn = ["reset", "unavailable"] + RetryOnStatusCodes = [500, 502, 503] + RequestHeaders = { + Set = { + "X-Web-Version" : "" + } + } + ResponseHeaders = { + Set = { + "X-Web-Version" : "" + } + } + } + } +] +``` + + + + + +```json +{ + "Kind": "service-router", // required + "Name": "", // required + "Namespace": "", + "Partition": "", + "Meta": { + "": "" + }, + + "Routes": [ + { + "Match": { + "HTTP": { + "PathExact": "" // cannot specify with PathPrefix or PathRegex + }, + "HTTP": { + "PathPrefix": "" // cannot specify with PathExact or PathRegex + }, + "HTTP": { + "PathRegex": "" // cannot specify with PathPrefix or PathExact + }, + "HTTP": { + "Methods": ["GET", "POST", "PUT"] + }, + "HTTP": { + "Header": [ // do not specify Present, Exact, Prefix, Suffix, and Regex in a single Header + { + "Name": "", // required when specifying Routes.Match.HTTP.Header + "Present": false, + "Exact": "", + "Prefix": "", + "Suffix": "", + "Regex": "", + "Invert": false, + } + ] + }, + "HTTP": { + "QueryParam": [ // do not specify Present, Exact, and Regex in a single QueryParam + "Name": "", // required when specifying Routes.Match.HTTP.Header + "Present": false, + "Exact": "", + "Regex": "" + ] + } + }, + + "Destination": { + "Service": "", + "ServiceSubset": "", + "Namespace": "", + "Partition": "", + "PrefixRewrite": "", // required specifying either Routes.Match.HTTP.PathPrefix or Routes.Match.HTTP.PathExact + "RequestTimeout": 0, + "IdleTimeout": 0, + "NumRetries": 1, + "RetryOnConnectFailure": false, + "RetryOn": ["reset", "unavailable"], + "RetryOnStatusCodes": [500, 502, 503], + "RequestHeaders": { + "Set": { + "X-Web-Version" : "" + } + }, + "ResponseHeaders": { + "Set": { + "X-Web-Version" : "" + } + } + } + } + ] +} +``` + + + + + +```yaml +```yaml +apiVersion: consul.hashicorp.com/v1alpha1 # required +kind: ServiceRouter # required +metadata: + name: + namespace: +spec: + routes: + - match: + http: + pathExact: ## cannot specify with pathPrefix or pathRegex + http: + pathPrefix: ## cannot specify with pathExact or pathRegex + http: + pathRegex: ## cannot specify with pathPrefix or pathExact + http: + methods: [GET, POST, PUT] + http: + header: ## do not specify present, exact, prefix, suffix, and regex in a single header + - name: ## required when specifying routes.match.http.header + present: false + exact: + prefix: + suffix: + regex: + invert: false + http: + queryParam: ## do not specify present, exact, and regex in a single QueryParam + - name: ## required when specifying routes.match.http.header + present: false + exact: + regex: + + destination: + service: + serviceSubset: + namespace: + partition: + prefixRewrite: ## required specifying either routes.match.http.pathPrefix or routes.match.http.pathExact + requestTimeout: 0 + idleTimeout: 0 + numRetries: 1 + retryOnConnectFailure: false + retryOn: ['reset'] + retryOnStatusCodes: [500, 502, 503] + requestHeaders: + set: + x-Web-Version: + responseHeaders: + set: + x-Web-Version: +``` + + + + + +## Specification + +This section provides details about the fields you can configure in the service router configuration entry. + + + + + +### `Kind` + +Specifies the type of configuration entry to implement. + +#### Values + +- Default: none +- This field is required. +- Data type: String value that must be set to `service-router`. + +### `Name` + +Specifies a name for the configuration entry. The name is metadata that you can use to reference the configuration entry when performing Consul operations with the [`consul config` command](/consul/commands/config). + +#### Values + +- Default: Defaults to the name of the node after writing the entry to the Consul server. +- This field is required. +- Data type: String + +### `Namespace` + +Specifies the [namespace](/consul/docs/enterprise/namespaces) to apply the configuration entry to. Refer to [Namespaces](/consul/docs/enterprise/namespaces) for additional information about Consul namespaces. + +#### Values + +- Default: None +- Data type: String + +### `Partition` + +Specifies the [admin partition](/consul/docs/enterprise/admin-partitions) to apply the configuration entry to. Refer to [Admin partitions](/consul/docs/enterprise/admin-partitions) for additional information. + +#### Values + +- Default: `default` +- Data type: String + +### `Meta` + +Specifies key-value pairs to add to the KV store. + +#### Values + +- Default: none +- Data type: Map of one or more key-value pairs + - ``: String + - ``: String or integer + +### `Routes` + +Defines the possible routes for L7 requests. Consul evaluates traffic against the list of routes in their order of appearance in the configuration entry. When multiple routes satisfy the request, Consul uses the first route that matches. Traffic that fails to match any of the provided routes is routed to the default service. + +#### Values + +- Default: None +- Data type: List that can contain the following parameters: + + | 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 | + +### `Routes[].Match` + +Describes a set of criteria that Consul compares incoming L7 traffic with. If empty or omitted, it acts as a catch-all. + +#### Values + +- Default: None +- Data type: Map that contains the following parameter: + +| Parameter | Description | Data type | Default | +| :-------- | :------------------------------------------------------------------------------------------------------------------------------------- | --------- | ------- | +| `HTTP` | A set of HTTP-specific match criteria. Refer to [`Routes[].Match{}.HTTP`](#routes-match-http) for additional configuration parameters. | Map | None | + +### `Routes[].Match{}.HTTP` + +Specifies a set of HTTP criteria used to evaluate incoming L7 traffic for matches. + +When matching on the HTTP request path, you can only match on one path at a time. Do not configure `PathExact`, `PathPrefix`, and `PathRegex` in a single HTTP map. + +#### Values + +- Default: None +- Data type: Map that can contain the following parameters: + +| Parameter | Description | Data type | Default | +| :----------- | :------------------------------------------------------------------------------------------------------------------------------------- | --------- | ------- | +| `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`](#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`](#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](#routes-match-http-queryparam) for additional configuration parameters. | List | None | + +### `Routes[].Match{}.HTTP{}.Methods` + +Specifies HTTP methods that the match applies to. If not specified, the request matches on all HTTP methods. If provided, the name must be a valid method formatted as a string. + +#### Values + +- Default: None +- Data type: List of strings. String values must be a valid [HTTP request method](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods): + - `GET` + - `HEAD` + - `POST` + - `PUT` + - `DELETE` + - `CONNECT` + - `OPTIONS` + - `TRACE` + - `PATCH` + +### `Routes[].Match{}.HTTP{}.Header` + +Specifies information to match to in the HTTP request header. When more than one field is configured, all criteria must match for the service routing to apply. + +When using this field, do not configure `Present`, `Exact`, `Prefix`, `Suffix`, and `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. + +#### Values + +- Default: None +- Data type: List containing one or more of the following parameters: + +| 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`](#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 | +| `Suffix` | Specifies that a request matches when the header with the given name has this suffix. When using this field, do not configure `Present`, `Exact`, `Prefix`, or `Regex` in the same HTTP object. | String | None | +| `Regex` | Specifies that a request matches when the header with the given name matches this regular expression. When using this field, do not configure `Present`, `Exact`, `Prefix`, or `Suffix` 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 | +| `Invert` | Specifies that the logic for the HTTP header match should be inverted. Requests with matching criteria are not routed. | Boolean | `false` | + +### `Routes[].Match{}.HTTP{}.QueryParam` + +Specifies information to match to on HTTP query parameters. When more than one field is configured, all criteria must match for the service routing to apply. + +When using this field, do not configure `Present`, `Exact`, and `Regex` in a single map. You can use only one of these fields at a time when configuring match criteria for HTTP query parameters, as they are mutually exclusive with one another. + +#### Values + +- Default: None +- Data type: List of maps. Each map can contain one or more of the following parameters: + +| 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`](#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 | + +### `Routes[].Destination` + +Specifies the target service to route matching requests to, as well as behavior for the request to follow when routed. + +#### Values + +- Default: None +- Data type: Map containing one or more of the following parameters: + +| Parameter | Description | Data type | Default | +| :-------- | :------------------------------------------------------------------------------------------------------------------------------------- | --------- | ------- | +| `Service` | Specifies the name of the service to resolve instead of the default. If empty, the default service name is inherited from the configuration entry’s [`Name` field](#name). | String | None | +| `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` | Specifies the Consul namespace to resolve the service from instead of the current namespace. If empty, the current namespace is used. | String | None | +| `Partition` | 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 | +| `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[]`](#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`](#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`](#routes-destination-responseheaders) for additional configuration parameters. | Map | None | + +### `Routes[].Destination{}.RetryOn[]` + +Specifies a list of conditions for Consul to retry requests. Configure this field and other retry fields in the `Destination` object to configure the logic for retry attempts. For examples, refer to the [retry logic example configurations](#retry-logic). + +#### Values + +- Default: None +- Data type: List of strings. Strings must match one of the following values: + +| Conditions | Description | +| :------------------- | :--------------------------------------------------------------------------------------------------- | +| `5xx` | Consul encountered a 5xx HTTP response code error code while routing the request. | +| `gateway-error` | Consul encountered a gateway error while routing the request. | +| `reset` | The Consul server was reset while routing the request. | +| `connect-failure` | Consul encountered a service mesh failure while routing the request. | +| `envoy-ratelimited` | An Envoy proxy did not complete the request because it was rate limited. | +| `retriable-4xx` | Consul encountered a retriable 4xx HTTP response code while routing the request. | +| `refused-stream` | An upstream service refused the connection while Consul was routing the request. | +| `cancelled` | The request was canceled while Consul was routing it. | +| `deadline-exceeded` | Consul did not receive a response that the request was routed within the configured timeout period. | +| `internal` | Consul encountered an internal error while routing the request. | +| `resource-exhausted` | Available resources were exhausted, preventing Consul from routing the request. | +| `unavailable` | Consul was unavailable to route the request when it was made. | + +### `Routes[].Destination{}.RequestHeaders` + +Specifies a set of HTTP-specific header modification rules applied to requests routed with the service router. You cannot configure request headers if the listener protocol is set to `tcp`. + +#### Values + +- Default: None +- Values: Object containing one or more fields that define header modification rules: + - `Add`: Map of one or more key-value pairs. + - `Set`: Map of one or more key-value pairs. + - `Remove`: Map of one or more key-value pairs. + +The following table describes how to configure values for request headers: + +| Rule | Description | Type | +| --- | --- | --- | +| `Add` | Defines a set of key-value pairs to add to the header. Use header names as the keys. Header names are not case-sensitive. If header values with the same name already exist, the value is appended and Consul applies both headers. You can [use variable placeholders](#use-variable-placeholders). | map of strings | +| `Set` | Defines a set of key-value pairs to add to the request header or to replace existing header values with. Use header names as the keys. Header names are not case-sensitive. If header values with the same names already exist, Consul replaces the header values. You can [use variable placeholders](#use-variable-placeholders). | map of strings | +| `Remove` | Defines a list of headers to remove. Consul removes only headers containing exact matches. Header names are not case-sensitive. | list of strings | + +#### Use variable placeholders + +For `Add` and `Set`, if the service is configured to use Envoy as the proxy, the value may contain variables to interpolate dynamic metadata into the value. For example, using the variable `%DOWNSTREAM_REMOTE_ADDRESS%` in your configuration entry allows you to pass a value that is generated when the routing occurs. + +### `Routes[].Destination{}.ResponseHeaders` + +Specifies a set of HTTP-specific header modification rules applied to responses routed with the service router. You cannot configure request headers if the listener protocol is set to `tcp`. + +#### Values + +- Default: None +- Values: Object containing one or more fields that define header modification rules: + - `Add`: Map of one or more string key-value pairs. + - `Set`: Map of one or more string key-value pairs. + - `Remove`: Map of one or more string key-value pairs. + +The following table describes how to configure values for response headers: + +| Rule | Description | Type | +| --- | --- | --- | +| `Add` | Defines a set of key-value pairs to add to the header. Use header names as the keys. Header names are not case-sensitive. If header values with the same name already exist, the value is appended and Consul applies both headers. You can [use variable placeholders](#use-variable-placeholders). | map of strings | +| `Set` | Defines a set of key-value pairs to add to the request header or to replace existing header values with. Use header names as the keys. Header names are not case-sensitive. If header values with the same names already exist, Consul replaces the header values. You can [use variable placeholders](#use-variable-placeholders). | map of strings | +| `Remove` | Defines a list of headers to remove. Consul removes only headers containing exact matches. Header names are not case-sensitive. | list of strings | + +#### Use variable placeholders + +For `Add` and `Set`, if the service is configured to use Envoy as the proxy, the value may contain variables to interpolate dynamic metadata into the value. For example, using the variable `%DOWNSTREAM_REMOTE_ADDRESS%` in your configuration entry allows you to pass a value that is generated when the routing occurs. + + + + + +### `apiVersion` + +Kubernetes-only parameter that specifies the version of the Consul API that the configuration entry maps to Kubernetes configurations. The value must be `consul.hashicorp.com/v1alpha1`. + +### `kind` + +Specifies the type of configuration entry to implement. + +#### Values + +- Default: none +- This field is required. +- Data type: String value that must be set to `serviceRouter`. + +### `metadata.name` + +Specifies a name for the configuration entry. The name is metadata that you can use to reference the configuration entry when performing Consul operations, such as applying a configuration entry to a specific cluster. + +#### Values + +- Default: Inherits name from the host node +- This field is required. +- Data type: String + + +### `metadata.namespace` + +Specifies the Consul namespace to use for resolving the service. You can map Consul namespaces to Kubernetes Namespaces in different ways. Refer to [Custom Resource Definitions (CRDs) for Consul on Kubernetes](/consul/docs/k8s/crds#consul-enterprise) for additional information. + +#### Values + +- Default: None +- Data type: String + +### `spec` + +Kubernetes-only field that contains all of the configurations for service splitter pods. + +#### Values + +- Default: None +- This field is required. +- Data type: Object containing [`spec.routes`](#spec-routes) configuration + +### `spec.meta` + +Specifies key-value pairs to add to the KV store. + +#### Values + +- Default: none +- Data type: Map of one or more key-value pairs + - keys: String + - values: String, integer, or float + +### `spec.routes` + +Defines the possible routes for L7 requests. Consul evaluates traffic against the list of routes in their order of appearance in the configuration entry. When multiple routes satisfy the request, Consul uses the first route that matches. Traffic that fails to match any of the provided routes is routed to the default service. + +#### Values + +- Default: None +- Data type: List that can contain the following parameters: + + | 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 | + +### `spec.routes[].match` + +Describes a set of criteria that Consul compares incoming L7 traffic with. If empty or omitted, it acts as a catch-all. + +#### Values + +- Default: None +- Data type: Map that contains the following parameter: + +| 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 | + +### `spec.routes[].match.http` + +Specifies a set of HTTP criteria used to evaluate incoming L7 traffic for matches. + +When matching on the HTTP request path, you can only match on one path at a time. Do not configure `pathExact`, `pathPrefix`, and `pathRegex` in a single HTTP map. + +#### Values + +- Default: None +- Data type: Map that can contain the following parameters: + +| Parameter | Description | Data type | Default | +| :----------- | :------------------------------------------------------------------------------------------------------------------------------------- | --------- | ------- | +| `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 | + +### `spec.routes[].match.http.methods` + +Specifies HTTP methods that the match applies to. If not specified, the request matches on all HTTP methods. If provided, the name must be a valid method formatted as a string. + +#### Values + +- Default: None +- Data type: List of strings. String values must be a valid [HTTP request method](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods): + - `GET` + - `HEAD` + - `POST` + - `PUT` + - `DELETE` + - `CONNECT` + - `OPTIONS` + - `TRACE` + - `PATCH` -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. +### `spec.routes[].match.http.header` -## Requirements +Specifies information to match to in the HTTP request header. When more than one field is configured, all criteria must match for the service routing to apply. -- Consul [service mesh connect](/consul/docs/connect/configuration) enabled services -- Service to service communication over the protocol `http` +When using this field, do not configure `present`, `exact`, `prefix`, `suffix`, and `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. -## Interaction with other Config Entries +#### Values -- Service router config entries are a component of [L7 Traffic - Management](/consul/docs/connect/l7-traffic). +- Default: None +- Data type: List containing one or more of the following parameters: -- Service router config entries are restricted to only services that define - their protocol as HTTP-based via a corresponding - [`service-defaults`](/consul/docs/connect/config-entries/service-defaults) config - entry or globally via - [`proxy-defaults`](/consul/docs/connect/config-entries/proxy-defaults) . +| 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 | +| `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 | +| `suffix` | Specifies that a request matches when the header with the given name has this suffix. When using this field, do not configure `present`, `exact`, `prefix`, or `regex` in the same HTTP object. | String | None | +| `regex` | Specifies that a request matches when the header with the given name matches this regular expression. When using this field, do not configure `present`, `exact`, `prefix`, or `suffix` 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 | +| `invert` | Specifies that the logic for the HTTP header match should be inverted. Requests with matching criteria are not routed. | Boolean | `false` | -- Any route destination that omits the `ServiceSubset` field is eligible for - splitting via a - [`service-splitter`](/consul/docs/connect/config-entries/service-splitter) should - one be configured for that service, otherwise resolution proceeds according - to any configured - [`service-resolver`](/consul/docs/connect/config-entries/service-resolver). +### `spec.routes[].match.http.queryParam` -## UI +Specifies information to match to on HTTP query parameters. When more than one field is configured, all criteria must match for the service routing to apply. -Once a `service-router` is successfully entered, you can view it in the UI. Service routers, service splitters, and service resolvers can all be viewed by clicking on your service then switching to the _routing_ tab. +When using this field, do not configure `present`, `exact`, and `regex` in a single map. You can use only one of these fields at a time when configuring match criteria for HTTP query parameters, as they are mutually exclusive with one another. -![screenshot of service router in the UI](/img/l7-routing/Router.png) +#### Values -## Sample Config Entries +- Default: None +- Data type: List of maps. Each map can contain one or more of the following parameters: + +| 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 | +| `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 | + +### `spec.routes[].destination` + +Specifies the target service to route matching requests to, as well as behavior for the request to follow when routed. + +#### Values + +- Default: None +- Data type: Map containing one or more of the following parameters: + +| Parameter | Description | Data type | Default | +| :-------- | :------------------------------------------------------------------------------------------------------------------------------------- | --------- | ------- | +| `service` | Specifies the name of the service to resolve instead of the default. If empty, the default service name is inherited from the configuration entry’s [`name` field](#name). | String | None | +| `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` | Specifies the Consul namespace to resolve the service from instead of the current namespace. If empty, the current namespace is used. | String | None | +| `partition` | 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 | +| `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 | + +### `spec.routes[].destination.retryOn[]` + +Specifies a list of conditions for Consul to retry requests. Configure this field and other retry fields in the `destination` object to configure the logic for retry attempts. For examples, refer to the [retry logic example configurations](#retry-logic). + +#### Values + +- Default: None +- Data type: List of strings. Strings must match one of the following values: + +| Conditions | Description | +| :------------------- | :--------------------------------------------------------------------------------------------------- | +| `5xx` | Consul encountered a 5xx HTTP response code error code while routing the request. | +| `gateway-error` | Consul encountered a gateway error while routing the request. | +| `reset` | The Consul server was reset while routing the request. | +| `connect-failure` | Consul encountered a service mesh failure while routing the request. | +| `envoy-ratelimited` | An Envoy proxy did not complete the request because it was rate limited. | +| `retriable-4xx` | Consul encountered a retriable 4xx HTTP response code while routing the request. | +| `refused-stream` | An upstream service refused the connection while Consul was routing the request. | +| `cancelled` | The request was canceled while Consul was routing it. | +| `deadline-exceeded` | Consul did not receive a response that the request was routed within the configured timeout period. | +| `internal` | Consul encountered an internal error while routing the request. | +| `resource-exhausted` | Available resources were exhausted, preventing Consul from routing the request. | +| `unavailable` | Consul was unavailable to route the request when it was made. | + +### `spec.routes[].destination.requestHeaders` + +Specifies a set of HTTP-specific header modification rules applied to requests routed with the service router. You cannot configure request headers if the listener protocol is set to `tcp`. + +#### Values + +- Default: None +- Values: Object containing one or more fields that define header modification rules: + - `add`: Map of one or more key-value pairs. + - `set`: Map of one or more key-value pairs. + - `remove`: Map of one or more key-value pairs. + +The following table describes how to configure values for request headers: + +| Rule | Description | Type | +| --- | --- | --- | +| `add` | Defines a set of key-value pairs to add to the header. Use header names as the keys. Header names are not case-sensitive. If header values with the same name already exist, the value is appended and Consul applies both headers. You can [use variable placeholders](#use-variable-placeholders). | map of strings | +| `set` | Defines a set of key-value pairs to add to the request header or to replace existing header values with. Use header names as the keys. Header names are not case-sensitive. If header values with the same names already exist, Consul replaces the header values. You can [use variable placeholders](#use-variable-placeholders). | map of strings | +| `remove` | Defines a list of headers to remove. Consul removes only headers containing exact matches. Header names are not case-sensitive. | list of strings | + +#### Use variable placeholders + +For `add` and `set`, if the service is configured to use Envoy as the proxy, the value may contain variables to interpolate dynamic metadata into the value. For example, using the variable `%DOWNSTREAM_REMOTE_ADDRESS%` in your configuration entry allows you to pass a value that is generated when the routing occurs. + +### `spec.routes[].destination.responseHeaders` + +Specifies a set of HTTP-specific header modification rules applied to responses routed with the service router. You cannot configure request headers if the listener protocol is set to `tcp`. + +#### Values + +- Default: None +- Values: Object containing one or more fields that define header modification rules: + - `add`: Map of one or more string key-value pairs. + - `set`: Map of one or more string key-value pairs. + - `remove`: Map of one or more string key-value pairs. + +The following table describes how to configure values for response headers: + +| Rule | Description | Type | +| --- | --- | --- | +| `add` | Defines a set of key-value pairs to add to the header. Use header names as the keys. Header names are not case-sensitive. If header values with the same name already exist, the value is appended and Consul applies both headers. You can [use variable placeholders](#use-variable-placeholders). | map of strings | +| `set` | Defines a set of key-value pairs to add to the request header or to replace existing header values with. Use header names as the keys. Header names are not case-sensitive. If header values with the same names already exist, Consul replaces the header values. You can [use variable placeholders](#use-variable-placeholders). | map of strings | +| `remove` | Defines a list of headers to remove. Consul removes only headers containing exact matches. Header names are not case-sensitive. | list of strings | + +#### Use variable placeholders + +For `add` and `set`, if the service is configured to use Envoy as the proxy, the value may contain variables to interpolate dynamic metadata into the value. For example, using the variable `%DOWNSTREAM_REMOTE_ADDRESS%` in your configuration entry allows you to pass a value that is generated when the routing occurs. + + + + + +## Examples + +The following examples demonstrate common service router configuration patterns for specific use cases. ### Path prefix matching -Route HTTP requests with a path starting with `/admin` to a different service: +The following example routes HTTP requests with `/admin` at the start of their path to a service named `admin`. @@ -66,7 +891,6 @@ Routes = [ Service = "admin" } }, - # NOTE: a default catch-all will send unmatched traffic to "web" ] ``` @@ -82,7 +906,6 @@ spec: pathPrefix: /admin destination: service: admin - # NOTE: a default catch-all will send unmatched traffic to "web" ``` ```json @@ -106,9 +929,9 @@ spec: -### Header/query parameter matching +### Match a header and query parameter -Route HTTP requests with a special URL parameter or header to a canary subset: +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. @@ -148,7 +971,6 @@ Routes = [ ServiceSubset = "canary" } }, - # NOTE: a default catch-all will send unmatched traffic to "web" ] ``` @@ -175,7 +997,6 @@ spec: destination: service: web serviceSubset: canary - # NOTE: a default catch-all will send unmatched traffic to "web" ``` ```json @@ -223,8 +1044,7 @@ spec: ### gRPC routing -Re-route a gRPC method to another service. Since gRPC method calls [are -HTTP/2](https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-HTTP2.md), we can use an HTTP path match rule to re-route traffic: +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. @@ -243,7 +1063,6 @@ Routes = [ Service = "invoice-generator" } }, - # NOTE: a default catch-all will send unmatched traffic to "billing" ] ``` @@ -259,7 +1078,6 @@ spec: pathExact: /mycompany.BillingService/GenerateInvoice destination: service: invoice-generator - # NOTE: a default catch-all will send unmatched traffic to "billing" ``` ```json @@ -285,7 +1103,10 @@ spec: ### Retry logic -Enable retry logic by delegating this responsibility to Consul and the proxy. Review the [`ServiceRouteDestination`](#serviceroutedestination) block for more details. +The following example configures Consul so that when a request for the `orders` service passes through the service mesh, Consul routes the traffic to the `products` service or the `procurement` service based on the HTTP path that originated the request: + +- 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. @@ -295,7 +1116,7 @@ Kind = "service-router" Name = "orders" Routes = [ { - Match{ + Match { HTTP { PathPrefix = "/coffees" } @@ -303,14 +1124,14 @@ Routes = [ Destination { Service = "products" - RequestTimeout = "10s" - NumRetries = 3 + RequestTimeout = "15s" + NumRetries = 5 RetryOnConnectFailure = true RetryOn = ["reset"] } }, { - Match{ + Match { HTTP { PathPrefix = "/orders" } @@ -339,8 +1160,8 @@ spec: pathExact: /coffees destination: service: products - requestTimeout: 10s - numRetries: 3 + requestTimeout: 15s + numRetries: 5 retryOnConnectFailure: true retryOn: ['reset'] - match: @@ -367,8 +1188,8 @@ spec: } }, "Destination": { - "NumRetries": 3, - "RequestTimeout": "10s", + "NumRetries": 5, + "RequestTimeout": "15s", "RetryOnConnectFailure": true, "RetryOn": ["reset"], "Service": "procurement" @@ -392,413 +1213,4 @@ spec: } ``` - - -## Available Fields - -', - yaml: false, - }, - { - name: 'Namespace', - type: `string: "default"`, - enterprise: true, - description: - 'Specifies the namespace to which the configuration entry will apply.', - yaml: false, - }, - { - name: 'Partition', - type: `string: "default"`, - enterprise: true, - description: - 'Specifies the admin partition to which the configuration will apply.', - yaml: false, - }, - { - name: 'Meta', - type: 'map: nil', - description: - 'Specifies arbitrary KV metadata pairs. Added in Consul 1.8.4.', - yaml: false, - }, - { - name: 'metadata', - children: [ - { - name: 'name', - description: 'Set to the name of the service being configured.', - }, - { - name: 'namespace', - description: - 'If running Consul Open Source, the namespace is ignored (see [Kubernetes Namespaces in Consul OSS](/consul/docs/k8s/crds#consul-oss)). If running Consul Enterprise see [Kubernetes Namespaces in Consul Enterprise](/consul/docs/k8s/crds#consul-enterprise) for more details.', - }, - ], - hcl: false, - }, - { - name: 'Routes', - type: 'array', - description: `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.`, - children: [ - { - name: 'Match', - type: 'ServiceRouteMatch: ', - description: `A set of criteria that can - match incoming L7 requests. If empty or omitted it acts as a catch-all.`, - children: [ - { - name: 'HTTP', - type: 'ServiceRouteHTTPMatch: ', - description: `A set of [HTTP-specific match criteria](#serviceroutehttpmatch).`, - }, - ], - }, - { - name: 'Destination', - type: 'ServiceRouteDestination: ', - description: `Controls [how to proxy](#serviceroutedestination) the matching request(s) to a service.`, - }, - ], - }, - ]} -/> - -### `ServiceRouteHTTPMatch` - -
At most only one of `PathExact`, `PathPrefix`, or `PathRegex` may be configured.', - yaml: - 'Exact path to match on the HTTP request path.

At most only one of `pathExact`, `pathPrefix`, or `pathRegex` may be configured.', - }, - }, - { - name: 'PathPrefix', - type: 'string: ""', - description: { - hcl: - 'Path prefix to match on the HTTP request path.

At most only one of `PathExact`, `PathPrefix`, or `PathRegex` may be configured.', - yaml: - 'Path prefix to match on the HTTP request path.

At most only one of `pathExact`, `pathPrefix`, or `pathRegex` may be configured.', - }, - }, - { - name: 'PathRegex', - type: 'string: ""', - description: { - hcl: - 'Regular expression to match on the HTTP request path.

The syntax is [described below](#regular-expression-syntax).

At most only one of `PathExact`, `PathPrefix`, or `PathRegex` may be configured.', - yaml: - 'Regular expression to match on the HTTP request path.

The syntax is [described below](#regular-expression-syntax).

At most only one of `pathExact`, `pathPrefix`, or `pathRegex` may be configured.', - }, - }, - { - name: 'Methods', - type: 'array', - description: - 'A list of HTTP methods for which this match applies. If unspecified all HTTP methods are matched. If provided the names must be a valid [method](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods).', - }, - { - name: 'Header', - type: 'array)', - description: - '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.', - children: [ - { - name: 'Name', - type: 'string: ', - description: 'Name of the header to match.', - }, - { - name: 'Present', - type: 'bool: false', - description: { - hcl: - '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.', - yaml: - '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.', - }, - }, - { - name: 'Exact', - type: 'string: ""', - description: { - hcl: - '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.', - yaml: - '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.', - }, - }, - { - name: 'Prefix', - type: 'string: ""', - description: { - hcl: - '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.', - yaml: - '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.', - }, - }, - { - name: 'Suffix', - type: 'string: ""', - description: { - hcl: - '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.', - yaml: - '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.', - }, - }, - { - name: 'Regex', - type: 'string: ""', - description: { - hcl: - 'Match if the header with the given name matches this pattern.

The syntax is [described below](#regular-expression-syntax).

At most only one of `Exact`, `Prefix`, `Suffix`, `Regex`, or `Present` may be configured.', - yaml: - 'Match if the header with the given name matches this pattern.

The syntax is [described below](#regular-expression-syntax).

At most only one of `exact`, `prefix`, `suffix`, `regex`, or `present` may be configured.', - }, - }, - { - name: 'Invert', - type: 'bool: false', - description: 'Inverts the logic of the match', - }, - ], - }, - { - name: 'QueryParam', - type: 'array)', - description: - '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.', - children: [ - { - name: 'Name', - type: 'string: ', - description: 'The name of the query parameter to match on.', - }, - { - name: 'Present', - type: 'bool: false', - description: { - hcl: - '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.', - yaml: - '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.', - }, - }, - { - name: 'Exact', - type: 'string: ""', - description: { - hcl: - 'Match if the query parameter with the given name is this value.

At most only one of `Exact`, `Regex`, or `Present` may be configured.', - yaml: - 'Match if the query parameter with the given name is this value.

At most only one of `exact`, `regex`, or `present` may be configured.', - }, - }, - { - name: 'Regex', - type: 'string: ""', - description: { - hcl: - 'Match if the query parameter with the given name matches this pattern.

The syntax is [described below](#regular-expression-syntax).

At most only one of `Exact`, `Regex`, or `Present` may be configured.', - yaml: - 'Match if the query parameter with the given name matches this pattern.

The syntax is [described below](#regular-expression-syntax).

At most only one of `exact`, `regex`, or `present` may be configured.', - }, - }, - ], - }, - ]} -/> - -### `ServiceRouteDestination` - -
This requires that either `Match.HTTP.PathPrefix` or `Match.HTTP.PathExact` be configured on this route.', - yaml: - '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.', - }, - }, - { - name: 'RequestTimeout', - type: 'duration: 0', - description: - 'The total amount of time permitted for the entire downstream request (and retries) to be processed.', - }, - { - name: 'IdleTimeout', - type: 'duration: 0', - description: - 'The total amount of time permitted for the request stream to be idle', - }, - { - name: 'NumRetries', - type: 'int: 1', - description: { - hcl: 'The number of times to retry the request when a retryable result occurs. You cannot set the value to `0`. To disable retries, unset all other retry settings (`RetryOnConnectFailure`, `RetryOn`, `RetryOnStatusCodes`)', - yaml: 'The number of times to retry the request when a retryable result occurs. You cannot set the value to `0`. To disable retries, unset all other retry settings (`retryOnConnectFailure`, `retryOn`, `retryOnStatusCodes`)', - } - }, - { - name: 'RetryOnConnectFailure', - type: 'bool: false', - description: 'Allows for connection failure errors to trigger a retry.', - }, - { - name: 'RetryOn', - type: 'array', - description: `Allows Consul to retry requests when they meet one of the following sets of conditions: - \`5xx\`, \`gateway-error\`, \`reset\`, \`connect-failure\`, \`envoy-ratelimited\`, \`retriable-4xx\`, - \`refused-stream\`, \`cancelled\`, \`deadline-exceeded\`, \`internal\`, \`resource-exhausted\`, or \`unavailable\``, - }, - { - name: 'RetryOnStatusCodes', - type: 'array', - description: - 'A list of HTTP response status codes that are eligible for retry.', - }, - { - name: 'RequestHeaders', - type: 'HTTPHeaderModifiers: ', - description: `A set of [HTTP-specific header modification rules](/consul/docs/connect/config-entries/service-router#httpheadermodifiers) - that will be applied to requests routed to this service. - This cannot be used with a \`tcp\` listener.`, - }, - { - name: 'ResponseHeaders', - type: 'HTTPHeaderModifiers: ', - description: `A set of [HTTP-specific header modification rules](/consul/docs/connect/config-entries/service-router#httpheadermodifiers) - that will be applied to responses from this service. - This cannot be used with a \`tcp\` listener.`, - }, - ]} -/> - -### `HTTPHeaderModifiers` - -: optional', - description: `The set of key/value pairs that specify header values to add. - Use header names as keys. Header names are _not_ case-sensitive. - If header values with the same name already exist, the value set here will - be appended and both will be present. - If Envoy is used as the proxy, the value may contain - [variable placeholders](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_conn_man/headers#custom-request-response-headers) for example - \`%DOWNSTREAM_REMOTE_ADDRESS%\` to interpolate dynamic request - metadata into the value added.`, - }, - { - name: 'Set', - type: 'map: optional', - description: `The set of key/value pairs that specify header values to add. - Use header names as keys. Header names are _not_ case-sensitive. - If header values with the same name already exist, the value set here will - _replace_ them. - If Envoy is used as the proxy, the value may contain - [variable placeholders](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_conn_man/headers#custom-request-response-headers) for example - \`%DOWNSTREAM_REMOTE_ADDRESS%\` to interpolate dynamic request - metadata into the value added.`, - }, - { - name: 'Remove', - type: 'array: optional', - description: `The set of header names to remove. Only headers - whose names are a case-insensitive exact match will be removed`, - }, - ]} -/> - -## ACLs - -Configuration entries may be protected by [ACLs](/consul/docs/security/acl). - -Reading a `service-router` config entry requires `service:read` on the resource. - -Creating, updating, or deleting a `service-router` config entry requires -`service:write` on the resource and `service:read` on any other service referenced by -name in these fields: - -- [`Routes[].Destination.Service`](#service) - -## Regular Expression Syntax - -The actual syntax of the regular expression fields described here is entirely -proxy-specific. - -When using [Envoy](/consul/docs/connect/proxies/envoy) as a proxy (the only supported proxy in Kubernetes), -the syntax for these fields is version specific: - -| Envoy Version | Syntax | -| --------------- | ------------------------------------------------------------------- | -| 1.11.2 or newer | [documentation](https://github.com/google/re2/wiki/Syntax) | -| 1.11.1 or older | [documentation](https://en.cppreference.com/w/cpp/regex/ecmascript) | + \ No newline at end of file