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 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: string | required | must be set to service-router
• Name: string | required
• Namespace: string EnterpriseEnterprise
• Partition: string | default EnterpriseEnterprise
• Meta: map

• Routes: list

  • Match: map
    • HTTP: map
      • PathExact: string
      • PathPrefix: string
      • PathRegex: string
      • Methods: list
      • Header: list
        • Name: string
        • Present: boolean | false
        • Exact: string
        • Prefix: string
        • Suffix: string
        • Regex: string
        • Invert: boolean | false
      • QueryParam: list
        • Name: string
        • Present: boolean | false
        • Exact: string
        • Regex: string
  • Destination: map
    • Service: string
    • ServiceSubset: string
    • Namespace: string EnterpriseEnterprise
    • Partition: string EnterpriseEnterprise
    • PrefixRewrite: string
    • RequestTimeout: integer | 0
    • IdleTimeout: integer | 0
    • NumRetries: integer | 1
    • RetryOnConnectFailure: boolean | false
    • RetryOn: list
    • RetryOnStatusCodes: list
    • RequestHeaders: map
      • Add: map
      • Set: map
      • Remove: map
    • ResponseHeaders: map
      • Add: map
      • Set: map
      • Remove: map

• apiVersion: string | required | must be set to consul.hashicorp.com/v1alpha1

• kind: string | required | must be set to ServiceRouter
• metadata: map | required
  • name: string | required
  • namespace: string | optional EnterpriseEnterprise
• spec: map | required
  • routes: list
    • match: map
      • http: map
        • pathExact: string
        • pathPrefix: string
        • pathRegex: string
        • methods: list
        • header: list
          • name: string
          • present: boolean | false
          • exact: string
          • prefix: string
          • suffix: string
          • regex: string
          • invert: boolean
        • queryParam: list
          • name: string
          • present: boolean | false
          • regex: string
    • destination: map
      • service: string
      • serviceSubset: string
      • namespace: string EnterpriseEnterprise
      • partition: string EnterpriseEnterprise
      • prefixRewrite: string
      • requestTimeout: integer | 0
      • numRetries: integer | 0
      • numRetries: integer | 1
      • retryOnConnectFailure: boolean | false
      • retryOn: list
      • retryOnStatusCodes: list
      • requestHeaders: map
        • add: map
        • set: map
        • remove: map
      • responseHeaders: map
        • add: map
        • set: map
        • remove: map

Complete configuration

When every field is defined, a service router configuration entry has the following form:

Kind      = "service-router"                             ## required
Name      = "<service-name>"                             ## required
Namespace = "<namespace-configuration-applies-to>"
Partition = "<partition-configuration-applies-to>"
Meta = {
 <key> = "<value>"
}
Routes = [
 {
   Match {
     HTTP {
       PathExact = "<exact/http/path>"                    ## cannot specify with PathPrefix or PathRegex
     },
     HTTP {
       PathPrefix = "<path/prefix>"                       ## cannot specify with PathExact or PathRegex
     },
     HTTP {
       PathRegex = "<regex/path>"                         ## 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    = "<header-to-match>"                  ## required when specifying Routes.Match.HTTP.Header
           Present = false
           Exact   = "<exact-match-name>"
           Prefix  = "<prefix-to-match>"
           Suffix  = "<suffix-to-match>"
           Regex   = "<regex-to-match>"
           Invert  = false
         }
       ]
     }
     HTTP {
      QueryParam = [                                       ## do not specify Present, Exact, and Regex in a single QueryParam
        Name   = "<text-to-match-in-query-parameter>"      ## required when specifying Routes.Match.HTTP.Header
        Present = false
        Exact = "<exact-text-to-match-in-query-parameter>"
        Regex = "<regex-to-match-in-query-paramater>"
      ]
     }
   },
     Destination {
       Service               = "<service-name-at-destination>"
       ServiceSubset         = "<service-subset-at-destination>"
       Namespace             = "<namespace-at-destination>"
       Partition             = "<partition-at-destination>"
       PrefixRewrite         = "<new-prefix-after-routing>"   ## required specifying either Routes.Match.HTTP.PathPrefix or Routes.Match.HTTP.PathExact
       RequestTimeout        = 0 
       IdleTimeout           = 0
       NumRetries            = 1
       RetryOnConnectFailure = false
       RetryOn               = ["reset", "unavailable"]
       RetryOnStatusCodes    = [500, 502, 503]
       RequestHeaders = {
         Set = {
           "X-Web-Version" : "<text-string>"
         }
       }
       ResponseHeaders = {
         Set = {
           "X-Web-Version" : "<text-string>"
         }
       }
     }
 }
]

