api: ext-proc attributes

[guydc]

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.

Attributes provide HTTP extensions with additional context (e.g. TCP, TLS and XDS attributes) that can be relevant inputs for the extension logic.

Comparison to other extension options

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

• lua: stream and connection attributes are available through StreamInfo
• wasm: get attributes through get_property

For out-of-process extensions like ext-proc, Envoy must be explicitly configured to allow access to attributes and 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 extension with context.

Security Considerations

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, xds.node and generic metadata and filter state access attributes.

Related Work

• Issue: Support Additional External Processing Options #3170
• Previous Attempts by various contributors:
  • api: adds request/response attributes ExtProc options #4496
  • api: add Untyped metadata support in ExtProc #4160
  • api: add metadata and attribute options for ext-proc #3247

Release Notes: Yes

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 65.60%. Comparing base (a383dd9) to head (bcd6d76).
Report is 1 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #4794      +/-   ##
==========================================
- Coverage   65.61%   65.60%   -0.02%     
==========================================
  Files         211      211              
  Lines       31989    31989              
==========================================
- Hits        20991    20987       -4     
- Misses       9760     9762       +2     
- Partials     1238     1240       +2     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[arkodg]

LGTM thanks !

[arkodg]

curious what happens when something like connection.unknown is used ? is it a no-op ?

[guydc]

curious what happens when something like connection.unknown is used ? is it a no-op ?

Yes, it's just ignored and not passed. Config is still accepted by the proxy.