CORE#12191: Adds clarity on Maglev doc, surrounding NodePorts and type:LoadBalancer #2455

aaaaaaaalex · 2026-01-09T18:25:34Z

Product Version(s):
OSS and EE next

Issue

Link to docs preview:

SME review:

An SME has approved this change.

DOCS review:

A member of the docs team has approved this change.

Additional information:

Merge checklist:

Deploy preview inspected wherever changes were made
Build completed successfully
Test have passed

netlify · 2026-01-09T18:25:39Z

✅ Deploy Preview for calico-docs-preview-next ready!

Name	Link
🔨 Latest commit	`113106b`
🔍 Latest deploy log	https://app.netlify.com/projects/calico-docs-preview-next/deploys/6970c44cfddf4c0007da06f2
😎 Deploy Preview	https://deploy-preview-2455--calico-docs-preview-next.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

netlify · 2026-01-09T18:25:42Z

❌ Deploy Preview for tigera failed. Why did it fail? →

Built without sensitive environment variables

Name	Link
🔨 Latest commit	`113106b`
🔍 Latest deploy log	https://app.netlify.com/projects/tigera/deploys/6970c44c337ac100089e95a7

Copilot

Pull request overview

This PR improves the Maglev load balancing documentation by clarifying NodePort limitations and adding guidance on using Maglev with LoadBalancer IPAM. The changes address confusion around when Maglev functionality is useful and how to properly configure services to leverage it.

Changes:

Clarified that Maglev doesn't work with NodePorts specifically (not just NodePort-type services)
Added new section explaining how to use Maglev with LoadBalancer IPAM and BGP advertisement
Updated prerequisites to emphasize the need for external IP routing capability

Copilot · 2026-01-09T18:26:12Z

calico-enterprise/networking/configuring/add-maglev-load-balancing.mdx

+## Use Maglev Alongside $[prodname] LoadBalancer IPAM
+
+Maglev can be enabled on services with `type: LoadBalancer`, and $[prodname] can be configured to allocate
+load balancer VIPs. See the guide to [enable LoadBalancer IPAM](networking/ipam/service-loadbalancer).


The relative link path is incorrect. Based on the file's location in calico-enterprise/networking/configuring/, this link should start with ../../ to navigate up to the root, or use an absolute path starting with /calico-enterprise/. The current path networking/ipam/service-loadbalancer will not resolve correctly from this file's location.

Suggested change

load balancer VIPs. See the guide to [enable LoadBalancer IPAM](networking/ipam/service-loadbalancer).

load balancer VIPs. See the guide to [enable LoadBalancer IPAM](../../networking/ipam/service-loadbalancer).

Copilot · 2026-01-09T18:26:12Z

calico-enterprise/networking/configuring/add-maglev-load-balancing.mdx

 ## Prerequisites