{
  "Kind": "service-router",                                 // required
  "Name": "<service-name>",                                 // required
  "Namespace": "<namespace-configuration-applies-to>",
  "Partition": "<partition-configuration-applies-to>",
  "Meta": {
   "<key>": "<value>"
  },
  "Routes": [
   {
    "Match": {
      "HTTP": {
        "PathExact": "<exact/http/path>"                     // cannot specify with PathPrefix or PathRegex
      },
      "HTTP": { 
        "PathPrefix": "<path/prefix>"                        // cannot specify with PathExact or PathRegex
      }, 
      "HTTP": {
       "PathRegex": "<regex/path>"                           // 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": "<header-to-match>",                      // required when specifying Routes.Match.HTTP.Header
           "Present": false,
           "Exact": "<exact-match-name>",
           "Prefix": "<prefix-to-match>",
           "Suffix": "<suffix-to-match>",
           "Regex": "<regex-to-match>",
           "Invert": false,
         }
        ]
      },
      "HTTP": {
       "QueryParam": [                                         // do not specify Present, Exact, and Regex in a single QueryParam
         "Name": "<text-to-match-in-query-parameter>",         // required when specifying Routes.Match.HTTP.Header
         "Present": false,
         "Exact": "<exact-text-to-match-in-query-parameter>",
         "Regex": "<regex-to-match-in-query-paramater>"
       ]
      }
    },
     "Destination": {
       "Service": "<service-name-at-destination>",
       "ServiceSubset": "<service-subset-at-destination>",
       "Namespace": "<namespace-at-destination>",
       "Partition": "<partition-at-destination>",
       "PrefixRewrite": "<new-prefix-after-routing>",           // required specifying either Routes.Match.HTTP.PathPrefix or Routes.Match.HTTP.PathExact
       "RequestTimeout": 0, 
       "IdleTimeout": 0,
       "NumRetries": 1,
       "RetryOnConnectFailure": false,
       "RetryOn": ["reset", "unavailable"],
       "RetryOnStatusCodes": [500, 502, 503],
       "RequestHeaders": {
         "Set":  {
           "X-Web-Version" : "<text-string>"
         }
       },
       "ResponseHeaders": {
         "Set": {
           "X-Web-Version" : "<text-string>"
         }
       }
     }
  }
 ]
}

apiVersion: consul.hashicorp.com/v1alpha1                  # required
kind: ServiceRouter                                        # required            
metadata:
  name: <serviceName>
  namespace: <namespace>
spec:
  routes:
    - match:
       http:
         pathExact: <exact/http/path>                      ## cannot specify with pathPrefix or pathRegex
       http:
         pathPrefix: <path/prefix>                         ## cannot specify with pathExact or pathRegex
       http:
         pathRegex: <regex/path>                           ## 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: <header-to-match>                        ## required when specifying spec.routes.match.http.header
            present: false
            exact: <exact-match-name>
            prefix: <prefix-to-match>
            suffix: <suffix-to-match>
            regex: <regex-to-match>
            invert: false
       http:
         queryParam:                                        ## do not specify present, exact, and regex in a single queryParam
          - name: <text-to-match-in-query-parameter>        ## required when specifying spec.routes.match.http.header
            present: false
            exact: <exact-text-to-match-in-query-parameter>
            regex: <regex-to-match-in-query-paramater>
    destination:
       service: <service-name-at-destination>
       serviceSubset: <service-subset-at-destination>
       namespace: <namespace-at-destination>
       partition: <partition-at-destination>
       prefixRewrite: <new-prefix-after-routing>             ## 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: <text-string>
       responseHeaders:
         set:
           x-Web-Version: <text-string>

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.

