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:

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

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:

  1. Inspect traffic in both directions

  2. Modify the network traffic

  3. 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": {...},
  "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.

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.