api: ext-proc metadata an attributes

What type of PR is this?

Following the discussion at KubeCon NA : https://docs.google.com/document/d/1PS5xLA0IDbj6McHIXXhShn51Zq37WvuistaidBPeHoE/edit?tab=t.0

Scope and Motivation

This API will allow users to define:

Which attributes are sent to the external processor as context for requests/responses
Which Dynamic Metadata namespaces are sent to the external processor as context
Which Dynamic Metadata namespaces the external process is permitted to emit metadata to

Attributes provide HTTP extensions with additional context (e.g. TCP, TLS and XDS attributes) that can be relevant inputs for the extension logic. Additionally, extensions may rely on well-know dynamic metadata emitted by previous filters, such as verified JWT subject and issuer. Finally, extensions may emit dynamic metadata that will be consumed by other extensions, access logs, etc.

Envoy has well-known metadata and attribute names to ensure safe consumption by other filters:

Users may select to use custom metadata namespaces in addition to well-known namespaces.

Comparison to other extension options

Many Envoy extensions are inherently capable of interaction with context attributes and dynamic metadata:

lua:
- get/set dynamic metadata
- stream and connection attributes are available through StreamInfo
wasm:
- get dynamic metadata
- get attributes through [get_property]()
- set metadata not implemented yet

For out-of-process extensions like ext-proc, Envoy must be explicitly configured to allow access to attributes and metadata and define the scope of access. With the increase in ext-proc use cases, such as the llm-instance-gateway, envoy-ai-gateway and externally-deployed WAFs, there is a greater need to provide Connection/Stream context, allow integration with other filters, and make it possible for external processors to emit metadata.

Security Considerations

In terms of security, the dynamic metadata shared with the external processor is scoped to the current connection and stream:

Dynamic state is generated per network connection or per HTTP stream. Dynamic state can be mutable if desired by the filter generating the state. [...]

Similarly, most attributes are scoped to the current connection or stream by their prefix (connection.*, request.*, response.*), with the exception of xds.* attributes such as xds.listener_metadata, xds.upstream_host_metadata. In Envoy Gateway, the static metadata for listeners, routes and upstream hosts will only contain the K8s resource metadata (Name, Namespace, GVK, EG-specific annotations), which are not considered sensitive information that should be hidden by Infra operators from Application developers or vice-versa.

Release Notes: No

envoyproxy / gateway