From cb375a22e2d1fdc3b1c370429df4427faa155d8e Mon Sep 17 00:00:00 2001
From: Ben Jee <b.jee@f5.com>
Date: Thu, 28 May 2026 14:58:49 -0700
Subject: [PATCH] Update USP doc for routing to clusterIPs

---
 .../traffic-management/upstream-settings.md   | 110 +++++++++++++++++-
 1 file changed, 107 insertions(+), 3 deletions(-)

diff --git a/content/ngf/traffic-management/upstream-settings.md b/content/ngf/traffic-management/upstream-settings.md
index 23c53b567..0448909ff 100644
--- a/content/ngf/traffic-management/upstream-settings.md
+++ b/content/ngf/traffic-management/upstream-settings.md
@@ -299,7 +299,7 @@ spec:
     kind: Service
     name: tea
   loadBalancingMethod: "hash consistent"
-  hashMethodKey: "$upstream_addr"
+  hashMethodKey: "\$upstream_addr"
 EOF
 ```
 
@@ -357,6 +357,7 @@ upstream default_tea_80 {
 
 {{< call-out "note" >}}
 NGINX Open Source supports the following load-balancing methods: `round_robin`, `least_conn`, `ip_hash`, `hash`, `hash consistent`, `random`, `random two`, and `random two least_conn`.
+
 NGINX Plus supports all of the methods available in NGINX Open Source, and adds the following methods: `random two least_time=header`, `random two least_time=last_byte`, `least_time header`, `least_time last_byte`, `least_time header inflight`, and `least_time last_byte inflight`.
 {{< /call-out >}}
 
@@ -513,7 +514,7 @@ kubectl apply -f - <<EOF
 apiVersion: gateway.nginx.org/v1alpha1
 kind: UpstreamSettingsPolicy
 metadata:
-  name: upstream-unset-keepAlive
+  name: upstream-unset-keepalive
 spec:
   targetRefs:
   - group: core
@@ -527,7 +528,7 @@ EOF
 Verify that the `UpstreamSettingsPolicy` is Accepted:
 
 ```shell
-kubectl describe upstreamsettingspolicies.gateway.nginx.org upstream-unset-keepAlive
+kubectl describe upstreamsettingspolicies.gateway.nginx.org upstream-unset-keepalive
 ```
 
 You should see the following status:
@@ -565,6 +566,109 @@ upstream default_tea_80 {
 }
 ```
 
+## Enable routing to Service ClusterIPs
+
+The ability to configure NGINX to route to the Service ClusterIP and port instead of individual Pod IPs can be useful in service mesh scenarios or when working with other Kubernetes controllers/operators that require traffic to flow to the Service IP address.
+
+View the IP address of the `coffee` backend pod and verify it matches the IP address in the `coffee` upstream:
+
+```shell
+kubectl get endpoints coffee
+```
+
+```text
+NAME     ENDPOINTS         AGE
+coffee   10.244.0.8:8080   13m
+```
+
+```shell
+kubectl exec -it deployments/gateway-nginx -- nginx -T
+```
+
+```text
+upstream default_coffee_80 {
+    random two least_conn;
+    zone default_coffee_80 1m;
+
+
+    server 10.244.0.8:8080;
+    keepalive 32;
+}
+```
+
+The following example creates an `UpstreamSettingsPolicy` that configures NGINX to route to the coffee Service ClusterIP instead of the individual backend Pod IPs by using the `useClusterIP` field:
+
+```yaml
+kubectl apply -f - <<EOF
+apiVersion: gateway.nginx.org/v1alpha1
+kind: UpstreamSettingsPolicy
+metadata:
+  name: upstream-clusterip
+spec:
+  targetRefs:
+  - group: core
+    kind: Service
+    name: coffee
+  useClusterIP: true
+EOF
+```
+
+Verify that the `UpstreamSettingsPolicy` is Accepted:
+
+```shell
+kubectl describe upstreamsettingspolicies.gateway.nginx.org upstream-keepalives
+```
+
+You should see the following status:
+
+```text
+Status:
+  Ancestors:
+    Ancestor Ref:
+      Group:      gateway.networking.k8s.io
+      Kind:       Gateway
+      Name:       gateway
+      Namespace:  default
+    Conditions:
+      Last Transition Time:  2026-05-28T21:49:20Z
+      Message:               The Policy is accepted
+      Observed Generation:   1
+      Reason:                Accepted
+      Status:                True
+      Type:                  Accepted
+    Controller Name:         gateway.nginx.org/nginx-gateway-controller
+Events:                      <none>
+```
+
+{{< call-out "note" >}}This setting applies only when the target Service has a ClusterIP. For headless Services (ClusterIP: None) and ExternalName Services, normal endpoint resolution is used instead. Additionally, this setting is also not applied to L4/stream upstreams.{{< /call-out >}}
+
+View the IP address of the `coffee` Service and verify it matches the IP address in the `coffee` upstream:
+
+```shell
+kubectl get service coffee
+```
+
+```text
+NAME     TYPE        CLUSTER-IP    EXTERNAL-IP   PORT(S)   AGE
+coffee   ClusterIP   10.96.23.26   <none>        80/TCP    16m
+```
+
+
+```shell
+kubectl exec -it deployments/gateway-nginx -- nginx -T
+```
+
+```text
+upstream default_coffee_80 {
+    random two least_conn;
+    zone default_coffee_80 1m;
+
+
+    server 10.96.23.26:80;
+    keepalive 32;
+}
+```
+
 ---
 
 ## Further reading