From c9dec6168283b4bf452bb28739f947aea79c341f 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   | 109 +++++++++++++++++-
 1 file changed, 106 insertions(+), 3 deletions(-)

diff --git a/content/ngf/traffic-management/upstream-settings.md b/content/ngf/traffic-management/upstream-settings.md
index 29c3c54174..2445341941 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
 ```
 
@@ -513,7 +513,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 +527,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 +565,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