From 16582975bfba2122ead23662776b65d357f1edbe Mon Sep 17 00:00:00 2001 From: Sidharath Bansal <60166938+SidharathBansal@users.noreply.github.com> Date: Fri, 10 Jul 2026 23:01:35 +0530 Subject: [PATCH 1/3] Add useClusterIP section to data plane configuration guide Document the new NginxProxy useClusterIP field, which routes upstream traffic to a Service's ClusterIP instead of individual Pod IPs to reduce NGINX reloads on backend Pod churn. Notes the fallback cases (headless, ExternalName, L4/stream) and the default value. --- .../ngf/how-to/data-plane-configuration.md | 29 +++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/content/ngf/how-to/data-plane-configuration.md b/content/ngf/how-to/data-plane-configuration.md index 6416bce74b..2ac8724122 100644 --- a/content/ngf/how-to/data-plane-configuration.md +++ b/content/ngf/how-to/data-plane-configuration.md @@ -384,6 +384,35 @@ EOF --- +## 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. This means that every time the backend Pods change (for example, during a scale up, scale down, or rollout), NGINX must reload to pick up the new set of endpoints. + +Setting `useClusterIP` to `true` in the `NginxProxy` resource configures NGINX to route to the Service's ClusterIP and port instead of the individual Pod IPs. The upstream then contains a single server (the Service VIP), and NGINX no longer needs to reload when the backend Pods churn. This is also useful for service mesh compatibility and for controllers or operators that require traffic to traverse the Service VIP. + +The following command creates an `NginxProxy` resource that enables `useClusterIP`: + +```yaml +kubectl apply -f - <}}) for the full list of options. + +--- + ## Configure infrastructure-related settings You can configure deployment and service settings for all data plane instances by editing the `NginxProxy` resource at the Gateway or GatewayClass level. These settings can also be specified under the `nginx` section in the Helm values file. You can edit things such as replicas, pod scheduling options, container resource limits, extra volume mounts, service types and load balancer settings. From 12406d082ec07e7d4288e3b8e38e702ce7e4adb4 Mon Sep 17 00:00:00 2001 From: Sidharath Bansal <60166938+SidharathBansal@users.noreply.github.com> Date: Tue, 14 Jul 2026 21:03:18 +0530 Subject: [PATCH 2/3] NGF: note load balancing caveat for useClusterIP Enabling useClusterIP makes the upstream a single Service VIP, so NGINX load balancing across Pods no longer applies; the Kubernetes Service handles load balancing instead. --- content/ngf/how-to/data-plane-configuration.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/content/ngf/how-to/data-plane-configuration.md b/content/ngf/how-to/data-plane-configuration.md index 2ac8724122..a6b2a4e7b8 100644 --- a/content/ngf/how-to/data-plane-configuration.md +++ b/content/ngf/how-to/data-plane-configuration.md @@ -390,6 +390,8 @@ By default, NGINX Gateway Fabric resolves each backend Service to its individual Setting `useClusterIP` to `true` in the `NginxProxy` resource configures NGINX to route to the Service's ClusterIP and port instead of the individual Pod IPs. The upstream then contains a single server (the Service VIP), and NGINX no longer needs to reload when the backend Pods churn. This is also useful for service mesh compatibility and for controllers or operators that require traffic to traverse the Service VIP. +{{< 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 NGINX load balancing settings such as those in an `UpstreamSettingsPolicy` no longer apply to that Service. {{< /call-out >}} + The following command creates an `NginxProxy` resource that enables `useClusterIP`: ```yaml From 1968c5e89a4c871503e4ec0981e3f26bee9086e1 Mon Sep 17 00:00:00 2001 From: Sidharath Bansal <60166938+SidharathBansal@users.noreply.github.com> Date: Wed, 15 Jul 2026 02:07:02 +0530 Subject: [PATCH 3/3] Update content/ngf/how-to/data-plane-configuration.md Co-authored-by: Saloni Choudhary <146118978+salonichf5@users.noreply.github.com> --- content/ngf/how-to/data-plane-configuration.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/content/ngf/how-to/data-plane-configuration.md b/content/ngf/how-to/data-plane-configuration.md index a6b2a4e7b8..76abffe0e0 100644 --- a/content/ngf/how-to/data-plane-configuration.md +++ b/content/ngf/how-to/data-plane-configuration.md @@ -406,10 +406,10 @@ EOF ``` `useClusterIP` applies only when the target Service has a ClusterIP. The following cases fall back to the default Pod IP resolution: - -- Headless Services (`ClusterIP: None`). +- Headless Services (ClusterIP: None). - ExternalName Services. -- Layer 4 (TCPRoute/UDPRoute) stream upstreams, which are not affected by this setting. + +Layer 4 (TCPRoute/UDPRoute) stream upstreams are unaffected by this setting, since it does not apply to L4 traffic. If not specified, `useClusterIP` defaults to `false`. As with other `NginxProxy` fields, it can be set on the GatewayClass to apply globally, or on a Gateway to override the GatewayClass value. See the [Merging Semantics](#merging-semantics) section for details, and the `NginxProxy spec` in the [API reference]({{< ref "/ngf/reference/api.md" >}}) for the full list of options.