Thrift Proxy Route Configuration

Thrift Proxy Route 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:

config/filter/network/thrift_proxy/v2alpha1/route.proto

extensions.filters.network.thrift_proxy.v3.RouteConfiguration

[extensions.filters.network.thrift_proxy.v3.RouteConfiguration proto]

{
  "name": "...",
  "routes": []
}

name

(string) The name of the route configuration. Reserved for future use in asynchronous route discovery.

routes

(repeated extensions.filters.network.thrift_proxy.v3.Route) The list of routes that will be matched, in order, against incoming requests. The first route that matches will be used.

extensions.filters.network.thrift_proxy.v3.Route

[extensions.filters.network.thrift_proxy.v3.Route proto]

{
  "match": "{...}",
  "route": "{...}"
}

match

(extensions.filters.network.thrift_proxy.v3.RouteMatch, REQUIRED) Route matching parameters.

route

(extensions.filters.network.thrift_proxy.v3.RouteAction, REQUIRED) Route request to some upstream cluster.

extensions.filters.network.thrift_proxy.v3.RouteMatch

[extensions.filters.network.thrift_proxy.v3.RouteMatch proto]

{
  "method_name": "...",
  "service_name": "...",
  "invert": "...",
  "headers": []
}

method_name

(string) If specified, the route must exactly match the request method name. As a special case, an empty string matches any request method name.

Precisely one of method_name, service_name must be set.

service_name

(string) If specified, the route must have the service name as the request method name prefix. As a special case, an empty string matches any service name. Only relevant when service multiplexing.

Precisely one of method_name, service_name must be set.

invert

(bool) Inverts whatever matching is done in the method_name or service_name fields. Cannot be combined with wildcard matching as that would result in routes never being matched.

Note

This does not invert matching done as part of the headers field field. To invert header matching, see invert_match.

headers

(repeated config.route.v3.HeaderMatcher) Specifies a set of headers that the route should match on. The router will check the request’s headers against all the specified headers in the route config. A match will happen if all the headers in the route are present in the request with the same values (or based on presence if the value field is not in the config). Note that this only applies for Thrift transports and/or protocols that support headers.

extensions.filters.network.thrift_proxy.v3.RouteAction

[extensions.filters.network.thrift_proxy.v3.RouteAction proto]

{
  "cluster": "...",
  "weighted_clusters": "{...}",
  "cluster_header": "...",
  "metadata_match": "{...}",
  "rate_limits": [],
  "strip_service_name": "...",
  "request_mirror_policies": []
}

cluster

(string) Indicates a single upstream cluster to which the request should be routed to.

Precisely one of cluster, weighted_clusters, cluster_header must be set.

weighted_clusters

(extensions.filters.network.thrift_proxy.v3.WeightedCluster) Multiple upstream clusters can be specified for a given route. The request is routed to one of the upstream clusters based on weights assigned to each cluster.

Precisely one of cluster, weighted_clusters, cluster_header must be set.

cluster_header

(string) Envoy will determine the cluster to route to by reading the value of the Thrift header named by cluster_header from the request headers. If the header is not found or the referenced cluster does not exist Envoy will respond with an unknown method exception or an internal error exception, respectively.

Precisely one of cluster, weighted_clusters, cluster_header must be set.

metadata_match

(config.core.v3.Metadata) Optional endpoint metadata match criteria used by the subset load balancer. Only endpoints in the upstream cluster with metadata matching what is set in this field will be considered. Note that this will be merged with what’s provided in WeightedCluster.metadata_match, with values there taking precedence. Keys and values should be provided under the “envoy.lb” metadata key.

rate_limits

(repeated config.route.v3.RateLimit) Specifies a set of rate limit configurations that could be applied to the route. N.B. Thrift service or method name matching can be achieved by specifying a RequestHeaders action with the header name “:method-name”.

strip_service_name

(bool) Strip the service prefix from the method name, if there’s a prefix. For example, the method call Service:method would end up being just method.

request_mirror_policies

(repeated extensions.filters.network.thrift_proxy.v3.RouteAction.RequestMirrorPolicy) Indicates that the route has request mirroring policies.

extensions.filters.network.thrift_proxy.v3.RouteAction.RequestMirrorPolicy

[extensions.filters.network.thrift_proxy.v3.RouteAction.RequestMirrorPolicy proto]

The router is capable of shadowing traffic from one cluster to another. The current implementation is “fire and forget,” meaning Envoy will not wait for the shadow cluster to respond before returning the response from the primary cluster. All normal statistics are collected for the shadow cluster making this feature useful for testing.

Note

Shadowing will not be triggered if the primary cluster does not exist.

{
  "cluster": "...",
  "runtime_fraction": "{...}"
}

cluster

(string, REQUIRED) Specifies the cluster that requests will be mirrored to. The cluster must exist in the cluster manager configuration when the route configuration is loaded. If it disappears at runtime, the shadow request will silently be ignored.

runtime_fraction

(config.core.v3.RuntimeFractionalPercent) If not specified, all requests to the target cluster will be mirrored.

For some fraction N/D, a random number in the range [0,D) is selected. If the number is <= the value of the numerator N, or if the key is not present, the default value, the request will be mirrored.

extensions.filters.network.thrift_proxy.v3.WeightedCluster

[extensions.filters.network.thrift_proxy.v3.WeightedCluster proto]

Allows for specification of multiple upstream clusters along with weights that indicate the percentage of traffic to be forwarded to each cluster. The router selects an upstream cluster based on these weights.

{
  "clusters": []
}

clusters

(repeated extensions.filters.network.thrift_proxy.v3.WeightedCluster.ClusterWeight, REQUIRED) Specifies one or more upstream clusters associated with the route.

extensions.filters.network.thrift_proxy.v3.WeightedCluster.ClusterWeight

[extensions.filters.network.thrift_proxy.v3.WeightedCluster.ClusterWeight proto]

{
  "name": "...",
  "weight": "{...}",
  "metadata_match": "{...}"
}

name

(string, REQUIRED) Name of the upstream cluster.

weight

(UInt32Value) When a request matches the route, the choice of an upstream cluster is determined by its weight. The sum of weights across all entries in the clusters array determines the total weight.

metadata_match

(config.core.v3.Metadata) Optional endpoint metadata match criteria used by the subset load balancer. Only endpoints in the upstream cluster with metadata matching what is set in this field, combined with what’s provided in RouteAction’s metadata_match, will be considered. Values here will take precedence. Keys and values should be provided under the “envoy.lb” metadata key.