Skip to content

Add auto IP family detection for LoadBalancer Service - #5530

Merged
sjberman merged 12 commits into
nginx:mainfrom
tanayarun:feat/auto-ip-family-detection
Jul 27, 2026
Merged

sjberman merged 12 commits into
nginx:mainfrom
tanayarun:feat/auto-ip-family-detection

Conversation

@tanayarun

@tanayarun tanayarun commented Jul 1, 2026 •

Copy link
Copy Markdown
Contributor

Proposed changes

Problem: NGF always sets ipFamilyPolicy: PreferDualStack on the generated
LoadBalancer Service regardless of cluster capability, causing unnecessary
error noise in MetalLB on IPv4 only clusters.

Solution: Added a new IPFamilyType value auto (now the default, replacing
dual) that detects the cluster's IP family at startup by reading
spec.ipFamilies from the kubernetes Service in kube-system. The detected
value is stored on NginxProvisioner and used when ipFamily is auto.
Explicit ipFamily: dual/ipv4/ipv6 values are always respected and override
auto-detection.

Testing: Added TestDetectClusterIPFamily covering IPv4-only, dual-stack, and
not found fallback cases. Updated TestSetIPFamily to cover the auto path.
All existing unit tests pass.

Closes #5488

Checklist

  • I have read the CONTRIBUTING doc
  • I have added tests that prove my fix is effective or that my feature works
  • I have checked that all unit tests pass after adding my changes
  • I have updated necessary documentation
  • I have rebased my branch onto main
  • I will ensure my PR is targeting the main branch and pulling from my branch from my own fork

Release notes

Added auto IP family detection for the LoadBalancer Service. NginxProxy
ipFamily now defaults to "auto", which detects the cluster's IP family
at startup instead of always using PreferDualStack.

@nginx-bot

nginx-bot Bot commented Jul 1, 2026

Copy link
Copy Markdown

Hi @tanayarun! Welcome to the project! 🎉

Thanks for opening this pull request!
Be sure to check out our Contributing Guidelines while you wait for someone on the team to review this.

@github-actions

github-actions Bot commented Jul 1, 2026 •

Copy link
Copy Markdown
Contributor

✅ All required contributors have signed the F5 CLA for this PR. Thank you!
Posted by the CLA Assistant Lite bot.

@github-actions github-actions Bot added the enhancement New feature or request label Jul 1, 2026
@tanayarun

Copy link
Copy Markdown
Contributor Author

I have hereby read the F5 CLA and agree to its terms

@tanayarun
tanayarun force-pushed the feat/auto-ip-family-detection branch from b6c4496 to 7c8a623 Compare July 2, 2026 03:53
@shaun-nx

shaun-nx commented Jul 2, 2026

Copy link
Copy Markdown
Contributor

Thanks again @tanayarun for this contribution. I'll give this PR a full review today.

@shaun-nx

shaun-nx commented Jul 2, 2026

Copy link
Copy Markdown
Contributor

Hi @tanayarun

After going through the PR, I think we might be able to simplify the approach.

Right now, the new detectClusterIPFamily function will set the appropriate ipFamily assuming it can read it from default/kubernetes. This is correct, and will ensure still default back to PreferDualStack if it can't get this data from the service.

With that, we don't really need auto as a new IPFamilyType in the NginxProxy resource. Instead, we can assert the new auto detection logic when the user does not set IpFamily in the NginxProxy resource (i.e. *IpFamily = nil).

So, in nginxproxy_types.go, this would look like this:

// IPFamily specifies the IP family to be used by the NGINX.
// If not set, NGF inspectes the `default/kubernetes` service's `ipFamily` field at startup
// to obtain the IP family of the cluster and configure NGINX accordingly.
//
// +optional
IPFamily *IPFamilyType `json:"ipFamily,omitempty"`

Your new function, detectClusterIPFamily, will remain the same, and the existing setIPFamily function, would be updated to return the auto-detected IPFamily only when the user does not set their own value.

This would look like this in internal/controller/provisioner/objects.go:

func (p *NginxProvisioner) setIPFamily(nProxyCfg *graph.EffectiveNginxProxy, svc *corev1.Service) {
	// If the user explicitly set ipFamily, use that
	// Otherwise use auto-detected ipFamily from cluster
	ipFamily := p.clusterIPFamily
	if nProxyCfg != nil && nProxyCfg.IPFamily != nil {
		ipFamily = *nProxyCfg.IPFamily
	}
...

Let me know what you think too, and if anything I said make sense.

@tanayarun

Copy link
Copy Markdown
Contributor Author

That makes sense and is cleaner, using nil as the signal for auto detection avoids adding a new API value. I'll update the code accordingly. Thanks for this, I was not able to come up with this approach.

@tanayarun

Copy link
Copy Markdown
Contributor Author

Implemented as suggested.

@shaun-nx

shaun-nx commented Jul 2, 2026

Copy link
Copy Markdown
Contributor

Implemented as suggested.

Thanks @tanayarun I'll run some local tests on this now.
Also, can you make sure to run the command make generate-crds in the root directory of this project?
Since we're making changes to the NginxProxy resource, this command will make sure the CRD will be installed with these new settings for IpFamily

@github-project-automation github-project-automation Bot moved this from 🆕 New to 🏗 In Progress in NGINX Gateway Fabric Jul 2, 2026
@tanayarun

Copy link
Copy Markdown
Contributor Author

Hey @shaun-nx.
Fixed: updated detectClusterIPFamily to use client.Reader and passing
mgr.GetAPIReader() instead of mgr.GetClient(). Makes sense since this
runs before mgr.Start() so the cache isn't populated yet.

Unfortunately I don't have access to a MetalLB cluster to test end-to-end,
but the unit tests pass and the logic matches what you verified locally,
and also thanks for all the review and suggestions, learning a lot.

@shaun-nx

shaun-nx commented Jul 3, 2026

Copy link
Copy Markdown
Contributor

and also thanks for all the review and suggestions, learning a lot.

No problem at all @tanayarun !
If you don't mind me asking, did you find that our contributing guidelines to be helpful when making this PR? For new contributors, we want to make sure that this guide helps you get up and running as best as possible. If you think there are any gaps in this guide, we'd love you know. Given that we made it, we can sometime be bias 😅

@tanayarun

Copy link
Copy Markdown
Contributor Author

Yes, the contributing guide were really helpful.
I Loved the code review pyramid illustration :)
Development guide is awesome, specially architecture.
thanks.

