feat(api): support per-route gRPC initial metadata for ExtProc via ExtProcPerRoute

[surenraju-careem]

What type of PR is this?

feat(api)

What this PR does / why we need it:

Adds a grpcInitialMetadata field to the ExtProc API in EnvoyExtensionPolicy, allowing users to specify per-route key-value pairs sent as gRPC stream initial metadata to the external processing server via ExtProcPerRoute.overrides.grpc_initial_metadata.

Today, patchRoute() in the xDS translator always emits an empty FilterConfig{Config: &anypb.Any{}} for every ext_proc-enabled route — regardless of which EnvoyExtensionPolicy (with sectionName scoping) is attached. This means the ext_proc server has no stable, per-route signal to determine which HTTPRoute rule is being processed.

The only current option is Attributes["xds.route_name"], but that value is index-based (httproute/ns/name/rule/0/match/0/...) and breaks whenever rules are reordered.

With this change, operators can inject stable, semantic metadata:

apiVersion: gateway.envoyproxy.io/v1alpha1
kind: EnvoyExtensionPolicy
metadata:
  name: checkout-ext-proc
spec:
  targetRefs:
  - group: gateway.networking.k8s.io
    kind: HTTPRoute
    name: checkout-route
    sectionName: fraud-check-rule
  extProc:
  - backendRefs:
    - name: fraud-check-service
      port: 9001
    grpcInitialMetadata:
    - name: x-handler
      value: fraud-check
    - name: x-route-rule
      value: fraud-check-rule

Envoy then delivers these as gRPC stream initial metadata to the ext_proc server on every request matching that rule, enabling the server to apply rule-specific logic without any unstable xDS route name parsing.

This maps directly to ExtProcOverrides.grpc_initial_metadata (field 7), which is fully implemented in Envoy since envoy#31544.

Which issue(s) this PR fixes:

Fixes #8459

Changes:

• api/v1alpha1: add GRPCInitialMetadata []ExtProcGRPCInitialMetadataEntry to ExtProc struct
• internal/ir: add GRPCInitialMetadata field and ExtProcGRPCInitialMetadata type
• internal/gatewayapi: map API field to IR in buildExtProc()
• internal/xds/translator: patchRoute() emits a typed ExtProcPerRoute with overrides.grpc_initial_metadata when entries are present; falls back to empty FilterConfig otherwise
• CRD manifests regenerated (make manifests)
• API docs regenerated (make generate)
• examples/grpc-ext-proc: updated to read and reflect gRPC stream initial metadata in response headers for e2e observability

Release Notes: Yes

[netlify]

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

Name	Link
🔨 Latest commit	949d979
🔍 Latest deploy log	https://app.netlify.com/projects/cerulean-figolla-1f9435/deploys/69afbbdb614629000995730c

[codecov]

Codecov Report

❌ Patch coverage is 17.24138% with 24 lines in your changes missing coverage. Please review.
✅ Project coverage is 74.09%. Comparing base (a470576) to head (949d979).
⚠️ Report is 157 commits behind head on main.

Files with missing lines	Patch %	Lines
internal/xds/translator/extproc.go	17.39%	17 Missing and 2 partials ⚠️
internal/gatewayapi/envoyextensionpolicy.go	16.66%	4 Missing and 1 partial ⚠️

❌ Your patch check has failed because the patch coverage (17.24%) is below the target coverage (60.00%). You can increase the patch coverage or adjust the target coverage.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #8463      +/-   ##
==========================================
- Coverage   74.13%   74.09%   -0.05%     
==========================================
  Files         242      242              
  Lines       37579    37604      +25     
==========================================
+ Hits        27859    27862       +3     
- Misses       7778     7798      +20     
- Partials     1942     1944       +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.

[zhaohuabing]

Could we add gRPC initial metadata to one of the existing xds test yaml file so we can verify the generated envoy config?

[zhaohuabing]

Is it possible that we may need to support HTTP ext proc in the future? If so, a GRPCService wrapper might be more furture-proof. cc @guydc

[github-actions]

This pull request has been automatically marked as stale because it has not had activity in the last 30 days. Please feel free to give a status update now, ping for review, when it's ready. Thank you for your contributions!