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, or to the value of the serverName field if set, 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, or to the value of the serverName field if set.
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.

To change the value that the gateway proxy sets, use the serverName field in the same section. The serverName field applies to the Overwrite and AppendIfAbsent modes. In the PassThrough mode, the gateway proxy never sets the server header, so the serverName field has no effect.

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. The serverName field sets the value that the gateway proxy uses when the backend does not send a server header.

    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
          serverName: my-gateway
    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 a server header only if the backend does not send one.
    spec.default.httpSettings.serverNameThe value that the gateway proxy sets in the server header when the backend does not send one. If not set, the value is envoy.
  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 my-gateway 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: my-gateway
    

Replace the server header with a custom value

  1. Update the ListenerPolicy to set only the serverName field. Because the serverHeaderTransformation field is not set, the gateway proxy uses the default Overwrite mode.

    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:
          serverName: my-gateway
    EOF

    Review the following table to understand this configuration.

    SettingDescription
    spec.default.httpSettings.serverNameThe value that the gateway proxy sets in the server header. Because serverHeaderTransformation is not set, the default Overwrite mode applies, and the gateway proxy replaces any server header from the backend with this value.
  2. Repeat the request to the /response-headers endpoint. Verify that the gateway proxy replaces the server: my-backend header from the httpbin app with the my-gateway value.

    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-gateway
    date: Wed, 11 Nov 2026 16:08:48 GMT
    content-length: 39
    x-envoy-upstream-service-time: 1
    ...
    

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?