Dynamic Modules Cluster Specifier (proto)

This extension has the qualified name envoy.router.cluster_specifier_plugin.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.cluster_specifier_plugin

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

type.googleapis.com/envoy.extensions.router.cluster_specifiers.dynamic_modules.v3.DynamicModuleClusterSpecifier

Dynamic modules cluster specifier configuration reference documentation.

extensions.router.cluster_specifiers.dynamic_modules.v3.RouteActionOverride

[extensions.router.cluster_specifiers.dynamic_modules.v3.RouteActionOverride proto]

Route action properties that a dynamic module may select for a request in place of the properties of the matched route. These properties are themselves built from other extensions, such as retry host predicates and retry priorities, so they must be declared here in advance rather than chosen freely by the module on each request.

Each entry is built and validated when the cluster specifier is configured, so an invalid entry is rejected at configuration load rather than on the request path. Every entry must replace at least one property, so an entry that builds to no replacement is rejected as well.

{
  "retry_policy": {...},
  "metadata_match": {...},
  "request_mirror_policies": [],
  "hash_policy": []
}

retry_policy: (config.route.v3.RetryPolicy) Retry policy replacing the retry policy of the matched route. If not specified, the retry policy of the matched route is used, so an entry cannot be used to remove a retry policy that the matched route configures.

metadata_match: (config.core.v3.Metadata) Metadata match criteria replacing the criteria of the matched route, used by subset load balancing. Only the envoy.lb entry of filter_metadata is used, matching the behavior of RouteAction.metadata_match. If not specified, or if there is no envoy.lb entry, the criteria of the matched route are used, so an entry cannot be used to remove the criteria that the matched route configures. An entry whose only property is a metadata_match without an envoy.lb entry therefore replaces nothing and is rejected.

request_mirror_policies: (repeated config.route.v3.RouteAction.RequestMirrorPolicy) Request mirroring policies replacing the request mirroring policies of the matched route. If not specified, the request mirroring policies of the matched route are used, so an entry cannot be used to turn off mirroring that the matched route configures. 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 matched route, used when the upstream cluster employs a hashing load balancer. If not specified, the hash policy of the matched route is used, so an entry cannot be used to remove a hash policy that the matched route configures. A cluster-level hash policy and a load-balancer-level hash policy, when configured, take precedence over this route-level policy.

extensions.router.cluster_specifiers.dynamic_modules.v3.DynamicModuleClusterSpecifier

[extensions.router.cluster_specifiers.dynamic_modules.v3.DynamicModuleClusterSpecifier proto]

Configuration for the Dynamic Modules Cluster Specifier. This cluster specifier allows loading shared object files via dlopen to select the upstream cluster for a request, and to replace the timeout, idle timeout, priority, request body buffer limit, cluster not found response code, hash policy, retry policy, metadata match criteria and request mirroring policies of the matched route.

A module can be loaded by multiple cluster specifiers. It is loaded only once and shared across multiple cluster specifier instances. The module is invoked while the route is being resolved, so the selection is visible to the router without clearing the route cache. It is invoked again whenever a filter refreshes the route cluster, or a retry re-selects it when refresh_cluster_on_retry is set, so the module must be able to produce a decision from the request headers and the stream info alone.

{
  "dynamic_module_config": {...},
  "specifier_name": ...,
  "specifier_config": {...},
  "route_action_overrides": {...}
}

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 cluster specifier is configured, 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 cluster specifier configuration. If not specified, defaults to an empty string.

This can be used to distinguish between different cluster specifier implementations inside a dynamic module. When Envoy receives this configuration, it passes the specifier_name to the dynamic module’s cluster specifier config init function together with the specifier_config. That way a module can decide which in-module implementation to use based on the name at load time.

specifier_config

(Any) The configuration for the cluster specifier chosen by specifier_name. If not specified, an empty configuration is passed to the module.

google.protobuf.Struct is serialized as JSON before passing it to the module. google.protobuf.BytesValue and google.protobuf.StringValue are passed directly without the wrapper.

# Passing a JSON struct configuration
specifier_config:
  "@type": "type.googleapis.com/google.protobuf.Struct"
  value:
    cluster_name_prefix: shard-

# Passing a simple string configuration
specifier_config:
  "@type": "type.googleapis.com/google.protobuf.StringValue"
  value: "shard-"

route_action_overrides: (map<string, extensions.router.cluster_specifiers.dynamic_modules.v3.RouteActionOverride>) Route action overrides that the module may select by name for a request. If not specified, the module can only select the cluster, the timeout, the idle timeout, the priority, the request body buffer limit and the cluster not found response code.