Skip to content

NGF: document NginxProxy useClusterIP setting #2116

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
SidharathBansal wants to merge 3 commits into
base: ngf-release-2.7
Choose a base branch
from
Open

NGF: document NginxProxy useClusterIP setting #2116

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
1658297
Add useClusterIP section to data plane configuration guide
SidharathBansal Jul 10, 2026
12406d0
NGF: note load balancing caveat for useClusterIP
SidharathBansal Jul 14, 2026
1968c5e
Update content/ngf/how-to/data-plane-configuration.md
SidharathBansal Jul 14, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 31 additions & 0 deletions content/ngf/how-to/data-plane-configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -384,6 +384,37 @@ 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.

{{< 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
kubectl apply -f - <<EOF
apiVersion: gateway.nginx.org/v1alpha2
kind: NginxProxy
metadata:
name: ngf-proxy-config
spec:
useClusterIP: true
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).
- ExternalName Services.

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.

---

## 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.
Expand Down
Loading