Service router configuration 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 Enterprise
Partition: string | default Enterprise
Meta: map
Routes: list
- Match: map
  - HTTP: map
    - PathExact: string
    - PathPrefix: string
    - PathRegex: string
    - CaseInsensitive: boolean | false
    - 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 Enterprise
  - Partition: string Enterprise
  - 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 Enterprise
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 Enterprise
    - partition: string Enterprise
    - 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-parameter>"
      ]
     }
   },


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

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

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

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

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
- <KEY>: String
- <VALUE>: 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:

`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{}.CaseInsensitive`

Specifies the path prefix to match on the HTTP request path must be case insensitive or not.

Values

Default: false
Data type: Boolean

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

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

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

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

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

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:

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

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

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

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`

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:

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

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

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

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

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

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:

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

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

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

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

Path prefix matching with case insensitive

The following example routes HTTP requests for the web service to a service named admin when they have /admin or /Admin at the start of their path.

Kind = "service-router"
Name = "web"
Routes = [
  {
    Match {
      HTTP {
        PathPrefix = "/Admin"
        CaseInsensitive = true
      }
    }

    Destination {
      Service = "admin"
    }
  },
]

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

{
  "Kind": "service-router",
  "Name": "web",
  "Routes": [
    {
      "Match": {
        "HTTP": {
          "PathPrefix": "/Admin",
          "CaseInsensitive": true
        }
      },
      "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"
            }
        }
    ]
}

Service router configuration reference

Configuration model

Complete configuration

Specification

Kind

Values

Name

Values

Namespace EnterpriseEnterprise

Values

Partition EnterpriseEnterprise

Values

Meta

Values

Routes

Values

Routes[].Match

Values

Routes[].Match{}.HTTP

Values

Routes[].Match{}.HTTP{}.PathExact

Values

Routes[].Match{}.HTTP{}.PathPrefix

Values

Routes[].Match{}.HTTP{}.CaseInsensitive

Values

Routes[].Match{}.HTTP{}.PathRegex

Values

Routes[].Match{}.HTTP{}.Methods

Values

Routes[].Match{}.HTTP{}.Header

Values

Routes[].Match{}.HTTP{}.Header[].Name

Values

Routes[].Match{}.HTTP{}.Header[].Present

Values

Routes[].Match{}.HTTP{}.Header[].Exact

Values

Routes[].Match{}.HTTP{}.Header[].Prefix

Values

Routes[].Match{}.HTTP{}.Header[].Suffix

Values

Routes[].Match{}.HTTP{}.Header[].Regex

Values

Routes[].Match{}.HTTP{}.Header[].Invert

Values

Routes[].Match{}.HTTP{}.QueryParam

Values

Routes[].Match{}.HTTP{}.QueryParam[].Name

Values

Routes[].Match{}.HTTP{}.QueryParam[].Present

Values

Routes[].Match{}.HTTP{}.QueryParam[].Exact

Values

Routes[].Match{}.HTTP{}.QueryParam[].Regex

Values

Routes[].Destination

Values

Routes[].Destination{}.Service

Values

Routes[].Destination{}.ServiceSubset

Values

Routes[].Destination{}.Namespace

Values

Routes[].Destination{}.Partition

Values

Routes[].Destination{}.PrefixRewrite

Values

Routes[].Destination{}.RequestTimeout

Values

Routes[].Destination{}.IdleTimeout

Values

Routes[].Destination{}.NumRetries

Values

Routes[].Destination{}.RetryOnConnectFailure

Values

Routes[].Destination{}.RetryOn[]

Values

Routes[].Destination{}.RetryOnStatusCodes

Values

`Kind`

`Name`

`Namespace` Enterprise

`Partition` Enterprise

`Meta`

`Routes`

`Routes[].Match`

`Routes[].Match{}.HTTP`

`Routes[].Match{}.HTTP{}.PathExact`

`Routes[].Match{}.HTTP{}.PathPrefix`

`Routes[].Match{}.HTTP{}.CaseInsensitive`

`Routes[].Match{}.HTTP{}.PathRegex`

`Routes[].Match{}.HTTP{}.Methods`

`Routes[].Match{}.HTTP{}.Header`

`Routes[].Match{}.HTTP{}.Header[].Name`

`Routes[].Match{}.HTTP{}.Header[].Present`

`Routes[].Match{}.HTTP{}.Header[].Exact`

`Routes[].Match{}.HTTP{}.Header[].Prefix`

`Routes[].Match{}.HTTP{}.Header[].Suffix`

`Routes[].Match{}.HTTP{}.Header[].Regex`

`Routes[].Match{}.HTTP{}.Header[].Invert`

`Routes[].Match{}.HTTP{}.QueryParam`

`Routes[].Match{}.HTTP{}.QueryParam[].Name`

`Routes[].Match{}.HTTP{}.QueryParam[].Present`

`Routes[].Match{}.HTTP{}.QueryParam[].Exact`

`Routes[].Match{}.HTTP{}.QueryParam[].Regex`

`Routes[].Destination`

`Routes[].Destination{}.Service`

`Routes[].Destination{}.ServiceSubset`

`Routes[].Destination{}.Namespace`

`Routes[].Destination{}.Partition`

`Routes[].Destination{}.PrefixRewrite`

`Routes[].Destination{}.RequestTimeout`

`Routes[].Destination{}.IdleTimeout`

`Routes[].Destination{}.NumRetries`

`Routes[].Destination{}.RetryOnConnectFailure`

`Routes[].Destination{}.RetryOn[]`

`Routes[].Destination{}.RetryOnStatusCodes`

`Routes[].Destination{}.RequestHeaders`

`Routes[].Destination{}.ResponseHeaders`