HTTP scoped routing configuration¶

This documentation is for the Envoy v3 API.

As of Envoy v1.18 the v2 API has been removed and is no longer supported.

If you are upgrading from v2 API config you may wish to view the v2 API documentation:

api/v2/scoped_route.proto

Routing architecture overview

config.route.v3.ScopedRouteConfiguration¶

[config.route.v3.ScopedRouteConfiguration proto]

Specifies a routing scope, which associates a Key to a config.route.v3.RouteConfiguration. The config.route.v3.RouteConfiguration can be obtained dynamically via RDS (route_configuration_name) or specified inline (route_configuration).

The HTTP connection manager builds up a table consisting of these Key to RouteConfiguration mappings, and looks up the RouteConfiguration to use per request according to the algorithm specified in the scope_key_builder assigned to the HttpConnectionManager.

For example, with the following configurations (in YAML):

HttpConnectionManager config:

...
scoped_routes:
  name: foo-scoped-routes
  scope_key_builder:
    fragments:
      - header_value_extractor:
          name: X-Route-Selector
          element_separator: ,
          element:
            separator: =
            key: vip

ScopedRouteConfiguration resources (specified statically via scoped_route_configurations_list or obtained dynamically via SRDS):

(1)
 name: route-scope1
 route_configuration_name: route-config1
 key:
    fragments:
      - string_key: 172.10.10.20

(2)
 name: route-scope2
 route_configuration_name: route-config2
 key:
   fragments:
     - string_key: 172.20.20.30

A request from a client such as:

GET / HTTP/1.1
Host: foo.com
X-Route-Selector: vip=172.10.10.20

would result in the routing table defined by the route-config1 RouteConfiguration being assigned to the HTTP request/stream.

{
  "on_demand": "...",
  "name": "...",
  "route_configuration_name": "...",
  "route_configuration": "{...}",
  "key": "{...}"
}

on_demand: (bool) Whether the RouteConfiguration should be loaded on demand.

name: (string, REQUIRED) The name assigned to the routing scope.

route_configuration_name: (string) The resource name to use for a service.discovery.v3.DiscoveryRequest to an RDS server to fetch the config.route.v3.RouteConfiguration associated with this scope.

route_configuration: (config.route.v3.RouteConfiguration) The config.route.v3.RouteConfiguration associated with the scope.

key: (config.route.v3.ScopedRouteConfiguration.Key, REQUIRED) The key to match against.

config.route.v3.ScopedRouteConfiguration.Key¶

[config.route.v3.ScopedRouteConfiguration.Key proto]

Specifies a key which is matched against the output of the scope_key_builder specified in the HttpConnectionManager. The matching is done per HTTP request and is dependent on the order of the fragments contained in the Key.

{
  "fragments": []
}

fragments: (repeated config.route.v3.ScopedRouteConfiguration.Key.Fragment, REQUIRED) The ordered set of fragments to match against. The order must match the fragments in the corresponding scope_key_builder.

config.route.v3.ScopedRouteConfiguration.Key.Fragment¶

[config.route.v3.ScopedRouteConfiguration.Key.Fragment proto]

{
  "string_key": "..."
}

string_key: (string, REQUIRED) A string to match against.