Skip to content

For the complete documentation index, see llms.txt. Markdown versions of all docs pages are available by appending .md to any docs URL.

Server header

Page as Markdown

Keep, replace, or remove the server header that the gateway proxy sets in responses.

Control the value of the server header in responses from the gateway proxy.

About the server header

By default, the gateway proxy sets the server header to envoy in every response and overwrites any server header that the backend sends. You might want to change this behavior, such as to keep the server header that your backend sets, or to not reveal which proxy software your gateway runs.

To change how the gateway proxy handles the server header, set the serverHeaderTransformation field in the spec.default.httpSettings section of a ListenerPolicy to one of the following values.

ValueDescription
OverwriteThe default behavior. The gateway proxy sets the server header to envoy and overwrites any server header from the backend.
AppendIfAbsentThe gateway proxy keeps the server header from the backend. If the backend does not send a server header, the gateway proxy sets it to envoy.
PassThroughThe gateway proxy keeps the server header from the backend unchanged. If the backend does not send a server header, the response does not include one.

Before you begin

  1. Follow the Get started guide to install kgateway.

  2. Follow the Sample app guide to create a gateway proxy with an HTTP listener and deploy the httpbin sample app.

  3. Get the external address of the gateway and save it in an environment variable.

    export INGRESS_GW_ADDRESS=$(kubectl get svc -n kgateway-system http -o jsonpath="{.status.loadBalancer.ingress[0]['hostname','ip']}")
    echo $INGRESS_GW_ADDRESS  

Default behavior

Send a request to the httpbin app that asks httpbin to return a server: my-backend response header. The /response-headers endpoint of the httpbin app sets response headers from the query parameters in the request.

curl -i "http://$INGRESS_GW_ADDRESS:8080/response-headers?Server=my-backend" -H "host: www.example.com"

Example output: The gateway proxy overwrites the server header that the httpbin app sets with the envoy value. The response body shows the server header value that the httpbin app sent.

HTTP/1.1 200 OK
access-control-allow-credentials: true
access-control-allow-origin: *
content-type: application/json; encoding=utf-8
server: envoy
date: Wed, 11 Nov 2026 16:08:48 GMT
content-length: 39
x-envoy-upstream-service-time: 1

{
  "Server": [
    "my-backend"
  ]
}

Pass through the backend server header

  1. Create a ListenerPolicy that sets the serverHeaderTransformation field to PassThrough.

    kubectl apply -f- <<EOF
    apiVersion: gateway.kgateway.dev/v1alpha1
    kind: ListenerPolicy
    metadata:
      name: server-header
      namespace: kgateway-system
    spec:
      targetRefs:
      - group: gateway.networking.k8s.io
        kind: Gateway
        name: http
      default:
        httpSettings:
          serverHeaderTransformation: PassThrough
    EOF

    Review the following table to understand this configuration. For more information about the available fields, see the API reference.

    SettingDescription
    spec.targetRefsThe Gateway that this policy applies to. The policy applies to all HTTP and HTTPS listeners on the Gateway.
    spec.default.httpSettings.serverHeaderTransformationSet to PassThrough to forward the server header from the backend unchanged, and to not add a server header if the backend does not send one.
  2. Repeat the request to the /response-headers endpoint. Verify that the response now includes the server: my-backend header from the httpbin app.

    curl -i "http://$INGRESS_GW_ADDRESS:8080/response-headers?Server=my-backend" -H "host: www.example.com"

    Example output:

    HTTP/1.1 200 OK
    access-control-allow-credentials: true
    access-control-allow-origin: *
    content-type: application/json; encoding=utf-8
    server: my-backend
    date: Wed, 11 Nov 2026 16:08:48 GMT
    content-length: 39
    x-envoy-upstream-service-time: 1
    ...
    
  3. Send a request to the /status/200 endpoint of the httpbin app, which does not set a server header. Verify that the response does not include a server header.

    curl -i http://$INGRESS_GW_ADDRESS:8080/status/200 -H "host: www.example.com"

    Example output:

    HTTP/1.1 200 OK
    access-control-allow-credentials: true
    access-control-allow-origin: *
    date: Wed, 11 Nov 2026 16:08:48 GMT
    content-length: 0
    x-envoy-upstream-service-time: 1
    

Set the server header only if the backend does not

  1. Update the ListenerPolicy to set the serverHeaderTransformation field to AppendIfAbsent.

    kubectl apply -f- <<EOF
    apiVersion: gateway.kgateway.dev/v1alpha1
    kind: ListenerPolicy
    metadata:
      name: server-header
      namespace: kgateway-system
    spec:
      targetRefs:
      - group: gateway.networking.k8s.io
        kind: Gateway
        name: http
      default:
        httpSettings:
          serverHeaderTransformation: AppendIfAbsent
    EOF

    Review the following table to understand this configuration.

    SettingDescription
    spec.default.httpSettings.serverHeaderTransformationSet to AppendIfAbsent to keep the server header from the backend, and to set the envoy value only if the backend does not send one.
  2. Repeat the request to the /response-headers endpoint. Verify that the response includes the server: my-backend header from the httpbin app.

    curl -i "http://$INGRESS_GW_ADDRESS:8080/response-headers?Server=my-backend" -H "host: www.example.com"

    Example output:

    HTTP/1.1 200 OK
    access-control-allow-credentials: true
    access-control-allow-origin: *
    content-type: application/json; encoding=utf-8
    server: my-backend
    date: Wed, 11 Nov 2026 16:08:48 GMT
    content-length: 39
    x-envoy-upstream-service-time: 1
    ...
    
  3. Repeat the request to the /status/200 endpoint. Verify that the gateway proxy adds a server header with the envoy value, because the httpbin app does not send one.

    curl -i http://$INGRESS_GW_ADDRESS:8080/status/200 -H "host: www.example.com"

    Example output:

    HTTP/1.1 200 OK
    access-control-allow-credentials: true
    access-control-allow-origin: *
    date: Wed, 11 Nov 2026 16:08:48 GMT
    content-length: 0
    x-envoy-upstream-service-time: 1
    server: envoy
    

Cleanup

You can remove the resources that you created in this guide.
kubectl delete listenerpolicy server-header -n kgateway-system --ignore-not-found
Was this page helpful?