feat: xds policy metadata by zirain · Pull Request #7824 · envoyproxy/gateway

zirain · 2025-12-26T07:50:09Z

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 · 2025-12-27T10:29:03Z

Codecov Report

❌ Patch coverage is 95.55556% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 73.73%. Comparing base (424d039) to head (8e7d18a).
⚠️ Report is 6 commits behind head on main.

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

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #7824      +/-   ##
==========================================
+ Coverage   73.70%   73.73%   +0.02%     
==========================================
  Files         237      237              
  Lines       35703    35747      +44     
==========================================
+ Hits        26316    26359      +43     
+ Misses       7529     7528       -1     
- Partials     1858     1860       +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 · 2026-01-01T21:13:56Z

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

guydc · 2026-01-02T15:28:57Z

Hi,

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).
are we adding the "Effective" policy here? Do we represent conflicts/overrides/inheritance? Might be nice to explain what exactly this describes.
maybe make this opt-in? This can inflate if we end up including other policies in the future...

zirain · 2026-01-03T00:03:30Z

internal/ir/xds.go

 	SectionName string `json:"sectionName,omitempty" yaml:"sectionName,omitempty"`
+
+	// TrafficPolicy is the NamespacedName of the TrafficPolicy resource associated with this resource
+	// If merged with parent policy, users need to check the status to find more details.


zirain · 2026-01-03T00:05:51Z

maybe make this opt-in

we can resuse the RuntimeFlags to guard this.

arkodg · 2026-01-10T19:48:26Z

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

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

cc @guydc @nacx

zirain · 2026-01-11T02:23:12Z

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 · 2026-01-11T05:00:39Z

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

zirain · 2026-01-11T10:56:18Z

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 · 2026-01-11T12:46:06Z

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.

zirain · 2026-01-14T04:12:55Z

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

Is the Policy metadata meant to be used primarily in access logs ?

If yes, from an end user perspective, what does it mean if the policy is part of access log line ?

cc @guydc @nacx

yes for now
it's not recommended as @wbpcode said in feat: xds policy metadata #7824 (comment)

nacx · 2026-01-14T11:36:03Z

AFAIU, this provides a generic way of listing what policies have taken place for a given request, to help users troubleshoot and understand where errors may be coming from. The current impl is the starting point (starting with BTP) and the idea is to be able to expand to other types when needed, as the approach is meant to be generic.
The introduction of the policy knob LGTM (I think it has the right semantics), and users interested in this field will have an easy way to add it to the access logs.

netlify · 2026-01-16T01:25:05Z

✅ Deploy Preview for cerulean-figolla-1f9435 canceled.

Name	Link
🔨 Latest commit	`8e7d18a`
🔍 Latest deploy log	https://app.netlify.com/projects/cerulean-figolla-1f9435/deploys/6976feed15c0cd0008271f84

arkodg · 2026-01-16T02:49:54Z

internal/ir/xds.go

+
+	// TrafficPolicy is the NamespacedName of the TrafficPolicy resource associated with this resource
+	// If merged with parent policy, users need to check the status to find more details.
+	TrafficPolicy *types.NamespacedName `json:"trafficPolicy,omitempty" yaml:"trafficPolicy,omitempty"`


can we make this generic like []Policies and also include Kind ?

what about group?

we dont seem to use it for other resources so its fine to not include for now imo

internal/xds/translator/testdata/in/xds-ir/http-route-with-trafficpolicy-metadta.yaml

arkodg · 2026-01-17T18:16:57Z

internal/xds/translator/metadata.go

