For the complete documentation index, see llms.txt. Markdown versions of all docs pages are available by appending .md to any docs URL.
Original client IP address
Configure how the gateway proxy determines the original client IP address from the connection or the X-Forwarded-For header.
Configure how the gateway proxy determines the original client IP address when requests pass through load balancers, CDNs, or other proxies.
About the client IP address
The gateway proxy uses the client IP address of a request in several places, such as to match the rules of an ACL policy, to apply rate limits by remote address, to set the X-Envoy-External-Address header, and to log the %DOWNSTREAM_REMOTE_ADDRESS% value in access logs.
By default, the gateway proxy uses the source address of the downstream connection as the client IP address. The X-Forwarded-For (XFF) header that a client sends is not trusted to determine the client IP address. Before the gateway proxy forwards the request, it appends the source address of the connection to the XFF header.
When the gateway proxy runs behind a load balancer or proxy that terminates the client connection, the source address of the connection belongs to that proxy instead of the client. If the proxy works at the TCP level, such as a network load balancer, you can preserve the client address with the externalTrafficPolicy: Local setting on the gateway proxy Service or with proxy protocol. If the proxy works at the HTTP level, such as an application load balancer or a CDN, it typically records the client address in the XFF header. In that case, configure the gateway proxy to trust the addresses that these proxies add to the XFF header.
You can use the following settings in the spec.default.httpSettings section of a ListenerPolicy to configure how the gateway proxy determines the client IP address.
| Setting | Description |
|---|---|
useRemoteAddress | Defaults to true. When true, the gateway proxy uses the source address of the connection as the client IP address, unless you also set xffNumTrustedHops. When false, the gateway proxy takes the client IP address from the XFF header and does not append to the XFF header, unless you set skipXFFAppend to false or the connection comes from an address outside your xffTrustedCIDRs ranges. When false, the gateway proxy also does not set the X-Envoy-External-Address header. |
xffNumTrustedHops | The number of trusted proxies in front of the gateway proxy that append to the XFF header. If useRemoteAddress is true and you set this value to N, the client IP address is the Nth address from the right of the XFF header that the gateway proxy receives. If useRemoteAddress is false, the client IP address is the N+1th address from the right, and a value of 0 uses the rightmost address. If the XFF header contains fewer addresses, the gateway proxy uses the source address of the connection. You cannot set this field together with xffTrustedCIDRs. |
xffTrustedCIDRs | The CIDR ranges of your trusted proxies. If the source address of the connection is in one of these ranges, the gateway proxy reads the XFF header from right to left and uses the first address that is not in a trusted range as the client IP address. If all addresses in the XFF header are trusted, the leftmost address is used. If the source address of the connection is not in a trusted range, the gateway proxy uses the source address as the client IP address and appends it to the XFF header. You must set useRemoteAddress to false to use this field, and you cannot set this field together with xffNumTrustedHops. |
skipXFFAppend | Set to true to forward the XFF header without appending the source address of the connection. If unset, the gateway proxy appends to the XFF header when useRemoteAddress is true, and does not append when useRemoteAddress is false. If you set xffTrustedCIDRs, the gateway proxy always appends the source address of connections from untrusted addresses, even if skipXFFAppend is true. |
Warning
Trust the XFF header only for addresses that your own proxies add. If clients can reach the gateway proxy directly without passing through your trusted proxies, they can send a forged XFF header to set any client IP address, such as to bypass an ACL policy or a rate limit.
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
Review how the gateway proxy determines the client IP address without a ListenerPolicy.
Send a request to the httpbin app with an XFF header that sets the
203.0.113.10client IP address.curl http://$INGRESS_GW_ADDRESS:8080/headers -H "host: www.example.com" \ -H "X-Forwarded-For: 203.0.113.10"Example output for a port-forward. The
X-Envoy-External-Addressheader shows the client IP address that the gateway proxy determined. This address is the source address of the connection,127.0.0.1, and not the address in the XFF header that the client sent. If you use a LoadBalancer, the header shows the address of your load balancer or node instead. The XFF header that is forwarded to the httpbin app has another address appended to it. For connections from a loopback address, such as through a port-forward, the gateway proxy appends its own IP address, such as10.244.0.7. For other connections, the gateway proxy appends the source address of the connection.{ "headers": { "Accept": [ "*/*" ], "Host": [ "www.example.com" ], "User-Agent": [ "curl/8.7.1" ], "X-Envoy-Expected-Rq-Timeout-Ms": [ "15000" ], "X-Envoy-External-Address": [ "127.0.0.1" ], "X-Forwarded-For": [ "203.0.113.10,10.244.0.7" ], "X-Forwarded-Proto": [ "http" ], "X-Request-Id": [ "b9e27a1c-3f6d-4a8e-9c52-7d1e0f4a6b38" ] } }
Trust a number of proxy hops
Use the xffNumTrustedHops setting when you know how many proxies that append to the XFF header are in front of the gateway proxy. For example, if all requests pass through one application load balancer, set xffNumTrustedHops to 1.
Create a ListenerPolicy that trusts one proxy hop in the XFF header.
kubectl apply -f- <<EOF apiVersion: gateway.kgateway.dev/v1alpha1 kind: ListenerPolicy metadata: name: client-ip namespace: kgateway-system spec: targetRefs: - group: gateway.networking.k8s.io kind: Gateway name: http default: httpSettings: xffNumTrustedHops: 1 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.xffNumTrustedHopsThe number of trusted proxies that append to the XFF header. Because useRemoteAddressistrueby default, a value of1sets the client IP address to the rightmost address in the XFF header that the gateway proxy receives.Repeat the request with the
203.0.113.10address in the XFF header. In this example, your curl request plays the role of the trusted load balancer that adds the client address to the XFF header. Verify that theX-Envoy-External-Addressheader now shows the203.0.113.10address from the XFF header.curl http://$INGRESS_GW_ADDRESS:8080/headers -H "host: www.example.com" \ -H "X-Forwarded-For: 203.0.113.10"Example output:
{ "headers": { "Accept": [ "*/*" ], "Host": [ "www.example.com" ], "User-Agent": [ "curl/8.7.1" ], "X-Envoy-Expected-Rq-Timeout-Ms": [ "15000" ], "X-Envoy-External-Address": [ "203.0.113.10" ], "X-Forwarded-For": [ "203.0.113.10,10.244.0.7" ], "X-Forwarded-Proto": [ "http" ], "X-Request-Id": [ "4c8d2e6f-1a7b-4f3e-8d95-2b6c0e9a7f14" ] } }Send a request with two addresses in the XFF header. Verify that the gateway proxy uses only the rightmost address,
198.51.100.7, as the client IP address. Because only one proxy hop is trusted, the gateway proxy ignores the203.0.113.10address that a client might have forged.curl http://$INGRESS_GW_ADDRESS:8080/headers -H "host: www.example.com" \ -H "X-Forwarded-For: 203.0.113.10, 198.51.100.7"Example output:
... "X-Envoy-External-Address": [ "198.51.100.7" ], "X-Forwarded-For": [ "203.0.113.10, 198.51.100.7,10.244.0.7" ], ...
Trust proxy CIDR ranges
Use the xffTrustedCIDRs setting when you know the IP address ranges of your proxies, but the number of proxies that a request passes through can vary.
Create a ListenerPolicy that trusts the XFF header for connections from specific CIDR ranges. You must set
useRemoteAddresstofalseto use trusted CIDR ranges.Review the following table to understand this configuration.kubectl apply -f- <<EOF apiVersion: gateway.kgateway.dev/v1alpha1 kind: ListenerPolicy metadata: name: client-ip namespace: kgateway-system spec: targetRefs: - group: gateway.networking.k8s.io kind: Gateway name: http default: httpSettings: useRemoteAddress: false xffTrustedCIDRs: - 10.0.0.0/8 - 127.0.0.1/32 EOFSetting Description spec.default.httpSettings.useRemoteAddressSet to falseto take the client IP address from the XFF header. This setting is required forxffTrustedCIDRs.spec.default.httpSettings.xffTrustedCIDRsThe CIDR ranges of your trusted proxies. Replace 10.0.0.0/8with the address ranges of your load balancers or proxies. The127.0.0.1/32range trusts connections through a port-forward for local testing. Remove it in production setups. With this configuration, a request from a trusted address with an XFF header of198.51.100.7, 203.0.113.10, 10.0.0.5gets the client IP address203.0.113.10, because10.0.0.5is in a trusted range. The gateway proxy does not set theX-Envoy-External-Addressheader in this mode.Port-forward the gateway proxy on port 19000 to open the Envoy admin interface.
kubectl port-forward deploy/http -n kgateway-system 19000In the Envoy configuration, verify that the original IP detection extension includes your trusted CIDR ranges. Alternatively, you can open the Envoy admin interface and look for the
original_ip_detection_extensionssetting in the config dump.curl -s localhost:19000/config_dump | jq '[.. | objects | select(has("original_ip_detection_extensions")) | {use_remote_address, original_ip_detection_extensions}]'Example output:
[ { "use_remote_address": false, "original_ip_detection_extensions": [ { "name": "envoy.http.original_ip_detection.xff", "typed_config": { "@type": "type.googleapis.com/envoy.extensions.http.original_ip_detection.xff.v3.XffConfig", "xff_trusted_cidrs": { "cidrs": [ { "address_prefix": "10.0.0.0", "prefix_len": 8 }, { "address_prefix": "127.0.0.1", "prefix_len": 32 } ] } } } ] } ]
Stop appending to the XFF header
By default, the gateway proxy appends the source address of the connection to the XFF header. If your backends expect the XFF header exactly as your trusted proxies set it, you can turn off appending.
Create a ListenerPolicy that sets
skipXFFAppendtotrue.Review the following table to understand this configuration.kubectl apply -f- <<EOF apiVersion: gateway.kgateway.dev/v1alpha1 kind: ListenerPolicy metadata: name: client-ip namespace: kgateway-system spec: targetRefs: - group: gateway.networking.k8s.io kind: Gateway name: http default: httpSettings: skipXFFAppend: true EOFSetting Description spec.default.httpSettings.skipXFFAppendSet to trueto forward the XFF header without appending the source address of the connection. This policy replaces the policy from the previous section, souseRemoteAddressreturns to its default value oftrue, and the gateway proxy uses the source address of the connection as the client IP address.Send a request with an XFF header. Verify that the XFF header that the httpbin app receives contains only the
203.0.113.10address that you sent.curl http://$INGRESS_GW_ADDRESS:8080/headers -H "host: www.example.com" \ -H "X-Forwarded-For: 203.0.113.10"Example output:
... "X-Envoy-External-Address": [ "127.0.0.1" ], "X-Forwarded-For": [ "203.0.113.10" ], ...
Cleanup
You can remove the resources that you created in this guide.kubectl delete listenerpolicy client-ip -n kgateway-system --ignore-not-found