External Processing Filter (proto)

This extension has the qualified name envoy.filters.network.ext_proc

Note

This extension is work-in-progress. Functionality is incomplete and it is not intended for production use.

This extension has an unknown security posture 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.filters.network

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

type.googleapis.com/envoy.extensions.filters.network.ext_proc.v3.NetworkExternalProcessor

Warning

This API feature is currently work-in-progress. API features marked as work-in-progress are not considered stable, are not covered by the threat model, are not supported by the security team, and are subject to breaking changes. Do not use this feature without understanding each of the previous points.

External Processing Filter: Process network traffic using an external service.

extensions.filters.network.ext_proc.v3.NetworkExternalProcessor

[extensions.filters.network.ext_proc.v3.NetworkExternalProcessor proto]

The Network External Processing filter allows an external service to process raw TCP/UDP traffic in a flexible way using a bidirectional gRPC stream. Unlike the HTTP External Processing filter, this filter operates at the L4 (transport) layer, giving access to raw network traffic.

The filter communicates with an external gRPC service that can:

Inspect traffic in both directions
Modify the network traffic
Control connection lifecycle (continue, close, or reset)

By using the filter’s processing mode, you can selectively choose which data directions to process (read, write or both), allowing for efficient processing.

{
  "grpc_service": {...},
  "failure_mode_allow": ...,
  "processing_mode": {...},
  "message_timeout": {...},
  "stat_prefix": ...,
  "metadata_options": {...}
}

grpc_service: (config.core.v3.GrpcService) The gRPC service that will process network traffic. This service must implement the NetworkExternalProcessor service defined in the proto file /envoy/service/network_ext_proc/v3/external_processor.proto.

failure_mode_allow: (bool) By default, if the gRPC stream cannot be established, or if it is closed prematurely with an error, the filter will fail, leading to the close of connection. With this parameter set to true, however, then if the gRPC stream is prematurely closed or could not be opened, processing continues without error.

processing_mode: (extensions.filters.network.ext_proc.v3.ProcessingMode) Options for controlling processing behavior.

message_timeout: (Duration) Specifies the timeout for each individual message sent on the stream and when the filter is running in synchronous mode. Whenever the proxy sends a message on the stream that requires a response, it will reset this timer, and will stop processing and return an error (subject to the processing mode) if the timer expires. Default is 200 ms.

stat_prefix: (string, REQUIRED)

metadata_options: (extensions.filters.network.ext_proc.v3.MetadataOptions) Options related to the sending and receiving of dynamic metadata.

extensions.filters.network.ext_proc.v3.ProcessingMode

[extensions.filters.network.ext_proc.v3.ProcessingMode proto]

Options for controlling processing behavior. Filter will reject the config if both read and write are SKIP mode.

{
  "process_read": ...,
  "process_write": ...
}

process_read: (extensions.filters.network.ext_proc.v3.ProcessingMode.DataSendMode) Controls whether inbound (read) data from the client is sent to the external processor. Default: STREAMED

process_write: (extensions.filters.network.ext_proc.v3.ProcessingMode.DataSendMode) Controls whether outbound (write) data to the client is sent to the external processor. Default: STREAMED

Enum extensions.filters.network.ext_proc.v3.ProcessingMode.DataSendMode

[extensions.filters.network.ext_proc.v3.ProcessingMode.DataSendMode proto]

Defines how traffic should be handled by the external processor.

STREAMED: (DEFAULT) ⁣Send the data to the external processor for processing whenever the data is ready.

SKIP: ⁣Skip sending the data to the external processor.

extensions.filters.network.ext_proc.v3.MetadataOptions

[extensions.filters.network.ext_proc.v3.MetadataOptions proto]

The MetadataOptions structure defines options for sending dynamic metadata. Specifically, which namespaces to send to the server.

{
  "forwarding_namespaces": {...}
}

forwarding_namespaces: (extensions.filters.network.ext_proc.v3.MetadataOptions.MetadataNamespaces) Describes which typed or untyped dynamic metadata namespaces to forward to the external processing server.

extensions.filters.network.ext_proc.v3.MetadataOptions.MetadataNamespaces

[extensions.filters.network.ext_proc.v3.MetadataOptions.MetadataNamespaces proto]

{
  "untyped": [],
  "typed": []
}

untyped: (repeated string) Specifies a list of metadata namespaces whose values, if present, will be passed to the ext_proc service as an opaque protobuf::Struct.

typed: (repeated string) Specifies a list of metadata namespaces whose values, if present, will be passed to the ext_proc service as a protobuf::Any. This allows envoy and the external processing server to share the protobuf message definition for safe parsing.