+	policyList := &structpb.ListValue{}
+
+	for _, policy := range metadata.Policies {
+		policyList.Values = append(policyList.Values, buildTrafficPolicyMetadata(policy))


Suggested change

policyList.Values = append(policyList.Values, buildTrafficPolicyMetadata(policy))

policyList.Values = append(policyList.Values, buildpolicyMetadata(policy))

arkodg · 2026-01-17T18:21:37Z

hey @zirain this is looking good, the question I have is how is policies different from resources metadata and should they be combined ?

zirain · 2026-01-18T01:39:37Z

hey @zirain this is looking good, the question I have is how is policies different from resources metadata and should they be combined ?

resources is what always be there, policies is optional.
My original idea is that users didn't need to iter all the resources to check if there any policies applied.

arkodg · 2026-01-20T00:32:17Z

thanks, this LGTM, wdyt @guydc

Signed-off-by: zirain <zirain2009@gmail.com>

guydc

LGTM, thanks!

* feat: xds policy metadata Signed-off-by: zirain <zirain2009@gmail.com> * fix gen Signed-off-by: zirain <zirain2009@gmail.com> * fix lint Signed-off-by: zirain <zirain2009@gmail.com> * use slice Signed-off-by: zirain <zirain2009@gmail.com> * add test Signed-off-by: zirain <zirain2009@gmail.com> * name Signed-off-by: zirain <zirain2009@gmail.com> --------- Signed-off-by: zirain <zirain2009@gmail.com> Signed-off-by: Sadmi Bouhafs <sadmibouhafs@gmail.com>

zirain mentioned this pull request Dec 27, 2025

ratelimit: use policy namespaced name as descriptor value #6801

Closed

zirain force-pushed the policy-metadata branch from 8f8a034 to 22d1677 Compare December 27, 2025 10:19

zirain force-pushed the policy-metadata branch from 22d1677 to 7734d4f Compare December 30, 2025 03:30

zirain marked this pull request as ready for review December 30, 2025 03:36

zirain requested a review from a team as a code owner December 30, 2025 03:36

zirain force-pushed the policy-metadata branch from 7734d4f to f625688 Compare December 30, 2025 03:36

zirain commented Jan 3, 2026

View reviewed changes

zirain force-pushed the policy-metadata branch from f625688 to d74c104 Compare January 16, 2026 01:25

arkodg reviewed Jan 16, 2026

View reviewed changes

internal/xds/translator/testdata/in/xds-ir/http-route-with-trafficpolicy-metadta.yaml Show resolved Hide resolved

zirain force-pushed the policy-metadata branch from 188284d to 5f9f8bb Compare January 16, 2026 03:34

zirain requested a review from arkodg January 16, 2026 03:38

zirain added this to the v1.7.0-rc.1 Release milestone Jan 16, 2026

zirain force-pushed the policy-metadata branch from 33fa670 to c7dc2b8 Compare January 17, 2026 01:22

arkodg reviewed Jan 17, 2026

View reviewed changes

zirain force-pushed the policy-metadata branch from c7dc2b8 to 573ddd6 Compare January 18, 2026 01:37

zirain force-pushed the policy-metadata branch 2 times, most recently from f8c9012 to 2649d65 Compare January 26, 2026 03:46

zirain added 6 commits January 26, 2026 13:43

feat: xds policy metadata

cf67523

Signed-off-by: zirain <zirain2009@gmail.com>

fix gen

2d6d790

Signed-off-by: zirain <zirain2009@gmail.com>

fix lint

341ec46

Signed-off-by: zirain <zirain2009@gmail.com>

use slice

3d0c878

Signed-off-by: zirain <zirain2009@gmail.com>

add test

625614e

Signed-off-by: zirain <zirain2009@gmail.com>

name

8e7d18a

Signed-off-by: zirain <zirain2009@gmail.com>

zirain force-pushed the policy-metadata branch from 2649d65 to 8e7d18a Compare January 26, 2026 05:43

guydc approved these changes Jan 26, 2026

View reviewed changes

guydc merged commit c942078 into envoyproxy:main Jan 26, 2026
57 of 59 checks passed

zirain deleted the policy-metadata branch January 26, 2026 13:54

	policyList.Values = append(policyList.Values, buildTrafficPolicyMetadata(policy))
	policyList.Values = append(policyList.Values, buildpolicyMetadata(policy))

Conversation

zirain commented Dec 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codecov bot commented Dec 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

arkodg commented Jan 1, 2026

Uh oh!

guydc commented Jan 2, 2026

Uh oh!

zirain Jan 3, 2026

Choose a reason for hiding this comment

Uh oh!

zirain commented Jan 3, 2026

Uh oh!

arkodg commented Jan 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

zirain commented Jan 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

arkodg commented Jan 11, 2026

Uh oh!

zirain commented Jan 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

wbpcode commented Jan 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

zirain commented Jan 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

nacx commented Jan 14, 2026

Uh oh!

netlify bot commented Jan 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for cerulean-figolla-1f9435 canceled.

Uh oh!

arkodg Jan 16, 2026

Choose a reason for hiding this comment

Uh oh!

zirain Jan 16, 2026

Choose a reason for hiding this comment

Uh oh!

arkodg Jan 17, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

arkodg Jan 17, 2026

Choose a reason for hiding this comment

Uh oh!

arkodg commented Jan 17, 2026

Uh oh!

zirain commented Jan 18, 2026

Uh oh!

arkodg commented Jan 20, 2026

Uh oh!

guydc left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

zirain commented Dec 26, 2025 •

edited

Loading

codecov bot commented Dec 27, 2025 •

edited

Loading

arkodg commented Jan 10, 2026 •

edited

Loading

zirain commented Jan 11, 2026 •

edited

Loading

zirain commented Jan 11, 2026 •

edited

Loading

wbpcode commented Jan 11, 2026 •

edited

Loading

zirain commented Jan 14, 2026 •

edited

Loading

netlify bot commented Jan 16, 2026 •

edited

Loading