-* Your cluster uses the eBPF data plane with [direct server return mode](../../operations/ebpf/enabling-ebpf.mdx#try-out-direct-server-return-mode).
+* Your cluster uses the eBPF data plane with [direct server return mode](../../../operations/ebpf/enabling-ebpf#try-out-direct-server-return-mode).


The relative link path appears incorrect. The file is in calico-enterprise/networking/configuring/, so the path ../../../operations/ebpf/enabling-ebpf would navigate too far up (3 levels up would go above the calico-enterprise directory). This should be ../../operations/ebpf/enabling-ebpf.mdx#try-out-direct-server-return-mode to correctly reference the file.

Suggested change

* Your cluster uses the eBPF data plane with [direct server return mode](../../../operations/ebpf/enabling-ebpf#try-out-direct-server-return-mode).

* Your cluster uses the eBPF data plane with [direct server return mode](../../operations/ebpf/enabling-ebpf.mdx#try-out-direct-server-return-mode).

@ctauchen based on our chat, I think Copilot is wrong here, right?

No, I think the suggestion here is exactly right. If you're referring to the CE doc, you need to go up two levels, and the mdx file ref is preferred.

calico-enterprise/networking/configuring/add-maglev-load-balancing.mdx

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

aaaaaaaalex · 2026-01-21T13:00:22Z

Prior to merge, I'd also like to copy this doc to the OSS equivalent

ctauchen

A few nits, otherwise LGTM.

ctauchen · 2026-01-14T15:46:31Z

calico-enterprise/networking/configuring/add-maglev-load-balancing.mdx

 description: Add Maglev load balancing to a Kubernetes service.
 ---

+


ctauchen · 2026-01-14T15:50:06Z

calico-enterprise/networking/configuring/add-maglev-load-balancing.mdx

 ## Prerequisites

-* Your cluster uses the eBPF data plane with [direct server return mode](../../operations/ebpf/enabling-ebpf.mdx#try-out-direct-server-return-mode).
+* Your cluster uses the eBPF data plane with [direct server return mode](../../../operations/ebpf/enabling-ebpf#try-out-direct-server-return-mode).


No, I think the suggestion here is exactly right. If you're referring to the CE doc, you need to go up two levels, and the mdx file ref is preferred.

ctauchen · 2026-01-21T16:42:27Z

calico-enterprise/networking/configuring/add-maglev-load-balancing.mdx

 ## Prerequisites

-* Your cluster uses the eBPF data plane with [direct server return mode](../../operations/ebpf/enabling-ebpf.mdx#try-out-direct-server-return-mode).
+* Your cluster uses the eBPF data plane with [direct server return mode](../../../operations/ebpf/enabling-ebpf#try-out-direct-server-return-mode).


Suggested change

* Your cluster uses the eBPF data plane with [direct server return mode](../../../operations/ebpf/enabling-ebpf#try-out-direct-server-return-mode).

* Your cluster uses the eBPF data plane with [direct server return mode](../../operations/ebpf/enabling-ebpf.mdx#try-out-direct-server-return-mode).

ctauchen · 2026-01-21T16:43:13Z

calico-enterprise/networking/configuring/add-maglev-load-balancing.mdx



-To verify that $[prodname] has configured Maglev load balancing for the service, check the logs from any `calico-node` pod for the string `Wrote Maglev` in reference to your service.
+## Optional: Verify that $[prodname] has configured Maglev load balancing for the service


I'd leave out the optional. Verification is always optional, but we never say it.

ctauchen · 2026-01-21T16:43:35Z

calico-enterprise/networking/configuring/add-maglev-load-balancing.mdx

-```bash title='Example log query'
-kubectl -n calico-system logs calico-node-7kltn | grep --ignore-case 'Wrote Maglev'
+```bash title='Example NAT table dump'
+kubectl -n calico-system exec <pod name> -- calico-node -bpf nat dump


Suggested change

kubectl -n calico-system exec <pod name> -- calico-node -bpf nat dump

kubectl -n calico-system exec <pod-name> -- calico-node -bpf nat dump

ctauchen · 2026-01-21T16:43:45Z

calico-enterprise/networking/configuring/add-maglev-load-balancing.mdx


-```bash title='Example output'
-2025-10-28 15:30:53.091 [INFO][75] felix/syncer.go 893: Wrote Maglev service backends to LUT service=default/svc:maglev-port
+Replace `<pod name>` with the name of any calico-node pod.


Suggested change

Replace `<pod name>` with the name of any calico-node pod.

Replace `<pod-name>` with the name of any calico-node pod.

Copilot AI review requested due to automatic review settings January 9, 2026 18:25

aaaaaaaalex requested a review from a team as a code owner January 9, 2026 18:25

Copilot AI reviewed Jan 9, 2026

View reviewed changes

aaaaaaaalex changed the title ~~CORE#12191: Adds clarity on Maglev doc, surrounding NodePorts and type:LoadBalancer~~ DRAFT CORE#12191: Adds clarity on Maglev doc, surrounding NodePorts and type:LoadBalancer Jan 9, 2026

aaaaaaaalex marked this pull request as draft January 9, 2026 18:27

aaaaaaaalex force-pushed the maglev-doc-lb-support branch from ffea0db to 9674b88 Compare January 12, 2026 10:41

adds clarity on Maglev with type:LoadBalancer

13edc4f

aaaaaaaalex force-pushed the maglev-doc-lb-support branch from 9674b88 to 13edc4f Compare January 14, 2026 13:28

aaaaaaaalex changed the title ~~DRAFT CORE#12191: Adds clarity on Maglev doc, surrounding NodePorts and type:LoadBalancer~~ CORE#12191: Adds clarity on Maglev doc, surrounding NodePorts and type:LoadBalancer Jan 14, 2026

aaaaaaaalex marked this pull request as ready for review January 14, 2026 13:29

aaaaaaaalex and others added 5 commits January 14, 2026 13:32

Apply suggestions from Copilot code review

2e905ca

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

simplify how-to, add context at top of doc

936c317

experiment: change syntax of noderunning to satisfy compiler

da60778

experiment: adjust a relative doc link

f83539b

[sausage commit] adjust overview wording, adjust URL, adjust sample cmd

7b632e0

aaaaaaaalex force-pushed the maglev-doc-lb-support branch from c116ed5 to 7b632e0 Compare January 21, 2026 11:54

aaaaaaaalex added 2 commits January 21, 2026 11:59

wrap <> string in backticks

984f76a

fix bpf link

113106b

ctauchen reviewed Jan 21, 2026

View reviewed changes

	load balancer VIPs. See the guide to [enable LoadBalancer IPAM](networking/ipam/service-loadbalancer).
	load balancer VIPs. See the guide to [enable LoadBalancer IPAM](../../networking/ipam/service-loadbalancer).

	* Your cluster uses the eBPF data plane with [direct server return mode](../../../operations/ebpf/enabling-ebpf#try-out-direct-server-return-mode).
	* Your cluster uses the eBPF data plane with [direct server return mode](../../operations/ebpf/enabling-ebpf.mdx#try-out-direct-server-return-mode).

		description: Add Maglev load balancing to a Kubernetes service.
		---



		To verify that $[prodname] has configured Maglev load balancing for the service, check the logs from any `calico-node` pod for the string `Wrote Maglev` in reference to your service.
		## Optional: Verify that $[prodname] has configured Maglev load balancing for the service

	kubectl -n calico-system exec <pod name> -- calico-node -bpf nat dump
	kubectl -n calico-system exec <pod-name> -- calico-node -bpf nat dump

	Replace `<pod name>` with the name of any calico-node pod.
	Replace `<pod-name>` with the name of any calico-node pod.

CORE#12191: Adds clarity on Maglev doc, surrounding NodePorts and type:LoadBalancer #2455

Are you sure you want to change the base?

CORE#12191: Adds clarity on Maglev doc, surrounding NodePorts and type:LoadBalancer #2455

Conversation

aaaaaaaalex commented Jan 9, 2026

Uh oh!

netlify bot commented Jan 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for calico-docs-preview-next ready!

Uh oh!

netlify bot commented Jan 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

❌ Deploy Preview for tigera failed. Why did it fail? →

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Jan 9, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 9, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

aaaaaaaalex commented Jan 21, 2026

Uh oh!

ctauchen left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

netlify bot commented Jan 9, 2026 •

edited

Loading

netlify bot commented Jan 9, 2026 •

edited

Loading