Document the netkit attach mechanism and the downgrade path - #2923
Document the netkit attach mechanism and the downgrade path#2923tomastigera wants to merge 2 commits into
Conversation
✅ Deploy Preview for calico-docs-preview-next ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
✅ Deploy Preview succeeded!Built without sensitive environment variables
To edit notification comments on pull requests, go to your Netlify project configuration. |
There was a problem hiding this comment.
Pull request overview
This PR updates the Calico “next” eBPF enablement documentation to explain how netkit pod interfaces are attached/programmed by the eBPF dataplane, and to document a safe downgrade path to releases that don’t support netkit attachment (to avoid leaving stale netkit programs attached after downgrade).
Changes:
- Corrects the description of what happens to existing netkit pod interfaces when switching
linuxPodInterfaceTypeback toVeth. - Adds an “Attach mechanism” subsection describing
bpfAttachTypebehaviors for netkit vs non-netkit interfaces. - Adds a “Downgrading to a release without netkit support” procedure describing how to switch attachment before downgrading.
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
| The `bpfAttachType` field of the `FelixConfiguration` selects how the eBPF data plane attaches its programs: | ||
|
|
||
| * `Netkit` (default) — netkit attachment on netkit interfaces, TCX on every other interface. | ||
| * `TCX` — TCX on every interface, including netkit interfaces. | ||
| * `TC` — the legacy qdisc-based attachment on every interface. Pod bandwidth QoS annotations are not supported with `TC`. |
There was a problem hiding this comment.
Claude: Correct that they disagree today, but _includes/components/FelixConfig/config-params.json is generated, not authored here — scripts/update-felix-config.sh syncs it from the product repos. Hand-editing it would be overwritten on the next sync.
The Netkit value is added by projectcalico/calico#13462, which updates the generated source. So the reference picks it up on the next sync after that merges, and this PR should not merge before it.
| ``` | ||
|
|
||
| Existing pods keep their netkit interfaces, but the eBPF data plane treats those as veth (programs attach via TC/TCX, the same path used for actual veth interfaces). | ||
| Existing pods keep their netkit interfaces, and the eBPF data plane keeps driving those through netkit attachment. |
There was a problem hiding this comment.
Claude: Good catch — fixed. The sentence now reads "…keeps driving those through netkit attachment unless bpfAttachType says otherwise (see below)."
The netkit section covered how to get netkit interfaces but not how the eBPF data plane attaches to them, so there was no documented way off netkit attachment. A release that predates it cannot remove netkit programs, so downgrading a node directly leaves the old programs attached and enforcing a stale policy alongside the downgraded Felix. Describe the bpfAttachType values and note that TCX or TC also migrates existing netkit interfaces, then give the downgrade procedure and the way back to the default. Also correct the revert paragraph: reverting linuxPodInterfaceType to Veth only changes what the CNI plugin creates for new pods. Attachment follows each interface's own type, so existing netkit interfaces keep netkit attachment. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
48fb3d5 to
f6d332a
Compare
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.
Suppressed comments (2)
calico/operations/ebpf/enabling-ebpf.mdx:469
- The
NetkitandTCXbullets read as if TCX is always used, but the generated Felix configuration reference indicates TCX can fall back to TC when TCX isn’t available. Consider reflecting that here to avoid misleading readers about kernel/support requirements.
* `Netkit` (default) — netkit attachment on netkit interfaces, TCX on every other interface.
* `TCX` — TCX on every interface, including netkit interfaces.
calico/operations/ebpf/enabling-ebpf.mdx:487
- “Removing the netkit links” is ambiguous and can be read as removing the netkit interfaces themselves, but earlier the doc states the interfaces stay netkit and only the attachment changes. Reword to make it clear you mean detaching/moving the netkit-attached programs.
Felix restarts on each node and re-attaches its programs, removing the netkit links.
netkit is the kernel's device type name, so it is spelled lowercase in prose and Vale.Spelling flags every occurrence. The existing netkit section predates the check running over it; only changed lines are linted, so the term first shows up as an error when that section is edited. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.
Suppressed comments (2)
calico/operations/ebpf/enabling-ebpf.mdx:470
- The phrase “Pod bandwidth QoS annotations” is ambiguous here; it’s clearer to either name the annotation(s) or link to the QoS bandwidth controls doc so readers know what’s unsupported under
TC.
* `Netkit` (default) — netkit attachment on netkit interfaces, TCX on every other interface.
* `TCX` — TCX on every interface, including netkit interfaces.
* `TC` — the legacy qdisc-based attachment on every interface. Pod bandwidth QoS annotations are not supported with `TC`.
calico/operations/ebpf/enabling-ebpf.mdx:487
- “Removing the netkit links” reads like the interfaces are removed; this step is about detaching netkit-attached eBPF programs and re-attaching via TCX. Rephrase to avoid confusion during downgrade procedures.
Felix restarts on each node and re-attaches its programs, removing the netkit links.
Product Version(s):
Calico next (the
calico/tree only — the netkit section is tech preview and not yet in a versioned tree).Issue:
CORE-13281. Documents the user-facing side of projectcalico/calico#13462.
Link to docs preview:
SME review:
DOCS review:
Additional information:
The netkit section on the eBPF page covers how to get netkit pod interfaces but not how the eBPF data plane attaches to them, so there is no documented way off netkit attachment. That matters for downgrades: a Calico release that has no concept of netkit attachment cannot remove netkit programs, so downgrading a node directly leaves the old programs attached and enforcing the policy that was in force at downgrade time, while the downgraded Felix programs the same interfaces through TC/TCX — two data planes on one interface.
This PR adds two short subsections:
bpfAttachTypevalues, the fact thatTCX/TCalso migrate existing netkit interfaces (the interfaces stay netkit, no pod is recreated), and that changing the field restarts Felix. It also notes that pod bandwidth QoS annotations are not supported withTC, so nobody picksTCthinking it is the safer target.TCX, let Felix restart, then downgrade; and removing the field to return to the default afterwards.It also corrects one existing sentence. The page said that after reverting
linuxPodInterfaceTypetoVeth, "the eBPF data plane treats those as veth (programs attach via TC/TCX)". That is not what happens:linuxPodInterfaceTypeonly controls what the CNI plugin creates for new pods, while the attach mechanism follows each interface's own type. Existing netkit interfaces keep netkit attachment.The behaviour described here was verified on a GCP cluster (kernel 6.17, eBPF data plane, netkit pod interfaces): flipping
bpfAttachTypebetween the default andTCXmoved the programs on netkit interfaces between netkit and TCX attachment in both directions, with the interfaces staying netkit and no pod recreated; underTCthe bandwidth QoS qdiscs were torn down.Merge checklist: