BackendTrafficPolicy responseOverride support request header matching

[sjoukedv]

Description:

Currently, we only support statusCode matching, e.g.

  responseOverride:
    - match:
        statusCodes:
          - type: Range
            range:
              start: 500
              end: 599
          - type: Value
            value: 403
      response:
        contentType: text/html
        header:
          set:
         # some extra header
          - name: x-envoy-custom-error
            value: custom-500-page

        # or user-friendly body
        body:
          type: ValueRef
          valueRef:
            group: ""
            kind: ConfigMap
            name: my-dynamic-error-template

It would be great if we also support the Accept request header so that we can return custom JSON for API routes, but keep the html page for request that are rendered in the browser.

This is something that was present in ingress-nginx

A custom error backend can use this information to return the best possible representation of an error page. For example, if the value of the Accept header send by the client was application/json, a carefully crafted backend could decide to return the error payload as a JSON document instead of HTML.

[optional Relevant Links:]

https://gateway.envoyproxy.io/docs/api/extension_types/#customresponsematch

[arkodg]

cc @rudrakhp

[nishantbkl3345-ship-it]

Hi, I’d like to take a look at this.

Before starting implementation, I wanted to confirm the expected direction: should this add support specifically for matching on the Accept header, or is the goal to make responseOverride.match support request header matching more generally?

[sjoukedv]

Hi, I’d like to take a look at this.

Before starting implementation, I wanted to confirm the expected direction: should this add support specifically for matching on the Accept header, or is the goal to make responseOverride.match support request header matching more generally?

Depends on how you are looking to implement this; without (or with few) additional fields or full support for configuration of the header name and it's value. I can't think of more use cases besides the Accept header, so this might even be changed to default behaviour with new documentation? This might have also been the reasoning behind the ingress-nginx implementation.

To give an example; Grafana which renders the UI, but also calls it's own API to query datasources. When querying it renders the response body in a pop-up on error, so this renders the HTML error page in case of issues while the request was sent to only accept json. While for errors when fetching HTML content I would like to keep showing the user-friendly HTML page.

[rudrakhp]

@sjoukedv any reason why you cannot handle this at the route level that supports header matching already? You can attach the BTP with JSON response override to the API route and another BTP with HTML response override to the user app route? So you have two routes and two BTPs.

[nishantbkl3345-ship-it]

That makes sense — thanks for pointing that out.

Using separate HTTPRoutes with header matching (e.g. on the Accept header) and attaching different BackendTrafficPolicies per route does seem to cover the use case without needing additional matching logic inside responseOverride itself.

I’ll take another look from that perspective and see if this can be solved purely at the route level before proposing any changes here.

[sjoukedv]

@sjoukedv any reason why you cannot handle this at the route level that supports header matching already? You can attach the BTP with JSON response override to the API route and another BTP with HTML response override to the user app route? So you have two routes and two BTPs.

You're right this would probably work when you have a single or few routes that you can duplicate. For many targeted routes by targetSelectors this becomes cumbersome to manage. In practice I use this to setup a "global" error page for all the services that are behind EG. It feels natural to me to sent the client back something that they accept if available. This improves error handling for downstream clients that get different content-type back than expected.

[nishantbkl3345-ship-it]

That makes sense — thanks for the clarification.

I’ll try to validate this use case using the route-level approach (HTTPRoute header matching + separate BackendTrafficPolicies), especially considering the “global” error handling scenario you described.

I want to see how manageable this is when applied across multiple services (e.g., using targetSelectors or shared patterns), and whether we can simplify the setup.

If it works well, I can put together a concrete example or documentation to make this pattern easier to adopt.

[nishantbkl3345-ship-it]

I validated the route-level approach locally using two HTTPRoutes and two BackendTrafficPolicys:

• one route intended for Accept: application/json
• one default/catch-all route for HTML
• separate responseOverride policies attached to each route

The resources were created successfully, but in my test both routes still produced the same plain 404 Not Found response with an empty body, regardless of:

• Accept: application/json
• Accept: text/html
• compound Accept headers
• no Accept header

So at least from this validation, the route-level split did not give differentiated JSON vs HTML behavior out of the box.

It’s possible I’m missing an additional requirement in how responseOverride is expected to work here, but I wanted to share the result since it suggests the workaround may not be as straightforward as it first seemed.

For reference, here are the curl results from my setup:

# Accept: application/json
HTTP/1.1 404 Not Found
content-length: 0

# Accept: text/html
HTTP/1.1 404 Not Found
content-length: 0

# Accept: application/json, text/html
HTTP/1.1 404 Not Found
content-length: 0

So the response did not vary based on the Accept header in this setup.

[rudrakhp]

@nishantbkl3345-ship-it can you please share your setup, the 2 BTPs + 2 routes solution is quite straightforward, I don't see why it won't work

[rudrakhp]

In practice I use this to setup a "global" error page for all the services that are behind EG.

@sjoukedv Why can't we manage a single BTP targeting all routes in that case? Something like:

apiVersion: gateway.envoyproxy.io/v1alpha1
kind: BackendTrafficPolicy
metadata:
  name: shared-html-errors
  namespace: gateway-conformance-infra
spec:
  targetRefs:
    - group: gateway.networking.k8s.io
      kind: HTTPRoute
      name: response-override-html
    - group: gateway.networking.k8s.io
      kind: HTTPRoute
      name: another-html-route
  responseOverride:
    - match:
        statusCodes:
          - type: Range
            range:
              start: 500
              end: 599
      response:
        contentType: text/html
        body:
          type: ValueRef
          valueRef:
            group: ""
            kind: ConfigMap
            name: my-dynamic-error-template

You will have twice the number of routes than before but the same single BTP resource with all the routes attached, which I think you might already be doing if you have a global error page setup.

[sjoukedv]

In practice I use this to setup a "global" error page for all the services that are behind EG.

@sjoukedv Why can't we manage a single BTP targeting all routes in that case? Something like:

apiVersion: gateway.envoyproxy.io/v1alpha1
kind: BackendTrafficPolicy
metadata:
  name: shared-html-errors
  namespace: gateway-conformance-infra
spec:
  targetRefs:
    - group: gateway.networking.k8s.io
      kind: HTTPRoute
      name: response-override-html
    - group: gateway.networking.k8s.io
      kind: HTTPRoute
      name: another-html-route
  responseOverride:
    - match:
        statusCodes:
          - type: Range
            range:
              start: 500
              end: 599
      response:
        contentType: text/html
        body:
          type: ValueRef
          valueRef:
            group: ""
            kind: ConfigMap
            name: my-dynamic-error-template

You will have twice the number of routes than before but the same single BTP resource with all the routes attached, which I think you might already be doing if you have a global error page setup.

Good observation, we can. Using selection by labels makes this even a bit easier. Discussion then shifts towards the duplicate routes. This depends a lot on how you create these routes. For me this is with 3rd party helm charts mostly. That means I need to create and maintain the additional routes myself because this separate route per Accept header implementation is specific to EG?

P.s. I just target the Gateway(s) now in the BTP.