Values

• Default: None
• Data type: String

Namespace EnterpriseEnterprise

Specifies the namespace to apply the configuration entry to. Refer to Namespaces for additional information about Consul namespaces.

Values

• Default: None
• Data type: String

Partition EnterpriseEnterprise

Specifies the admin partition to apply the configuration entry to. Refer to 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

• 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 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
  • PathPrefix
  • PathRegex
  • Methods
  • Header
  • 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, refer to the documentation for Envoy v1.11.2 or newer or the documentation for Envoy v1.11.1 or older, 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.

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
  • Present
  • Exact
  • Prefix
  • Suffix
  • Regex
  • 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.

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, refer to the documentation for Envoy v1.11.2 or newer or the documentation for Envoy v1.11.1 or older, 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
  • Present
  • Exact
  • 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.

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, refer to the documentation for Envoy v1.11.2 or newer or the documentation for Envoy v1.11.1 or older, 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
  • ServiceSubset
  • Namespace
  • Partition
  • PrefixRewrite
  • RequestTimeout
  • IdleTimeout
  • NumRetries
  • RetryOnConnectFailure
  • RetryOn
  • RetryOnStatusCodes
  • RequestHeaders
  • 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.

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. 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 or 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. 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.

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.

The following retry conditions are supported:

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 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

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:

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:

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 EnterpriseEnterprise

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 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 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

• 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 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
  • pathPrefix
  • pathRegex
  • methods
  • header
  • 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, refer to the documentation for Envoy v1.11.2 or newer or the documentation for Envoy v1.11.1 or older, 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.

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
  • present
  • exact
  • prefix
  • suffix
  • regex
  • 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.

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, refer to the documentation for Envoy v1.11.2 or newer or the documentation for Envoy v1.11.1 or older, 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
  • present
  • 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.

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, refer to the documentation for Envoy v1.11.2 or newer or the documentation for Envoy v1.11.1 or older, 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
  • serviceSubset
  • namespace
  • partition
  • prefixRewrite
  • requestTimeout
  • numRetries
  • numRetries
  • retryOnConnectFailure
  • retryOn
  • retryOnStatusCodes
  • requestHeaders
  • 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.

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. 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 or 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. 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.

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.

The following retry conditions are supported:

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 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

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:

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:

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.

Kind = "service-router"
Name = "web"
Routes = [
  {
    Match {
      HTTP {
        PathPrefix = "/admin"
      }
    }
    Destination {
      Service = "admin"
    }
  },
]

apiVersion: consul.hashicorp.com/v1alpha1
kind: ServiceRouter
metadata:
  name: web
spec:
  routes:
    - match:
        http:
          pathPrefix: /admin
      destination:
        service: admin

{
  "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.

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"
    }
  },
]

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

{
  "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-generatorservice 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.

Kind = "service-router"
Name = "billing"
Routes = [
  {
    Match {
      HTTP {
        PathExact = "/mycompany.BillingService/GenerateInvoice"
      }
    }
    Destination {
      Service = "invoice-generator"
    }
  },
]

apiVersion: consul.hashicorp.com/v1alpha1
kind: ServiceRouter
metadata:
  name: billing
spec:
  routes:
    - match:
        http:
          pathExact: /mycompany.BillingService/GenerateInvoice
      destination:
        service: invoice-generator

{
  "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.

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"]
    }
  }
]

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']

{
    "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"
            }
        }
    ]
}