@shaun-nx

shaun-nx commented Jul 3, 2026

Copy link
Copy Markdown
Contributor

Changes looks to be good from what I've tested. Nice work @tanayarun !
Before we go forward, can you add unit tests to provisioner_test.go? Since we added a new field to EffectiveNginxProxy, we will want to test that the clusterIPFamily value in the NginxProvisioner struct is assigned correctly.

Also, aside from making the new test, the existing TestNewNginxProvisioner test should assert that provisioner.clusterIPFamily is Dual stack. That test does not create any fake resources like services. So in this case, it should default to Dual.

If you add this line to the end of TestNewNginxProvisioner, it should work:

g.Expect(provisioner.clusterIPFamily).To(Equal(ngfAPIv1alpha2.Dual))

@tanayarun

Copy link
Copy Markdown
Contributor Author

I added the assertion to TestNewNginxProvisioner as suggested. but for the new test, the detection logic is already thoroughly covered in TestDetectClusterIPFamily in objects_test.go (IPv4-only, IPv6-only, dual-stack, and not found fallback cases). The wiring between NewNginxProvisioner and detectClusterIPFamily is verified by the new assertion in TestNewNginxProvisioner. Adding another test in provisioner_test.go would duplicate that coverage.
Am I correct or missing something ?

@shaun-nx

shaun-nx commented Jul 7, 2026

Copy link
Copy Markdown
Contributor

I added the assertion to TestNewNginxProvisioner as suggested. but for the new test, the detection logic is already thoroughly covered in TestDetectClusterIPFamily in objects_test.go (IPv4-only, IPv6-only, dual-stack, and not found fallback cases). The wiring between NewNginxProvisioner and detectClusterIPFamily is verified by the new assertion in TestNewNginxProvisioner. Adding another test in provisioner_test.go would duplicate that coverage. Am I correct or missing something ?

Ah yeah, that's a good point. I was worried that we needed a test which created the kubernetes service, but I see your test does that too. So that should be fine.

@shaun-nx

shaun-nx commented Jul 7, 2026

Copy link
Copy Markdown
Contributor

Let me know when you've pushed the changes with the new test assertion. I'll approve the change then. Nice work 😄

@tanayarun

Copy link
Copy Markdown
Contributor Author

Sorry for the delay, I will do it asap.

@tanayarun
tanayarun force-pushed the feat/auto-ip-family-detection branch from 32bab6b to 94bcd01 Compare July 11, 2026 05:05
@tanayarun

Copy link
Copy Markdown
Contributor Author

Hey, @shaun-nx I have pushed the changes !

@tanayarun
tanayarun force-pushed the feat/auto-ip-family-detection branch from 50e0c4b to 3b7c556 Compare July 11, 2026 05:10
@salonichf5 salonichf5 changed the title NGF: Add auto IP family detection for LoadBalancer Service Add auto IP family detection for LoadBalancer Service Jul 14, 2026
@tanayarun

Copy link
Copy Markdown
Contributor Author

Hey @shaun-nx , I have been working on this and I am almost finished, I will push the changes soon

@tanayarun
tanayarun force-pushed the feat/auto-ip-family-detection branch 2 times, most recently from 01969bf to ff30a6c Compare July 18, 2026 14:20
@tanayarun

Copy link
Copy Markdown
Contributor Author

Hey @shaun-nx.
done, threaded clusterIPFamily from NginxProvisioner through
BuildConfiguration into buildBaseHTTPConfig. When np.IPFamily is nil
(auto detect case), it now uses the cluster-detected value instead of
hardcoding Dual.
let me know if I am wrong somewhere and I will make changes according to it.

@sjberman sjberman moved this from 🏗 In Progress to External Pull Requests in NGINX Gateway Fabric Jul 21, 2026

@shaun-nx shaun-nx left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just finished re testing this locally. Everything looks to be working find.
Great job with this @tanayarun !

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

@tanayarun
tanayarun force-pushed the feat/auto-ip-family-detection branch from e00dda9 to 2cdb696 Compare July 24, 2026 08:56
@tanayarun
tanayarun force-pushed the feat/auto-ip-family-detection branch from 72f4d38 to 726ad46 Compare July 25, 2026 11:25
@sjberman
sjberman enabled auto-merge (squash) July 27, 2026 16:14
@sjberman
sjberman merged commit 5c54b53 into nginx:main Jul 27, 2026
42 checks passed
@github-project-automation github-project-automation Bot moved this from External Pull Requests to ✅ Done in NGINX Gateway Fabric Jul 27, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

Status: ✅ Done

Development

Successfully merging this pull request may close these issues.

NGINX Gateway Fabric creates PreferDualStack Service warning in IPv4-only MetalLB environments (non-blocking error noise)

4 participants