feat: xds policy metadata

[zirain]

This's an alternative for #6801, users should be able to dump the policies applied to the route with command %METADATA(ROUTE:envoy-gateway:policies)%.

This will help users to find which policy cause 429 response.

Sample output as following:

{
  ":authority": "172.18.255.201",
  "authorization": null,
  "bytes_received": 0,
  "bytes_sent": 0,
  "downstream_local_address": "10.244.2.26:10080",
  "downstream_remote_address": "172.18.0.1:55720",
  "duration": 2,
  "method": "GET",
  "policies": [
    {
      "kind": "BackendTrafficPolicy",
      "name": "policy-httproute",
      "namespace": "default"
    }
  ],
  "protocol": "HTTP/1.1",
  "ratelimit": {
    "descriptors": [
      {
        "entries": [
          "httproute/default/http-ratelimit/rule/0/match/0/*=httproute/default/http-ratelimit/rule/0/match/0/*",
          "rule-0-match-0=rule-0-match-0"
        ]
      }
    ],
    "domain": "default/eg/http"
  },
  "request_headers_bytes": 224,
  "requested_server_name": null,
  "response_code": 429,
  "response_code_details": "request_rate_limited",
  "response_flags": "RL",
  "route_name": "httproute/default/http-ratelimit/rule/0/match/0/*",
  "start_time": "2025-12-30T03:23:15.726Z",
  "upstream_cluster": "httproute/default/http-ratelimit/rule/0",
  "upstream_duration": null,
  "upstream_host": null,
  "upstream_local_address": null,
  "upstream_transport_failure_reason": null,
  "user-agent": "curl/8.7.1",
  "x-envoy-origin-path": "/echo",
  "x-envoy-upstream-service-time": null,
  "x-forwarded-for": "172.18.0.1",
  "x-request-id": "551f54cd-e7f3-49f8-a574-fcda06bceab0"
}

[codecov]

Codecov Report

❌ Patch coverage is 95.34884% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 72.76%. Comparing base (47a1dfa) to head (f625688).

Files with missing lines	Patch %	Lines
internal/gatewayapi/backendtrafficpolicy.go	80.00%	1 Missing and 1 partial ⚠️

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #7824   +/-   ##
=======================================
  Coverage   72.75%   72.76%           
=======================================
  Files         235      235           
  Lines       35100    35142   +42     
=======================================
+ Hits        25537    25570   +33     
- Misses       7748     7755    +7     
- Partials     1815     1817    +2     

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

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[arkodg]

cc @guydc is there any prior art for policy related metadata

[guydc]

Hi,

1. we can also use the resources container here, but can add another container as well (maybe better for users who assume something about the resource list length/contents).
2. are we adding the "Effective" policy here? Do we represent conflicts/overrides/inheritance? Might be nice to explain what exactly this describes.
3. maybe make this opt-in? This can inflate if we end up including other policies in the future...

[zirain]

@guydc

[zirain]

maybe make this opt-in

we can resuse the RuntimeFlags to guard this.

[arkodg]

hey we discussed this in the community meeting this week, this is a great feature but hoping you can give more clarity on the use case

1. Is the Policy metadata meant to be used primarily in access logs ?
2. If yes, from an end user perspective, what does it mean if the policy is part of access log line ?

cc @guydc @nacx

[zirain]

Generally, the user case is to find out the policy(we can add Security Policy) applied to the route when client received a non 200 resposne.

[arkodg]

For that specific case, shouldnt the metadata be on the RBAC filter ?

[zirain]

For that specific case, shouldnt the metadata be on the RBAC filter ?

RBAC is for 4xx, and 429 for ratelimit. this'a a general solution for any xPolicy, either from Envoy Gateway Extensions or Gateway API

BTW, can you elaborate a little more about set metadata to the RBAC filter?

[wbpcode]

Now, the Envoy have supported a filter state to record the filter name that return the local response (envoy.filters.network.http_connection_manager.local_reply_owner see https://www.envoyproxy.io/docs/envoy/latest/configuration/advanced/well_known_filter_state.html), with the filter state and also the route name's help, we should could identify the filter and related policy?

Anyway, for now, there is no general way to attach additional metadata for single filter in http filter chain or attach additional metadata for single filter config in the route configuration for now. (And I do not suggest to do that if no strong reason.)

Although part of our filters support metadata in their configuration, but it's implementation detail of the filter and Envoy's core will not aware it.

Or in the future, we can try the envoyproxy/envoy#42912, which could provide the actual per route filter, then, the plugin name could be used to map the policy name directly.