HashiCorp Developer AI Private beta now available Sign up today
Consul
Consul Home

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.

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

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

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

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

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

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

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

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:

ConditionsDescription
5xxConsul retries the request when an upstream responds with any 5xx error code or does not respond at all.
gateway-errorConsul retries the request when the upstream responds with a 502, 503, or 504 error.
resetConsul retries the request when the upstream does not respond at all.
connect-failureConsul retries the request when the connection to the upstream fails.
envoy-ratelimitedConsul retries the request when the header x-envoy-ratelimited is present.
retriable-4xxConsul retries the request when the upstream responds with a retriable 4xx code.
refused-streamConsul retries the request when the upstream resets the stream with a REFUSED_STREAM error code.
cancelledConsul retries the request when the gRPC status code in the response headers is cancelled.
deadline-exceededConsul retries the request when the gRPC status code in the response headers is deadline-exceeded.
internalConsul retries the request when the gRPC status code in the response headers is internal.
resource-exhaustedConsul retries the request when the gRPC status code in the response headers is resource-exhausted.
unavailableConsul retries the request when the gRPC status code in the response headers is unavailable.

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:

RuleDescriptionType
AddDefines 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
SetDefines 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
RemoveDefines 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:

RuleDescriptionType
AddDefines 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
SetDefines 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
RemoveDefines a list of headers to remove. Consul removes only headers containing exact matches. Header names are not case-sensitive.list of strings

Use variable placeholders

For Add and Set, if the service is configured to use Envoy as the proxy, the value may contain variables to interpolate dynamic metadata into the value. For example, using the variable %DOWNSTREAM_REMOTE_ADDRESS% in your configuration entry allows you to pass a value that is generated when the routing occurs.

Examples

The following examples demonstrate common service router configuration patterns for specific use cases.

Path prefix matching

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

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

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

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

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"]
    }
  }
]
Edit this page on GitHub