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
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.
| Value | Description |
|---|---|
Overwrite | The 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. |
AppendIfAbsent | The 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. |
PassThrough | The 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
Follow the Get started guide to install kgateway.
Follow the Sample app guide to create a gateway proxy with an HTTP listener and deploy the httpbin sample app.
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
Create a ListenerPolicy that sets the
serverHeaderTransformationfield toPassThrough.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 EOFReview the following table to understand this configuration. For more information about the available fields, see the API reference.
Setting Description 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 PassThroughto forward theserverheader from the backend unchanged, and to not add aserverheader if the backend does not send one.Repeat the request to the
/response-headersendpoint. Verify that the response now includes theserver: my-backendheader 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 ...Send a request to the
/status/200endpoint of the httpbin app, which does not set aserverheader. Verify that the response does not include aserverheader.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
Update the ListenerPolicy to set the
serverHeaderTransformationfield toAppendIfAbsent. TheserverNamefield sets the value that the gateway proxy uses when the backend does not send aserverheader.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 EOFReview the following table to understand this configuration.
Setting Description spec.default.httpSettings.serverHeaderTransformationSet to AppendIfAbsentto keep theserverheader from the backend, and to set aserverheader only if the backend does not send one.spec.default.httpSettings.serverNameThe value that the gateway proxy sets in the serverheader when the backend does not send one. If not set, the value isenvoy.Repeat the request to the
/response-headersendpoint. Verify that the response includes theserver: my-backendheader 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 ...Repeat the request to the
/status/200endpoint. Verify that the gateway proxy adds aserverheader with themy-gatewayvalue, 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
Update the ListenerPolicy to set only the
serverNamefield. Because theserverHeaderTransformationfield is not set, the gateway proxy uses the defaultOverwritemode.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 EOFReview the following table to understand this configuration.
Setting Description spec.default.httpSettings.serverNameThe value that the gateway proxy sets in the serverheader. BecauseserverHeaderTransformationis not set, the defaultOverwritemode applies, and the gateway proxy replaces anyserverheader from the backend with this value.Repeat the request to the
/response-headersendpoint. Verify that the gateway proxy replaces theserver: my-backendheader from the httpbin app with themy-gatewayvalue.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