NGF: document NginxProxy useClusterIP setting#2116
Conversation
github-actions
Bot
added
documentation
|
can we target this to release branch for ngf-release-2.7 |
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.
d65a783 to
1658297
Compare
|
Thanks @salonichf5! I've switched the base to |
|
I think we should mention the downside of using this is you lose out on NGINX's load balancing ability, and instead you end up just using k8s default Service load balancing. |
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.
|
Thanks @sjberman! Added a note calling out the trade-off: enabling |
salonichf5
left a comment
salonichf5
left a comment
There was a problem hiding this comment.
overall looks good, just a small comment
Co-authored-by: Saloni Choudhary <146118978+salonichf5@users.noreply.github.com>
|
|
||
| ## 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. |
There was a problem hiding this comment.
I wonder if we mention the ability to do this per upstream with the UpstreamSettingsPolicy, while also mentioning the global way to do it.
4 participants
Proposed changes
Problem: NGINX Gateway Fabric is adding a
useClusterIPfield to theNginxProxyresource (nginx/nginx-gateway-fabric#5557, resolving nginx/nginx-gateway-fabric#5554). The data plane configuration guide does not yet document it.Solution: Add a "Route upstream traffic to the Service ClusterIP" section to
content/ngf/how-to/data-plane-configuration.md. It explains what the setting does and why (fewer NGINX reloads on backend Pod churn, service-mesh compatibility), gives anNginxProxyYAML example, and documents the fallback cases (headless Services, ExternalName Services, L4/stream upstreams) and the default value.Testing: Rendered/reviewed the Markdown locally; no functional changes.
Related: nginx/nginx-gateway-fabric#5557, nginx/nginx-gateway-fabric#5554