Service Router

    If a router is not explicitly configured or is configured with no routes then the system behaves as if a router were configured sending all traffic to a service of the same name.

    • Consul service mesh connect enabled services
    • Service to service communication over the protocol http
    • Consul 1.8.4+ on Kubernetes.
    • Consul 1.5.0+ on other platforms.

    v1.8.4+: On Kubernetes, the ServiceRouter custom resource is supported in Consul versions 1.8.4+.
    v1.6.0+: On other platforms, this config entry is supported in Consul versions 1.6.0+.

    Interaction with other Config Entries

    • Service router config entries are a component of L7 Traffic Management.

    • Service router config entries are restricted to only services that define their protocol as HTTP-based via a corresponding config entry or globally via proxy-defaults .

    • Any route destination that omits the ServiceSubset field is eligible for splitting via a should one be configured for that service, otherwise resolution proceeds according to any configured service-resolver.

    Once a service-router is successfully entered, you can view it in the UI. Service routers, service splitters, and service resolvers can all be viewed by clicking on your service then switching to the routing tab.

    Sample Config Entries

    Route HTTP requests with a path starting with /admin to a different service:

    HCL

    Service Router - 图2

    • HCL
    • Kubernetes YAML
    • JSON
    1. Kind = "service-router"
    2. Name = "web"
    3. Routes = [
    4.   {
    5.     Match {
    6.       HTTP {
    7.         PathPrefix = "/admin"
    8.       }
    9.     }
    11.     Destination {
    12.       Service = "admin"
    13.     }
    14.   },
    15.   # NOTE: a default catch-all will send unmatched traffic to "web"
    16. ]
    1. apiVersion: consul.hashicorp.com/v1alpha1
    2. kind: ServiceRouter
    3. metadata:
    4.   name: web
    5. spec:
    6.   routes:
    7.     - match:
    8.         http:
    9.           pathPrefix: /admin
    10.       destination:
    11.         service: admin
    12.   # NOTE: a default catch-all will send unmatched traffic to "web"
    1. apiVersion: consul.hashicorp.com/v1alpha1
    2. kind: ServiceRouter
    3. metadata:
    4.   name: web
    5. spec:
    6.   routes:
    7.     - match:
    8.         http:
    9.           pathPrefix: /admin
    10.       destination:
    11.         service: admin
    12.   # NOTE: a default catch-all will send unmatched traffic to "web"
    1. {
    2.   "Kind": "service-router",
    3.   "Name": "web",
    4.   "Routes": [
    5.     {
    6.       "Match": {
    7.         "HTTP": {
    8.           "PathPrefix": "/admin"
    9.         }
    10.       },
    11.       "Destination": {
    12.         "Service": "admin"
    13.       }
    14.     }
    15.   ]
    16. }
    1. {
    2.   "Kind": "service-router",
    3.   "Name": "web",
    4.   "Routes": [
    5.     {
    6.       "Match": {
    7.         "HTTP": {
    8.           "PathPrefix": "/admin"
    9.         }
    10.       },
    11.       "Destination": {
    12.         "Service": "admin"
    13.       }
    14.     }
    15.   ]
    16. }

    Header/query parameter matching

    Route HTTP requests with a special URL parameter or header to a canary subset:

    HCL

    • HCL
    • Kubernetes YAML
    • JSON
    1. Kind = "service-router"
    2. Name = "web"
    3. Routes = [
    4.   {
    5.     Match {
    6.       HTTP {
    7.         Header = [
    8.           {
    9.             Name  = "x-debug"
    10.             Exact = "1"
    11.           },
    12.         ]
    13.       }
    14.     }
    15.     Destination {
    16.       Service       = "web"
    17.       ServiceSubset = "canary"
    18.     }
    19.   },
    20.   {
    21.     Match {
    22.       HTTP {
    23.         QueryParam = [
    24.           {
    25.             Name  = "x-debug"
    26.             Exact = "1"
    27.           },
    28.         ]
    29.       }
    30.     }
    31.     Destination {
    32.       Service       = "web"
    33.       ServiceSubset = "canary"
    34.     }
    35.   },
    36.   # NOTE: a default catch-all will send unmatched traffic to "web"
    37. ]
    1. Kind = "service-router"
    2. Name = "web"
    3. Routes = [
    4.   {
    5.     Match {
    6.       HTTP {
    7.         Header = [
    8.           {
    9.             Name  = "x-debug"
    10.             Exact = "1"
    11.           },
    12.         ]
    13.       }
    14.     }
    15.     Destination {
    16.       Service       = "web"
    17.       ServiceSubset = "canary"
    18.     }
    19.   },
    20.   {
    21.     Match {
    22.       HTTP {
    23.         QueryParam = [
    24.           {
    25.             Name  = "x-debug"
    26.             Exact = "1"
    27.           },
    28.         ]
    29.       }
    30.     }
    31.     Destination {
    32.       Service       = "web"
    33.       ServiceSubset = "canary"
    34.     }
    35.   },
    36.   # NOTE: a default catch-all will send unmatched traffic to "web"
    37. ]
    1. apiVersion: consul.hashicorp.com/v1alpha1
    2. kind: ServiceRouter
    3. metadata:
    4.   name: web
    5. spec:
    6.   routes:
    7.     - match:
    8.         http:
    9.           header:
    10.             - name: x-debug
    11.               exact: '1'
    12.       destination:
    13.         service: web
    14.         serviceSubset: canary
    15.         http:
    16.           queryParam:
    17.             - name: x-debug
    18.               exact: '1'
    19.       destination:
    20.         service: web
    21.         serviceSubset: canary
    22.   # NOTE: a default catch-all will send unmatched traffic to "web"
    1. {
    2.   "Kind": "service-router",
    3.   "Name": "web",
    4.   "Routes": [
    5.     {
    6.       "Match": {
    7.         "HTTP": {
    8.           "Header": [
    9.             {
    10.               "Name": "x-debug",
    11.               "Exact": "1"
    12.             }
    13.           ]
    14.         }
    15.       },
    16.       "Destination": {
    17.         "Service": "web",
    18.         "ServiceSubset": "canary"
    19.       }
    20.     },
    22.       "Match": {
    23.         "HTTP": {
    24.           "QueryParam": [
    25.             {
    26.               "Name": "x-debug",
    27.               "Exact": "1"
    28.             }
    29.           ]
    30.         }
    31.       },
    32.       "Destination": {
    33.         "Service": "web",
    34.         "ServiceSubset": "canary"
    35.       }
    36.     }
    37.   ]
    38. }
    1. {
    2.   "Kind": "service-router",
    3.   "Name": "web",
    4.   "Routes": [
    5.     {
    6.       "Match": {
    7.         "HTTP": {
    8.           "Header": [
    9.             {
    10.               "Name": "x-debug",
    11.               "Exact": "1"
    12.             }
    13.           ]
    14.         }
    15.       },
    16.       "Destination": {
    17.         "Service": "web",
    18.         "ServiceSubset": "canary"
    19.       }
    20.     },
    21.     {
    22.       "Match": {
    23.         "HTTP": {
    24.           "QueryParam": [
    25.             {
    26.               "Name": "x-debug",
    27.               "Exact": "1"
    28.             }
    29.           ]
    30.         }
    31.       },
    32.       "Destination": {
    33.         "Service": "web",
    34.         "ServiceSubset": "canary"
    35.       }
    36.     }
    37.   ]
    38. }

    Re-route a gRPC method to another service. Since gRPC method calls , we can use an HTTP path match rule to re-route traffic:

    HCL

    Service Router - 图4

    • HCL
    • Kubernetes YAML
    • JSON
    1. Kind = "service-router"
    2. Name = "billing"
    3. Routes = [
    4.   {
    5.     Match {
    6.       HTTP {
    7.         PathExact = "/mycompany.BillingService/GenerateInvoice"
    8.       }
    9.     }
    11.     Destination {
    12.       Service = "invoice-generator"
    13.     }
    14.   },
    15.   # NOTE: a default catch-all will send unmatched traffic to "billing"
    16. ]
    1. Kind = "service-router"
    2. Name = "billing"
    3. Routes = [
    4.   {
    5.     Match {
    6.       HTTP {
    7.         PathExact = "/mycompany.BillingService/GenerateInvoice"
    8.       }
    9.     }
    11.     Destination {
    12.       Service = "invoice-generator"
    13.     }
    14.   },
    15.   # NOTE: a default catch-all will send unmatched traffic to "billing"
    16. ]
    1. apiVersion: consul.hashicorp.com/v1alpha1
    2. kind: ServiceRouter
    3. metadata:
    4.   name: billing
    5. spec:
    6.   routes:
    7.     - match:
    8.         http:
    9.           pathExact: /mycompany.BillingService/GenerateInvoice
    10.       destination:
    11.         service: invoice-generator
    12.   # NOTE: a default catch-all will send unmatched traffic to "billing"
    1. apiVersion: consul.hashicorp.com/v1alpha1
    2. kind: ServiceRouter
    3. metadata:
    4.   name: billing
    5. spec:
    6.   routes:
    7.     - match:
    8.         http:
    9.           pathExact: /mycompany.BillingService/GenerateInvoice
    10.       destination:
    11.         service: invoice-generator
    12.   # NOTE: a default catch-all will send unmatched traffic to "billing"
    1. {
    2.   "Kind": "service-router",
    3.   "Name": "billing",
    4.   "Routes": [
    5.     {
    6.       "Match": {
    7.         "HTTP": {
    8.           "PathExact": "/mycompany.BillingService/GenerateInvoice"
    9.         }
    10.       },
    11.       "Destination": {
    12.         "Service": "invoice-generator"
    13.       }
    14.     }
    15.   ]
    16. }

    Retry logic

    Enable retry logic by delegating this responsibility to Consul and the proxy. Review the block for more details.

    HCL

    • HCL
    • Kubernetes YAML
    • JSON
    1. Kind = "service-router"
    2. Name = "orders"
    3. Routes = [
    4.   {
    5.     Match{
    6.         HTTP {
    7.             PathPrefix = "/coffees"
    8.         }  
    9.     }
    11.     Destination {
    12.         Service = "products"
    13.         RequestTimeout = "10s"
    14.         NumRetries = 3
    15.         RetryOnConnectFailure = true
    16.     }
    17.   },
    18.   {
    19.     Match{
    20.         HTTP {
    21.             PathPrefix = "/orders"
    22.         }  
    23.     }
    25.     Destination {
    26.         RequestTimeout = "10s"
    27.         NumRetries = 3
    28.         RetryOnConnectFailure = true
    29.     }
    30.   }
    31. ]
    1. Kind = "service-router"
    2. Name = "orders"
    3. Routes = [
    4.   {
    5.     Match{
    6.         HTTP {
    7.             PathPrefix = "/coffees"
    8.         }  
    9.     }
    11.     Destination {
    12.         Service = "products"
    13.         RequestTimeout = "10s"
    14.         NumRetries = 3
    15.         RetryOnConnectFailure = true
    16.     }
    17.   },
    18.   {
    19.     Match{
    20.         HTTP {
    21.             PathPrefix = "/orders"
    22.         }  
    23.     }
    25.     Destination {
    26.         Service = "procurement"
    27.         RequestTimeout = "10s"
    28.         NumRetries = 3
    29.         RetryOnConnectFailure = true
    30.     }
    31.   }
    32. ]
    1. apiVersion: consul.hashicorp.com/v1alpha1
    2. kind: ServiceRouter
    3. metadata:
    4.   name: orders
    5. spec:
    6.   routes:
    7.     - match:
    9.           pathExact: /coffees
    10.       destination:
    11.         service: products
    12.         requestTimeout: 10s
    13.         numRetries: 3
    14.         retryOnConnectFailure: true
    15.     - match:
    16.         http:
    17.           pathExact: /orders
    18.       destination:
    19.         service: procurement
    20.         requestTimeout: 10s
    21.         numRetries: 3
    22.         retryOnConnectFailure: true
    1. apiVersion: consul.hashicorp.com/v1alpha1
    2. kind: ServiceRouter
    3. metadata:
    4.   name: orders
    5. spec:
    6.   routes:
    7.     - match:
    8.         http:
    9.           pathExact: /coffees
    10.       destination:
    11.         service: products
    12.         requestTimeout: 10s
    13.         numRetries: 3
    14.         retryOnConnectFailure: true
    15.     - match:
    16.         http:
    17.           pathExact: /orders
    18.       destination:
    19.         service: procurement
    20.         requestTimeout: 10s
    21.         numRetries: 3
    22.         retryOnConnectFailure: true
    1. {
    2.     "Kind": "service-router",
    3.     "Name": "orders",
    4.     "Routes": [
    5.         {
    6.             "Match": {
    7.                 "HTTP": {
    8.                     "PathPrefix": "/coffees"
    9.                 }
    10.             },
    11.             "Destination": {
    12.                 "NumRetries": 3,
    13.                 "RequestTimeout": "10s",
    14.                 "RetryOnConnectFailure": true,
    15.                 "Service": "procurement"
    16.             }
    17.         },
    18.         {
    19.             "Match": {
    20.                 "HTTP": {
    21.                     "PathPrefix": "/orders"
    22.                 }
    23.             },
    24.             "Destination": {
    25.                 "NumRetries": 3,
    26.                 "RequestTimeout": "10s",
    27.                 "RetryOnConnectFailure": true,
    28.                 "Service": "procurement"
    29.             }
    30.         }
    31.     ]
    32. }
    1. {
    2.     "Kind": "service-router",
    3.     "Name": "orders",
    4.     "Routes": [
    5.         {
    6.             "Match": {
    7.                 "HTTP": {
    8.                     "PathPrefix": "/coffees"
    9.                 }
    10.             },
    11.             "Destination": {
    12.                 "NumRetries": 3,
    13.                 "RequestTimeout": "10s",
    14.                 "RetryOnConnectFailure": true,
    15.                 "Service": "procurement"
    16.             }
    17.         },
    18.         {
    19.             "Match": {
    20.                 "HTTP": {
    21.                     "PathPrefix": "/orders"
    22.                 }
    23.             },
    24.             "Destination": {
    25.                 "NumRetries": 3,
    26.                 "RequestTimeout": "10s",
    27.                 "RetryOnConnectFailure": true,
    28.                 "Service": "procurement"
    29.             }
    30.         }
    31.     ]
    32. }

    Service Router - 图6

    • Kind - Must be set to service-router

    • (string: <required>) - Set to the name of the service being configured.

    • Namespace (string: "default")

      Enterprise

      - Specifies the namespace to which the configuration entry will apply.

    • (string: "default")

      Enterprise

      - Specifies the admin partition to which the configuration will apply.

    • Meta (map<string|string>: nil) - Specifies arbitrary KV metadata pairs. Added in Consul 1.8.4.

      • (ServiceRouteMatch: <optional>) - A set of criteria that can match incoming L7 requests. If empty or omitted it acts as a catch-all.

        • HTTP (ServiceRouteHTTPMatch: <optional>) - A set of .

      • Destination (ServiceRouteDestination: <optional>) - Controls the matching request(s) to a service.

    Service Router - 图8

    • PathExact (string: "") - Exact path to match on the HTTP request path.

      At most only one of PathExact, PathPrefix, or PathRegex may be configured.

    • (string: "") - Path prefix to match on the HTTP request path.

      At most only one of PathExact, PathPrefix, or PathRegex may be configured.

    • PathRegex (string: "") - Regular expression to match on the HTTP request path.

      The syntax is .

      At most only one of PathExact, PathPrefix, or PathRegex may be configured.

    • Methods (array<string>) - A list of HTTP methods for which this match applies. If unspecified all HTTP methods are matched. If provided the names must be a valid .

    • Header (array<ServiceRouteHTTPMatchHeader>)) - A set of criteria that can match on HTTP request headers. If more than one is configured all must match for the overall match to apply.

      • (string: <required>) - Name of the header to match.

      • Present (bool: false) - Match if the header with the given name is present with any value.

        At most only one of Exact, Prefix, Suffix, Regex, or Present may be configured.

      • (string: "") - Match if the header with the given name is this value.

        At most only one of Exact, Prefix, Suffix, Regex, or Present may be configured.

      • Prefix (string: "") - Match if the header with the given name has this prefix.

        At most only one of Exact, Prefix, Suffix, Regex, or Present may be configured.

      • (string: "") - Match if the header with the given name has this suffix.

        At most only one of Exact, Prefix, Suffix, Regex, or Present may be configured.

      • Regex (string: "") - Match if the header with the given name matches this pattern.

        The syntax is .

        At most only one of Exact, Prefix, Suffix, Regex, or Present may be configured.

      • Invert (bool: false) - Inverts the logic of the match

    • (array<ServiceRouteHTTPMatchQueryParam>)) - A set of criteria that can match on HTTP query parameters. If more than one is configured all must match for the overall match to apply.

      • Name (string: <required>) - The name of the query parameter to match on.

      • (bool: false) - Match if the query parameter with the given name is present with any value.

        At most only one of Exact, Regex, or Present may be configured.

      • At most only one of Exact, Regex, or Present may be configured.

      • Regex (string: "") - Match if the query parameter with the given name matches this pattern.

        The syntax is .

        At most only one of Exact, Regex, or Present may be configured.

    ServiceRouteDestination

    Service Router - 图10

    • (string: "") - The service to resolve instead of the default service. If empty then the default service name is used.

    • ServiceSubset (string: "") - A named subset of the given service to resolve instead of the one defined as that service’s DefaultSubset. If empty, the default subset is used.

    • (string: "")

      Enterprise

      - The Consul namespace to resolve the service from instead of the current namespace. If empty, the current namespace is used.

    • Partition (string: "")

      Enterprise

      - The Consul admin partition to resolve the service from instead of the current partition. If empty, the current partition is used.

    • (string: "") - Defines how to rewrite the HTTP request path before proxying it to its final destination.

      This requires that either Match.HTTP.PathPrefix or Match.HTTP.PathExact be configured on this route.

    • RequestTimeout (duration: 0) - The total amount of time permitted for the entire downstream request (and retries) to be processed.

    • (int: 0) - The number of times to retry the request when a retryable result occurs.

    • RetryOnConnectFailure (bool: false) - Allows for connection failure errors to trigger a retry.

    • (array<int>) - A list of HTTP response status codes that are eligible for retry.

    • RequestHeaders (HTTPHeaderModifiers: <optional>) - A set of that will be applied to requests routed to this service. This cannot be used with a tcp listener.

    • ResponseHeaders (HTTPHeaderModifiers: <optional>) - A set of that will be applied to responses from this service. This cannot be used with a tcp listener.

    Service Router - 图12

    • Add (map<string|string>: optional) - The set of key/value pairs that specify header values to add. Use header names as keys. Header names are _not_ case-sensitive. If header values with the same name already exist, the value set here will be appended and both will be present. If Envoy is used as the proxy, the value may contain for example %DOWNSTREAM_REMOTE_ADDRESS% to interpolate dynamic request metadata into the value added.

    • Set (map<string|string>: optional) - The set of key/value pairs that specify header values to add. Use header names as keys. Header names are _not_ case-sensitive. If header values with the same name already exist, the value set here will _replace_ them. If Envoy is used as the proxy, the value may contain for example %DOWNSTREAM_REMOTE_ADDRESS% to interpolate dynamic request metadata into the value added.

    • Remove (array<string>: optional) - The set of header names to remove. Only headers whose names are a case-insensitive exact match will be removed

    ACLs

    Configuration entries may be protected by ACLs.

    Reading a service-router config entry requires service:read on the resource.

    Creating, updating, or deleting a service-router config entry requires service:write on the resource and service:read on any other service referenced by name in these fields:

    When using Envoy as a proxy (the only supported proxy in Kubernetes), the syntax for these fields is version specific: