Dynamic modules route specifier (proto)

This extension has the qualified name envoy.router.route_specifiers.dynamic_modules

Note

This extension is functional but has not had substantial production burn time, use only with this caveat.

This extension is not hardened and should only be used in deployments where both the downstream and upstream are trusted.

Tip

This extension extends and can be used with the following extension category:

envoy.router.route_specifiers

This extension must be configured with one of the following type URLs:

type.googleapis.com/envoy.extensions.router.route_specifiers.dynamic_modules.v3.DynamicModuleRouteSpecifier

A route specifier implemented by a dynamic module. For each request the module keeps the route that route matching resolved, refines it, replaces it with one of the route templates declared here, or drops it. Envoy builds every route from validated configuration, so a module can never produce a malformed route.

See the dynamic modules route specifier for more details.

extensions.router.route_specifiers.dynamic_modules.v3.RouteTemplate

[extensions.router.route_specifiers.dynamic_modules.v3.RouteTemplate proto]

A named route the module may select for a request.

A template is built and validated once, when the specifier is configured, so an invalid template is rejected at configuration load. It inherits from the virtual host and the route configuration the specifier is configured on, exactly like a configured route does. When the module selects a template, Envoy evaluates it against the request like a configured route: the match must hold, otherwise the failure_policy applies, and the action is resolved the usual way, including weighted_clusters and cluster specifier plugins.

{
  "template_id": ...,
  "route": {...}
}

template_id: (string, REQUIRED) The identifier the module selects this template with. Must be unique within the specifier.

route: (config.route.v3.Route, REQUIRED) The route. route_specifiers must be empty, since a template is not run through the specifier chains.

extensions.router.route_specifiers.dynamic_modules.v3.RouteOverride

[extensions.router.route_specifiers.dynamic_modules.v3.RouteOverride proto]

Route properties the module may select for a request.

These properties are built from other extensions, so they are declared here and built once at configuration load rather than constructed on the request path. An entry that replaces no property is rejected. A property an entry leaves unset keeps the value of the route the decision produced, so an entry can never remove a property that route configures.

{
  "override_id": ...,
  "retry_policy": {...},
  "metadata_match": {...},
  "request_mirror_policies": [],
  "hash_policy": [],
  "hedge_policy": {...},
  "rate_limits": [],
  "cors": {...}
}

override_id: (string, REQUIRED) The identifier the module selects this override with. Must be unique within the specifier.

retry_policy: (config.route.v3.RetryPolicy) Retry policy replacing the retry policy of the produced route.

metadata_match: (config.core.v3.Metadata) Metadata match criteria replacing those of the produced route, used by subset load balancing. Only the envoy.lb entry of filter_metadata is used, matching the behavior of RouteAction.metadata_match. An entry whose only property is a metadata_match without an envoy.lb entry replaces nothing and is rejected.

request_mirror_policies: (repeated config.route.v3.RouteAction.RequestMirrorPolicy) Request mirroring policies replacing those of the produced route. Statically named mirror clusters are checked against the cluster manager when validate_clusters is enabled.

hash_policy: (repeated config.route.v3.RouteAction.HashPolicy) Hash policy replacing the hash policy of the produced route, used when the upstream cluster employs a hashing load balancer. A cluster level and a load balancer level hash policy, when configured, take precedence over this route level policy.

hedge_policy: (config.route.v3.HedgePolicy) Hedge policy replacing the hedge policy of the produced route.

rate_limits: (repeated config.route.v3.RateLimit) Rate limits replacing the rate limits of the produced route.

cors: (config.route.v3.CorsPolicy) CORS policy replacing the CORS policy of the produced route. The CORS filter reads it only when CORS is not configured through per filter configuration.

extensions.router.route_specifiers.dynamic_modules.v3.DynamicModuleRouteSpecifier

[extensions.router.route_specifiers.dynamic_modules.v3.DynamicModuleRouteSpecifier proto]

Configuration for the dynamic modules route specifier.

{
  "dynamic_module_config": {...},
  "specifier_name": ...,
  "specifier_config": {...},
  "stat_prefix": ...,
  "route_templates": [],
  "route_overrides": [],
  "runtime_fraction": {...},
  "failure_policy": ...,
  "validate_clusters": {...}
}

dynamic_module_config: (extensions.dynamic_modules.v3.DynamicModuleConfig, REQUIRED) Specifies the shared object level configuration. This field is required.

Note

This extension loads the module while the route configuration is built, so it cannot wait for an asynchronous fetch. A remote module is therefore accepted only when the module is already cached on disk, and is otherwise rejected. Setting nack_on_cache_miss to true makes the rejection start a background fetch so that a later update succeeds. Prefer name or a local data source.

specifier_name: (string) The name for this route specifier configuration, used to select an implementation within the module. If not specified, defaults to an empty string.

specifier_config: (Any) The configuration for the route specifier chosen by specifier_name. If not specified, defaults to an empty configuration.

stat_prefix: (string, REQUIRED) Prefix for the statistics of this specifier, emitted as <metrics_namespace>.route_specifier.<stat_prefix>.*, where metrics_namespace is the metrics_namespace of the module. Specifiers that share a metrics namespace and prefix share counters, so keep the prefix unique within that namespace.

route_templates: (repeated extensions.router.route_specifiers.dynamic_modules.v3.RouteTemplate) The route templates the module may select by template_id, each replacing the resolved route with a route built from configuration. The template_id values must be unique.

route_overrides: (repeated extensions.router.route_specifiers.dynamic_modules.v3.RouteOverride) The route overrides the module may select by override_id, each overlaying its properties onto the produced route. The override_id values must be unique.

runtime_fraction: (config.core.v3.RuntimeFractionalPercent) Fraction of requests the module is invoked for. A request outside the fraction is passed through untouched and counted in runtime_skipped. The stable random value of the request is used, so the choice holds when the route of a request is recomputed. If not specified, defaults to every request.

Attention

A request outside the fraction is routed by routes or matcher alone, so a fraction below 100% is only safe, as a canary or as an emergency switch with the runtime key set to 0, while the route table the module replaces is still complete. Once that table has been shrunk, lowering the fraction turns the affected requests into 404s or routes them wrongly, and the way back is a route configuration rollback that restores the table.

failure_policy: (extensions.router.route_specifiers.dynamic_modules.v3.FailurePolicy) What Envoy does when the decision of the module cannot be honored. Must be set explicitly.

validate_clusters: (BoolValue) Whether the clusters the route templates and the route overrides name are checked against the cluster manager while the specifier is configured. If not specified, defaults to false, because the clusters a route names may be delivered after the route configuration that references them. An unknown cluster then fails the request with the cluster_not_found_response_code of the route instead.

Enum extensions.router.route_specifiers.dynamic_modules.v3.FailurePolicy

[extensions.router.route_specifiers.dynamic_modules.v3.FailurePolicy proto]

What Envoy does when the decision of the module cannot be honored.

This covers a module that reports an error, which is what the SDK does when the module panics, a decision that selects no template or an unknown one, a template whose match does not hold for the request, an override of a route that route matching did not resolve, route entry overrides recorded for a direct response, and route metadata a typed metadata factory rejects.

FAILURE_POLICY_UNSPECIFIED: (DEFAULT) ⁣Must be set explicitly.

PASS_THROUGH: ⁣Use the route the specifier was given, unchanged, and carry on with the chain. This keeps the routing of the route table the module replaces in effect while it is being rolled out. If the specifier was given no route, the request has no route.

NO_ROUTE: ⁣Use no route, so the request is handled as if nothing had matched, and end the chain. Prefer this once the module owns the routing of the virtual host, so that a failure never falls back to the routes that are left.