--- layout: docs 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 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/manage-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: ```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 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 spec.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 spec.routes.match.http.header present: false exact: regex: destination: service: serviceSubset: namespace: partition: prefixRewrite: ## required specifying either spec.routes.match.http.pathPrefix or spec.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: None - Data type: String ### `Namespace` Specifies the namespace 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 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: - [`Match`](#routes-match) - [`Destination`](#routes-destination) ### `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 [`Routes[].Match{}.HTTP`](#routes-match-http) parameter. ### `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: - [`PathExact`](#routes-match-http-pathexact) - [`PathPrefix`](#routes-match-http-pathprefix) - [`PathRegex`](#routes-match-http-pathregex) - [`Methods`](#routes-match-http-methods) - [`Header`](#routes-match-http-header) - [`QueryParam`](#routes-match-http-queryparam) ### `Routes[].Match{}.HTTP{}.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 map. #### Values - Default: None - Data type: String ### `Routes[].Match{}.HTTP{}.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 map. #### Values - Default: None - Data type: String ### `Routes[].Match{}.HTTP{}.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 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. #### Values - Default: None - Data type: String ### `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. String values must be a valid [HTTP request method](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods). #### Values - Default: None - Data type: List of strings. Each string must match one of the following values: - `GET` - `HEAD` - `POST` - `PUT` - `DELETE` - `CONNECT` - `OPTIONS` - `TRACE` - `PATCH` ### `Routes[].Match{}.HTTP{}.Header` Specifies information in the HTTP request header to match with. 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 map. 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: - [`Name`](#routes-match-http-header-name) - [`Present`](#routes-match-http-header-present) - [`Exact`](#routes-match-http-header-exact) - [`Prefix`](#routes-match-http-header-prefix) - [`Suffix`](#routes-match-http-header-suffix) - [`Regex`](#routes-match-http-header-regex) - [`Invert`](#routes-match-http-header-invert) ### `Routes[].Match{}.HTTP{}.Header[].Name` Specifies the name of the HTTP header to match. This field is required when using [`Routes[].Match{}.HTTP{}.Header`](#routes-match-http-header). #### Values - Default: None - Data type: String ### `Routes[].Match{}.HTTP{}.Header[].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 map. #### Values - Default: `false` - Data type: Boolean ### `Routes[].Match{}.HTTP{}.Header[].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 map. #### Values - Default: None - Data type: String ### `Routes[].Match{}.HTTP{}.Header[].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 map. #### Values - Default: None - Data type: String ### `Routes[].Match{}.HTTP{}.Header[].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 map. #### Values - Default: None - Data type: String ### `Routes[].Match{}.HTTP{}.Header[].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 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. #### Values - Default: None - Data type: String ### `Routes[].Match{}.HTTP{}.Header[].Invert` Specifies that the logic for the HTTP header match should be inverted. Requests with matching criteria are not routed. #### Values - Default: `false` - Data type: Boolean ### `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: - [`Name`](#routes-match-http-queryparam-name) - [`Present`](#routes-match-http-queryparam-present) - [`Exact`](#routes-match-http-queryparam-exact) - [`Regex`](#routes-match-http-queryparam-regex) ### `Routes[].Match{}.HTTP{}.QueryParam[].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). #### Values - Default: None - Data type: String ### `Routes[].Match{}.HTTP{}.QueryParam[].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. #### Values - Default: `false` - Data type: Boolean ### `Routes[].Match{}.HTTP{}.QueryParam[].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. #### Values - Default: None - Data type: String ### `Routes[].Match{}.HTTP{}.QueryParam[].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. #### Values - Default: None - Data type: String ### `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: - [`Service`](#routes-destination-service) - [`ServiceSubset`](#routes-destination-servicesubset) - [`Namespace`](#routes-destination-namespace) - [`Partition`](#routes-destination-partition) - [`PrefixRewrite`](#routes-destination-prefixrewrite) - [`RequestTimeout`](#routes-destination-requesttimeout) - [`IdleTimeout`](#routes-destination-idletimeout) - [`NumRetries`](#routes-destination-numretries) - [`RetryOnConnectFailure`](#routes-destination-retryonconnectfailure) - [`RetryOn`](#routes-destination-retryon) - [`RetryOnStatusCodes`](#routes-destination-retryonstatuscodes) - [`RequestHeaders`](#routes-destination-requestheaders) - [`ResponseHeaders`](#routes-destination-responseheaders) ### `Routes[].Destination{}.Service` Specifies the name of the service to resolve. If this parameter is not specified, the default service name is inherited from the configuration entry’s [`Name` field](#name). #### Values - Default: None - Data type: String ### `Routes[].Destination{}.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 this parameter is not specified, the default subset is used. #### Values - Default: None - Data type: String ### `Routes[].Destination{}.Namespace` Specifies the Consul namespace to resolve the service from instead of the current namespace. If this parameter is not specified, the current namespace is used. #### Values - Default: None - Data type: String ### `Routes[].Destination{}.Partition` Specifies the Consul admin partition to resolve the service from instead of the current partition. If this parameter is not specified, the current partition is used. #### Values - Default: None - Data type: String ### `Routes[].Destination{}.PrefixRewrite` Specifies rewrites to the HTTP request path before proxying it to its final destination. This field requires that either [`Routes[].Match{}.HTTP{}.PathPrefix`](#routes-match-http-pathprefix) or [`Routes[].Match{}.HTTP{}.PathExact`](#routes-match-http-pathexact) be configured on this route. #### Values - Default: None - Data type: String ### `Routes[].Destination{}.RequestTimeout` Specifies the total amount of time permitted for the entire downstream request to be processed, including retry attempts. #### Values - Default: `0` - Data type: Integer ### `Routes[].Destination{}.IdleTimeout` Specifies the total amount of time permitted for the request stream to be idle. #### Values - Default: `0` - Data type: Integer ### `Routes[].Destination{}.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`. #### Values - Default: `1` - Data type: Integer ### `Routes[].Destination{}.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). #### Values - Default: `false` - Data type: Boolean ### `Routes[].Destination{}.RetryOn[]` Specifies a list of conditions for Consul to retry requests based on the response from an upstream service. 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). The following retry conditions are supported: | Conditions | Description | | :------------------- | :------------------------------------------------------------------------------------------------------- | | `5xx` | Consul retries the request when an upstream responds with any 5xx error code or does not respond at all. | | `gateway-error` | Consul retries the request when the upstream responds with a 502, 503, or 504 error. | | `reset` | Consul retries the request when the upstream does not respond at all. | | `connect-failure` | Consul retries the request when the connection to the upstream fails. | | `envoy-ratelimited` | Consul retries the request when the header `x-envoy-ratelimited` is present. | | `retriable-4xx` | Consul retries the request when the upstream responds with a retriable 4xx code. | | `refused-stream` | Consul retries the request when the upstream resets the stream with a `REFUSED_STREAM` error code. | | `cancelled` | Consul retries the request when the gRPC status code in the response headers is `cancelled`. | | `deadline-exceeded` | Consul retries the request when the gRPC status code in the response headers is `deadline-exceeded`. | | `internal` | Consul retries the request when the gRPC status code in the response headers is `internal`. | | `resource-exhausted` | Consul retries the request when the gRPC status code in the response headers is `resource-exhausted`. | | `unavailable` | Consul retries the request when the gRPC status code in the response headers is `unavailable`. | #### Values - Default: None - Data type: List of strings. Strings must match one of the following values: - `5xx` - `gateway-error` - `reset` - `connect-failure` - `envoy-ratelimited` - `retriable-4xx` - `refused-stream` - `cancelled` - `deadline-exceeded` - `internal` - `resource-exhausted` - `unavailable` ### `Routes[].Destination{}.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) #### Values - Default: None - Data type: List of integers ### `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: None - 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` Map that contains the details about the `ServiceRouter` configuration entry. The `apiVersion`, `kind`, and `metadata` fields are siblings of the spec field. All other configurations are children. #### 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: - [`match`](#spec-routes-match) - [`destination`](#spec-routes-destination) ### `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 [`spec.routes[].match.http`](#spec-routes-match-http) parameter. ### `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: - [`pathExact`](#spec-routes-match-http-pathexact) - [`pathPrefix`](#spec-routes-match-http-pathprefix) - [`pathRegex`](#spec-routes-match-http-pathregex) - [`methods`](#spec-routes-match-http-methods) - [`header`](#spec-routes-match-http-header) - [`queryParam`](#spec-routes-match-http-queryparam) ### `spec.routes[].match.http.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 map. #### Values - Default: None - Data type: String ### `spec.routes[].match.http.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 map. #### Values - Default: None - Data type: String ### `spec.routes[].match.http.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 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. #### Values - Default: None - Data type: String ### `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. String values must be a valid [HTTP request method](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods). #### Values - Default: None - Data type: List of strings. Each string must match one of the following values: - `GET` - `HEAD` - `POST` - `PUT` - `DELETE` - `CONNECT` - `OPTIONS` - `TRACE` - `PATCH` ### `spec.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 map. 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: - [`name`](#spec-routes-match-http-header-name) - [`present`](#spec-routes-match-http-header-present) - [`exact`](#spec-routes-match-http-header-exact) - [`prefix`](#spec-routes-match-http-header-prefix) - [`suffix`](#spec-routes-match-http-header-suffix) - [`regex`](#spec-routes-match-http-header-regex) - [`invert`](#spec-routes-match-http-header-invert) ### `spec.routes[].match.http.header.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). #### Values - Default: None - Data type: String ### `spec.routes[].match.http.header.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 map. #### Values - Default: `false` - Data type: Boolean ### `spec.routes[].match.http.header.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 map. #### Values - Default: None - Data type: String ### `spec.routes[].match.http.header.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 map. #### Values - Default: None - Data type: String ### `spec.routes[].match.http.header.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 map. #### Values - Default: None - Data type: String ### `spec.routes[].match.http.header.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 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. #### Values - Default: None - Data type: String ### `spec.routes[].match.http.header.invert` Specifies that the logic for the HTTP header match should be inverted. Requests with matching criteria are not routed. #### Values - Default: `false` - Data type: Boolean ### `spec.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: - [`name`](#spec-routes-match-http-queryparam-name) - [`present`](#spec-routes-match-http-queryparam-present) - [`regex`](#spec-routes-match-http-queryparam-regex) ### `spec.routes[].match.http.queryParam[].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). #### Values - Default: None - Data type: String ### `spec.routes[].match.http.queryParam[].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. #### Values - Default: `false` - Data type: Boolean ### `spec.routes[].match.http.queryParam[].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. #### Values - Default: None - Data type: String ### `spec.routes[].match.http.queryParam[].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. #### Values - Default: None - Data type: String ### `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: - [`service`](#spec-routes-destination-service) - [`serviceSubset`](#spec-routes-destination-servicesubset) - [`namespace`](#spec-routes-destination-namespace) - [`partition`](#spec-routes-destination-partition) - [`prefixRewrite`](#spec-routes-destination-prefixrewrite) - [`requestTimeout`](#spec-routes-destination-requesttimeout) - [`numRetries`](#spec-routes-destination-numretries) - [`numRetries`](#spec-routes-destination-numretries) - [`retryOnConnectFailure`](#spec-routes-destination-retryonconnectfailure) - [`retryOn`](#spec-routes-destination-retryon) - [`retryOnStatusCodes`](#spec-routes-destination-retryonstatuscodes) - [`requestHeaders`](#spec-routes-destination-requestheaders) - [`responseHeaders`](#spec-routes-destination-responseheaders) ### `spec.routes[].destination.service` Specifies the name of the service to resolve. If this parameter is not specified, the default service name is inherited from the configuration entry’s [`metadata.name` field](#metadata-name). #### Values - Default: None - Data type: String ### `spec.routes[].destination.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 this parameter is not specified, the default subset is used. #### Values - Default: None - Data type: String ### `spec.routes[].destination.namespace` Specifies the Consul namespace to resolve the service from instead of the current namespace. If this parameter is not specified, the current namespace is used. #### Values - Default: None - Data type: String ### `spec.routes[].destination.partition` Specifies the Consul admin partition to resolve the service from instead of the current partition. If this parameter is not specified, the current partition is used. #### Values - Default: None - Data type: String ### `spec.routes[].destination.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. #### Values - Default: None - Data type: String ### `spec.routes[].destination.requestTimeout` Specifies the total amount of time permitted for the entire downstream request to be processed, including retry attempts. #### Values - Default: `0` - Data type: Integer ### `spec.routes[].destination.idleTimeout` Specifies the total amount of time permitted for the request stream to be idle. #### Values - Default: `0` - Data type: Integer ### `spec.routes[].destination.numRetries` Specifies the number of times to retry the request when a retry condition occurs. Configure this field and other retry fields in `spec.routes.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`. #### Values - Default: `1` - Data type: Integer ### `spec.routes[].destination.retryOnConnectFailure` Specifies that connection failure errors that trigger a retry request. Configure this field and other retry fields in `spec.routes[].destination` to configure the logic for retry attempts. For examples, refer to the [retry logic example configurations](#retry-logic). #### Values - Default: `false` - Data type: Boolean ### `spec.routes[].destination.retryOn` Specifies a list of conditions for Consul to retry requests based on the response from an upstream service. Configure this field and other retry fields in the `spec.routes[].destination` object to configure the logic for retry attempts. For examples, refer to the [retry logic example configurations](#retry-logic). The following retry conditions are supported: | Conditions | Description | | :------------------- | :------------------------------------------------------------------------------------------------------- | | `5xx` | Consul retries the request when an upstream responds with any 5xx error code or does not respond at all. | | `gateway-error` | Consul retries the request when the upstream responds with a 502, 503, or 504 error. | | `reset` | Consul retries the request when the upstream does not respond at all. | | `connect-failure` | Consul retries the request when the connection to the upstream fails. | | `envoy-ratelimited` | Consul retries the request when the header `x-envoy-ratelimited` is present. | | `retriable-4xx` | Consul retries the request when the upstream responds with a retriable 4xx code. | | `refused-stream` | Consul retries the request when the upstream resets the stream with a `REFUSED_STREAM` error code. | | `cancelled` | Consul retries the request when the gRPC status code in the response headers is `cancelled`. | | `deadline-exceeded` | Consul retries the request when the gRPC status code in the response headers is `deadline-exceeded`. | | `internal` | Consul retries the request when the gRPC status code in the response headers is `internal`. | | `resource-exhausted` | Consul retries the request when the gRPC status code in the response headers is `resource-exhausted`. | | `unavailable` | Consul retries the request when the gRPC status code in the response headers is `unavailable`. | #### Values - Default: None - Data type: List of strings. Strings must match one of the following values: - `5xx` - `gateway-error` - `reset` - `connect-failure` - `envoy-ratelimited` - `retriable-4xx` - `refused-stream` - `cancelled` - `deadline-exceeded` - `internal` - `resource-exhausted` - `unavailable` ### `spec.routes[].destination.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 `spec.routes[].destination` 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 integers ### `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 The following example routes HTTP requests for the `web` service to a service named `admin` when they have `/admin` at the start of their path. ```hcl Kind = "service-router" Name = "web" Routes = [ { Match { HTTP { PathPrefix = "/admin" } } Destination { Service = "admin" } }, ] ``` ```yaml apiVersion: consul.hashicorp.com/v1alpha1 kind: ServiceRouter metadata: name: web spec: routes: - match: http: pathPrefix: /admin destination: service: admin ``` ```json { "Kind": "service-router", "Name": "web", "Routes": [ { "Match": { "HTTP": { "PathPrefix": "/admin" } }, "Destination": { "Service": "admin" } } ] } ``` ### 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. ```hcl Kind = "service-router" Name = "web" Routes = [ { Match { HTTP { Header = [ { Name = "x-debug" Exact = "1" }, ] } } Destination { Service = "web" ServiceSubset = "canary" } }, { Match { HTTP { QueryParam = [ { Name = "x-debug" Exact = "1" }, ] } } Destination { Service = "web" ServiceSubset = "canary" } }, ] ``` ```yaml apiVersion: consul.hashicorp.com/v1alpha1 kind: ServiceRouter metadata: name: web spec: routes: - match: http: header: - name: x-debug exact: '1' destination: service: web serviceSubset: canary - match: http: queryParam: - name: x-debug exact: '1' destination: service: web serviceSubset: canary ``` ```json { "Kind": "service-router", "Name": "web", "Routes": [ { "Match": { "HTTP": { "Header": [ { "Name": "x-debug", "Exact": "1" } ] } }, "Destination": { "Service": "web", "ServiceSubset": "canary" } }, { "Match": { "HTTP": { "QueryParam": [ { "Name": "x-debug", "Exact": "1" } ] } }, "Destination": { "Service": "web", "ServiceSubset": "canary" } } ] } ``` ### 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. ```hcl Kind = "service-router" Name = "billing" Routes = [ { Match { HTTP { PathExact = "/mycompany.BillingService/GenerateInvoice" } } Destination { Service = "invoice-generator" } }, ] ``` ```yaml apiVersion: consul.hashicorp.com/v1alpha1 kind: ServiceRouter metadata: name: billing spec: routes: - match: http: pathExact: /mycompany.BillingService/GenerateInvoice destination: service: invoice-generator ``` ```json { "Kind": "service-router", "Name": "billing", "Routes": [ { "Match": { "HTTP": { "PathExact": "/mycompany.BillingService/GenerateInvoice" } }, "Destination": { "Service": "invoice-generator" } } ] } ``` ### Retry logic 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. ```hcl Kind = "service-router" Name = "orders" Routes = [ { Match { HTTP { PathPrefix = "/coffees" } } Destination { Service = "products" RequestTimeout = "15s" NumRetries = 5 RetryOnConnectFailure = true RetryOn = ["reset"] } }, { Match { HTTP { PathPrefix = "/orders" } } Destination { Service = "procurement" RequestTimeout = "10s" NumRetries = 3 RetryOnConnectFailure = true RetryOn = ["reset"] } } ] ``` ```yaml apiVersion: consul.hashicorp.com/v1alpha1 kind: ServiceRouter metadata: name: orders spec: routes: - match: http: pathExact: /coffees destination: service: products requestTimeout: 15s numRetries: 5 retryOnConnectFailure: true retryOn: ['reset'] - match: http: pathExact: /orders destination: service: procurement requestTimeout: 10s numRetries: 3 retryOnConnectFailure: true retryOn: ['reset'] ``` ```json { "Kind": "service-router", "Name": "orders", "Routes": [ { "Match": { "HTTP": { "PathPrefix": "/coffees" } }, "Destination": { "NumRetries": 5, "RequestTimeout": "15s", "RetryOnConnectFailure": true, "RetryOn": ["reset"], "Service": "procurement" } }, { "Match": { "HTTP": { "PathPrefix": "/orders" } }, "Destination": { "NumRetries": 3, "RequestTimeout": "10s", "RetryOnConnectFailure": true, "RetryOn": ["reset"], "Service": "procurement" } } ] } ```