Dynamic Modules Network Filter (proto)

This extension has the qualified name envoy.filters.network.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:

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

extensions.filters.network.dynamic_modules.v3.DynamicModuleNetworkFilter

[extensions.filters.network.dynamic_modules.v3.DynamicModuleNetworkFilter proto]

Configuration for the Dynamic Modules network filter. This filter allows loading shared object files that can be loaded via dlopen to extend the network filter chain.

A module can be loaded by multiple network filters; the module is loaded only once and shared across multiple filters.

Unlike HTTP filters which operate on structured headers, body, and trailers, network filters work with raw TCP byte streams. The filter can:

  • Inspect, modify, or inject data into the downstream connection.

  • Access connection-level information such as addresses and TLS status.

  • Control connection lifecycle (e.g., close the connection).

{
  "dynamic_module_config": {...},
  "filter_name": ...,
  "filter_config": {...},
  "terminal_filter": ...
}
dynamic_module_config

(extensions.dynamic_modules.v3.DynamicModuleConfig) Specifies the shared-object level configuration.

filter_name

(string) The name for this filter configuration.

This can be used to distinguish between different filter implementations inside a dynamic module. For example, a module can have completely different filter implementations. When Envoy receives this configuration, it passes the filter_name to the dynamic module’s network filter config init function together with the filter_config. That way a module can decide which in-module filter implementation to use based on the name at load time.

filter_config

(Any) The configuration for the filter chosen by filter_name.

This is passed to the module’s network filter initialization function. Together with the filter_name, the module can decide which in-module filter implementation to use and fine-tune the behavior of the filter.

For example, if a module has two filter implementations, one for echo and one for rate limiting, filter_name is used to choose either echo or rate limiting. The filter_config can be used to configure the echo behavior or the rate limiting parameters.

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 string value
filter_config:
  "@type": "type.googleapis.com/google.protobuf.StringValue"
  value: hello

# Passing raw bytes
filter_config:
  "@type": "type.googleapis.com/google.protobuf.BytesValue"
  value: aGVsbG8=  # echo -n "hello" | base64
terminal_filter

(bool) If true, the dynamic module is a terminal filter to use without an upstream connection.

The dynamic module is responsible for creating and sending the response to downstream.

Defaults to false.