From f963c195798f13b432e8202cb8b06fbd9b1e456b Mon Sep 17 00:00:00 2001 From: Sidharath Bansal <60166938+SidharathBansal@users.noreply.github.com> Date: Mon, 20 Jul 2026 21:45:41 +0530 Subject: [PATCH 1/3] NGF: document useClusterIP in UpstreamSettingsPolicy guide --- .../traffic-management/upstream-settings.md | 78 +++++++++++++++++++ 1 file changed, 78 insertions(+) diff --git a/content/ngf/traffic-management/upstream-settings.md b/content/ngf/traffic-management/upstream-settings.md index 29c3c54174..4443b863c9 100644 --- a/content/ngf/traffic-management/upstream-settings.md +++ b/content/ngf/traffic-management/upstream-settings.md @@ -567,6 +567,84 @@ upstream default_tea_80 { --- +## Route upstream traffic to the Service ClusterIP + +By default, NGINX Gateway Fabric resolves each backend Service to its individual Pod IPs and uses those as the upstream servers. Setting `useClusterIP` to `true` in an `UpstreamSettingsPolicy` configures NGINX to route to the Service's ClusterIP and port instead, so the upstream contains a single server (the Service VIP). This is useful for service mesh compatibility and for controllers or operators that require traffic to traverse the Service VIP. + +You can also enable this globally for all Services through the `useClusterIP` field of the `NginxProxy` resource. When both are configured for the same Service, the `UpstreamSettingsPolicy` value takes precedence. See [Data plane configuration]({{< ref "/ngf/how-to/data-plane-configuration.md" >}}) for the global setting. + +{{< call-out "note" >}} Because the upstream contains only the Service VIP as a single server, you lose NGINX's load balancing across the backend Pods. Traffic is instead load balanced by the Kubernetes Service (kube-proxy), so the load balancing and keepalive settings of an `UpstreamSettingsPolicy` no longer apply to that Service. `useClusterIP` applies only when the target Service has a ClusterIP; headless (`ClusterIP: None`) and ExternalName Services fall back to the default Pod IP resolution. {{< /call-out >}} + +To route to the ClusterIP of the `coffee` service, create the following `UpstreamSettingsPolicy`: + +```yaml +kubectl apply -f - < +``` + +Find the ClusterIP of the `coffee` service: + +```shell +kubectl get service coffee +``` + +Next, verify that the `coffee` upstream targets that ClusterIP by inspecting the NGINX configuration: + +```shell +kubectl exec -it deployments/gateway-nginx -- nginx -T +``` + +You should see a single `server` in the `coffee` upstream set to the Service ClusterIP and port (`10.244.0.14` is the ClusterIP in this example): + +```text +upstream default_coffee_80 { + random two least_conn; + zone default_coffee_80 512k; + + server 10.244.0.14:80; + keepAlive 16; +} +``` + +--- + ## Further reading - [Custom policies]({{< ref "/ngf/overview/custom-policies.md" >}}): learn about how NGINX Gateway Fabric custom policies work. From eb13bcaa651be34214f804a58d900c87445d9687 Mon Sep 17 00:00:00 2001 From: Sidharath Bansal <60166938+SidharathBansal@users.noreply.github.com> Date: Tue, 21 Jul 2026 18:18:08 +0530 Subject: [PATCH 2/3] Update content/ngf/traffic-management/upstream-settings.md Co-authored-by: yar --- content/ngf/traffic-management/upstream-settings.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/ngf/traffic-management/upstream-settings.md b/content/ngf/traffic-management/upstream-settings.md index 4443b863c9..7cf7ea94d2 100644 --- a/content/ngf/traffic-management/upstream-settings.md +++ b/content/ngf/traffic-management/upstream-settings.md @@ -633,7 +633,7 @@ kubectl exec -it deployments/gateway-nginx -- nginx -T You should see a single `server` in the `coffee` upstream set to the Service ClusterIP and port (`10.244.0.14` is the ClusterIP in this example): -```text +```nginx upstream default_coffee_80 { random two least_conn; zone default_coffee_80 512k; From e732fef28a3c4fa1a84a02bee0044cdcb7d79d94 Mon Sep 17 00:00:00 2001 From: Sidharath Bansal <60166938+SidharathBansal@users.noreply.github.com> Date: Tue, 21 Jul 2026 18:18:15 +0530 Subject: [PATCH 3/3] Update content/ngf/traffic-management/upstream-settings.md Co-authored-by: yar --- content/ngf/traffic-management/upstream-settings.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/ngf/traffic-management/upstream-settings.md b/content/ngf/traffic-management/upstream-settings.md index 7cf7ea94d2..e83bddc9a8 100644 --- a/content/ngf/traffic-management/upstream-settings.md +++ b/content/ngf/traffic-management/upstream-settings.md @@ -639,7 +639,7 @@ upstream default_coffee_80 { zone default_coffee_80 512k; server 10.244.0.14:80; - keepAlive 16; + keepalive 16; } ```