layout | page_title | description |
---|---|---|
docs |
Service Router - Configuration Entry Reference |
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. |
The service-router
config entry kind (ServiceRouter
on Kubernetes) controls Connect traffic routing and
manipulation at networking layer 7 (e.g. HTTP).
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.
- Consul service mesh connect enabled services
- Service to service communication over the protocol
http
- Consul 1.8.4+ on Kubernetes.
- Consul 1.5.0+ on other platforms.
-> v1.8.4+: On Kubernetes, the ServiceRouter
custom resource is supported in Consul versions 1.8.4+.
v1.6.0+: On other platforms, this config entry is supported in Consul versions 1.6.0+.
-
Service router config entries are a component of L7 Traffic Management.
-
Service router config entries are restricted to only services that define their protocol as HTTP-based via a corresponding
service-defaults
config entry or globally viaproxy-defaults
. -
Any route destination that omits the
ServiceSubset
field is eligible for splitting via aservice-splitter
should one be configured for that service, otherwise resolution proceeds according to any configuredservice-resolver
.
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.
Route HTTP requests with a path starting with /admin
to a different service:
<CodeTabs tabs={[ "HCL", "Kubernetes YAML", "JSON" ]}>
Kind = "service-router"
Name = "web"
Routes = [
{
Match {
HTTP {
PathPrefix = "/admin"
}
}
Destination {
Service = "admin"
}
},
# NOTE: a default catch-all will send unmatched traffic to "web"
]
apiVersion: consul.hashicorp.com/v1alpha1
kind: ServiceRouter
metadata:
name: web
spec:
routes:
- match:
http:
pathPrefix: /admin
destination:
service: admin
# NOTE: a default catch-all will send unmatched traffic to "web"
{
"Kind": "service-router",
"Name": "web",
"Routes": [
{
"Match": {
"HTTP": {
"PathPrefix": "/admin"
}
},
"Destination": {
"Service": "admin"
}
}
]
}
Route HTTP requests with a special URL parameter or header to a canary subset:
<CodeTabs tabs={[ "HCL", "Kubernetes YAML", "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"
}
},
# NOTE: a default catch-all will send unmatched traffic to "web"
]
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
# NOTE: a default catch-all will send unmatched traffic to "web"
{
"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"
}
}
]
}
Re-route a gRPC method to another service. Since gRPC method calls are HTTP/2, we can use an HTTP path match rule to re-route traffic:
<CodeTabs tabs={[ "HCL", "Kubernetes YAML", "JSON" ]}>
Kind = "service-router"
Name = "billing"
Routes = [
{
Match {
HTTP {
PathExact = "/mycompany.BillingService/GenerateInvoice"
}
}
Destination {
Service = "invoice-generator"
}
},
# NOTE: a default catch-all will send unmatched traffic to "billing"
]
apiVersion: consul.hashicorp.com/v1alpha1
kind: ServiceRouter
metadata:
name: billing
spec:
routes:
- match:
http:
pathExact: /mycompany.BillingService/GenerateInvoice
destination:
service: invoice-generator
# NOTE: a default catch-all will send unmatched traffic to "billing"
{
"Kind": "service-router",
"Name": "billing",
"Routes": [
{
"Match": {
"HTTP": {
"PathExact": "/mycompany.BillingService/GenerateInvoice"
}
},
"Destination": {
"Service": "invoice-generator"
}
}
]
}
Enable retry logic by delegating this responsibility to Consul and the proxy. Review the ServiceRouteDestination
block for more details.
<CodeTabs tabs={[ "HCL", "Kubernetes YAML", "JSON" ]}>
Kind = "service-router"
Name = "orders"
Routes = [
{
Match{
HTTP {
PathPrefix = "/coffees"
}
}
Destination {
Service = "products"
RequestTimeout = "10s"
NumRetries = 3
RetryOnConnectFailure = true
RetryOn = ["reset"]
}
},
{
Match{
HTTP {
PathPrefix = "/orders"
}
}
Destination {
Service = "procurement"
RequestTimeout = "10s"
NumRetries = 3
RetryOnConnectFailure = true
RetryOn = ["reset"]
}
}
]
apiVersion: consul.hashicorp.com/v1alpha1
kind: ServiceRouter
metadata:
name: orders
spec:
routes:
- match:
http:
pathExact: /coffees
destination:
service: products
requestTimeout: 10s
numRetries: 3
retryOnConnectFailure: true
retryOn: ['reset']
- match:
http:
pathExact: /orders
destination:
service: procurement
requestTimeout: 10s
numRetries: 3
retryOnConnectFailure: true
retryOn: ['reset']
{
"Kind": "service-router",
"Name": "orders",
"Routes": [
{
"Match": {
"HTTP": {
"PathPrefix": "/coffees"
}
},
"Destination": {
"NumRetries": 3,
"RequestTimeout": "10s",
"RetryOnConnectFailure": true,
"RetryOn": ["reset"],
"Service": "procurement"
}
},
{
"Match": {
"HTTP": {
"PathPrefix": "/orders"
}
},
"Destination": {
"NumRetries": 3,
"RequestTimeout": "10s",
"RetryOnConnectFailure": true,
"RetryOn": ["reset"],
"Service": "procurement"
}
}
]
}
<ConfigEntryReference
keys={[
{
name: 'apiVersion',
description: 'Must be set to consul.hashicorp.com/v1alpha1
',
hcl: false,
},
{
name: 'Kind',
description: {
hcl: 'Must be set to service-router
',
yaml: 'Must be set to ServiceRouter
',
},
},
{
name: 'Name',
description: 'Set to the name of the service being configured.',
type: 'string: ',
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<string|string>: 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). If running Consul Enterprise see Kubernetes Namespaces in 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.
,
},
],
},
]}
/>
<ConfigEntryReference
topLevel={false}
keys={[
{
name: 'PathExact',
type: 'string: ""',
description: {
hcl:
'Exact path to match on the HTTP request path.
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.
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.
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.',
},
{
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.
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.
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.
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.
At most only one of exact
, regex
, or present
may be configured.',
},
},
],
},
]}
/>
<ConfigEntryReference
topLevel={false}
keys={[
{
name: 'Service',
type: 'string: ""',
description:
'The service to resolve instead of the default service. If empty then the default service name is used.',
},
{
name: 'ServiceSubset',
type: 'string: ""',
description: {
hcl:
"A named subset of the given service to resolve instead of the one defined as that service's DefaultSubset
. If empty, the default subset is used.",
yaml:
"A named subset of the given service to resolve instead of the one defined as that service's defaultSubset
. If empty, the default subset is used.",
},
},
{
name: 'Namespace',
type: 'string: ""',
description:
'The Consul namespace to resolve the service from instead of the current namespace. If empty, the current namespace is used.',
enterprise: true,
},
{
name: 'Partition',
type: 'string: ""',
description:
'The Consul admin partition to resolve the service from instead of the current partition. If empty, the current partition is used.',
enterprise: true,
},
{
name: 'PrefixRewrite',
type: 'string: ""',
description: {
hcl:
'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.',
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: 0',
description:
'The number of times to retry the request when a retryable result occurs.',
},
{
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<int>', description: 'A list of HTTP response status codes that are eligible for retry.', }, { name: 'RequestHeaders', type: 'HTTPHeaderModifiers: <optional>', description:
A set of HTTP-specific header modification rules
that will be applied to requests routed to this service.
This cannot be used with a `tcp` listener., }, { name: 'ResponseHeaders', type: 'HTTPHeaderModifiers: <optional>', description:
A set of HTTP-specific header modification rules
that will be applied to responses from this service.
This cannot be used with a `tcp` listener.`,
},
]}
/>
<ConfigEntryReference
topLevel={false}
keys={[
{
name: 'Add',
type: 'map<string|string>: 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<string|string>: 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 for example
`%DOWNSTREAM_REMOTE_ADDRESS%` to interpolate dynamic request
metadata into the value added., }, { name: 'Remove', type: 'array<string>: optional', description:
The set of header names to remove. Only headers
whose names are a case-insensitive exact match will be removed`,
},
]}
/>
Configuration entries may be protected by ACLs.
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:
The actual syntax of the regular expression fields described here is entirely proxy-specific.
When using 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 |
1.11.1 or older | documentation |