Repository navigation
[DOCS#CORE-13910]: State Multus v4.3.1 floor for L2 bridge and Forklift on OpenShift - #3175
aaaaaaaalex wants to merge 17 commits into
Conversation
The L2 bridge prerequisites now ask for Multus v4.3.1 or later, matching the Forklift install page. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
✅ Deploy Preview succeeded!Built without sensitive environment variables
To edit notification comments on pull requests, go to your Netlify project configuration. |
✅ Deploy Preview for calico-docs-preview-next ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
There was a problem hiding this comment.
🟡 Changes recommended
The Multus v4.3.1 prerequisite is still missing from the BYO bridge documentation and its versioned copy, leaving users vulnerable to the IP-release bug this change aims to prevent.
2 open issues
What changed in this PR
Updates Calico Enterprise 3.24 L2 bridge documentation to require Multus v4.3.1 or later, preventing known IPAM cleanup issues with older releases.
Changes:
- Raises the Multus prerequisite in the unversioned L2 bridge reference and VLAN connection pages.
- Applies the same requirement to the versioned 3.24-2 documentation.
- Leaves the general multiple-networks guidance unchanged.
This pull request requires changes.
| File | Review result |
|---|---|
calico-enterprise/reference/l2-bridge-support.mdx |
Moderate issue (3 votes): The linked networking/l2-bridge/byo-bridge.mdx procedure, including its versioned copy, still permits Multus versions below v4.3.1 for secondary-interface workloads. |
calico-enterprise/networking/l2-bridge/connect-vlan.mdx |
Moderate issue (1 vote): The linked byo-bridge.mdx path still lacks the v4.3.1 requirement, allowing users to bypass the new floor. |
calico-enterprise_versioned_docs/version-3.24-2/reference/l2-bridge-support.mdx |
Moderate issue (3 votes): The linked versioned networking/l2-bridge/byo-bridge.mdx procedure still lacks the v4.3.1 requirement for secondary-interface workloads. |
calico-enterprise_versioned_docs/version-3.24-2/networking/l2-bridge/connect-vlan.mdx |
Moderate issue (1 vote): The linked versioned byo-bridge.mdx path still lacks the v4.3.1 requirement, allowing users to bypass the new floor. |
Review effort: Lite
| - An active $[prodname] license. | ||
| - The eBPF data plane, enabled cluster-wide. | ||
| - [Multus](../networking/configuring/multiple-networks.mdx), for attaching an L2 network to a workload as an additional interface. | ||
| - [Multus](../networking/configuring/multiple-networks.mdx) v4.3.1 or later, for attaching an L2 network to a workload as an additional interface. |
There was a problem hiding this comment.
Agreed. Fixed in 22122b5: byo-bridge.mdx (current and 3.24-2) now asks for v4.3.1 or later and links to the reference prerequisites for the OpenShift releases.
| - An active $[prodname] license. | ||
| - The eBPF data plane, enabled cluster-wide. | ||
| - [Multus](../networking/configuring/multiple-networks.mdx), for attaching an L2 network to a workload as an additional interface. | ||
| - [Multus](../networking/configuring/multiple-networks.mdx) v4.3.1 or later, for attaching an L2 network to a workload as an additional interface. |
There was a problem hiding this comment.
Same fix as above (22122b5), including the 3.24-2 copy.
lwr20
left a comment
lwr20
left a comment
There was a problem hiding this comment.
The floor wording looks right to me. I agree with Copilot that byo-bridge.mdx (and its 3.24-2 copy) needs the same v4.3.1 floor, or it's an easy way around this. The other thing is that the upstream thin manifest ships the :snapshot image, so applying the v4.3.1 manifest doesn't actually get you v4.3.1.
| - An active $[prodname] license. | ||
| - The eBPF data plane, enabled cluster-wide. | ||
| - [Multus](../networking/configuring/multiple-networks.mdx), for attaching an L2 network to a workload as an additional interface. | ||
| - [Multus](../networking/configuring/multiple-networks.mdx) v4.3.1 or later, for attaching an L2 network to a workload as an additional interface. |
There was a problem hiding this comment.
Applying the upstream v4.3.1 thin manifest (deployments/multus-daemonset.yml) runs multus-cni:snapshot, not v4.3.1, so someone can follow this and still not be on a pinned fixed release. Can we add a line telling them to pin the daemon and init container images to the release tag, like the Forklift page does?
There was a problem hiding this comment.
Good catch. Both upstream manifests do this (thin uses snapshot, thick uses snapshot-thick). In 22122b5 the reference prerequisites now say to set the Multus images to the release tag you're installing, and connect-vlan links to it.
There was a problem hiding this comment.
I'm going to push back on Claude's reasoning here a bit: the docs currently don't make reference to any specific manifest or link them - we shouldn't micromanage the Multus install process on upstream's behalf. If upstream has a bug where a pinned version actually ships floating tags, maybe we should just raise that with them instead
There was a problem hiding this comment.
Fair enough. These pages don't link a manifest or walk through the Multus install, so saying which version is enough here and pinning is upstream's problem. Happy to drop it. It's worth raising upstream though, since the manifest at the v4.3.1 tag still pulling snapshot will catch people out.
| - [Multus](../configuring/multiple-networks.mdx) v4.3.1 or later installed. | ||
| Every procedure on this page attaches the L2 network as an additional interface, which is what Multus does, so it is required here. | ||
| A workload taking an L2 network as its primary interface is configured with annotations instead and does not need Multus; see [Primary and secondary interfaces](../../reference/l2-bridge-support.mdx#primary-and-secondary-interfaces). | ||
| OpenShift includes Multus by default. |
There was a problem hiding this comment.
Do we know whether the Multus OpenShift ships has the multus-cni#1449 fix? If not, an OpenShift user reads this as covered when they might not be.
There was a problem hiding this comment.
We didn't know, so I checked. OpenShift backported the fix to its own Multus (openshift/multus-cni #350/#351/#352, OCPBUGS-120682/-120763/-120774). From the 4-stable release changelogs, it first ships in 4.20.40, 4.21.35 and 4.22.14. The release-4.19 branch still has the lossy json.Marshal(netConfList) and no backport, so every 4.19 release is affected. 4.18 and earlier don't have the conflist-delegate code that regressed. In 22122b5 the reference prerequisites and the Forklift-on-OpenShift page list the fixed releases, and connect-vlan and byo-bridge point to them.
There was a problem hiding this comment.
Update: the pages now only name the OpenShift releases whose Multus doesn't free IPs on delete (4.19, and 4.20–4.22 before 4.20.40 / 4.21.35 / 4.22.14). They don't state a minimum or supported OpenShift version, since we don't publish OpenShift version support elsewhere.
…he Multus floor The BYO bridge prerequisites now ask for Multus v4.3.1 or later too. The L2 bridge reference lists the OpenShift releases whose bundled Multus frees a workload's IP address on delete (4.20.40, 4.21.35, 4.22.14 and later). The VLAN, BYO bridge and Forklift-on-OpenShift pages point to it or state the same releases. The upstream Multus manifests use a floating snapshot image, so the reference now says to set the images to the release being installed. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
aaaaaaaalex
changed the title
…ng support Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ions Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ther platforms Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
lwr20
left a comment
lwr20
left a comment
There was a problem hiding this comment.
BYO bridge has the floor now, thanks, and I'm fine dropping the snapshot note. The thing I'd still fix is the OpenShift line. It now says everything before v4.20 is affected, but from what you found 4.18 and earlier are fine and early 4.20 to 4.22 patches aren't. The byo-bridge and connect-vlan links also send OpenShift users to Prerequisites for "recommended versions" that aren't listed there any more.
| OpenShift includes Multus by default; on other platforms it is a third-party component that $[prodname] does not ship. | ||
| A workload that takes an L2 network as its primary interface does not use Multus. | ||
| See [Primary and secondary interfaces](#primary-and-secondary-interfaces). | ||
| - If using OpenShift, an up-to-date version, which includes Multus: releases prior to v4.20 bundle a Multus that does not free a workload's IP address when the workload is deleted; the latest patch releases in v4.20+ fix the issue. |
There was a problem hiding this comment.
I don't think "prior to v4.20" is right. From your digging, 4.18 and earlier don't have the broken code, 4.19 does, and 4.20 to 4.22 stay broken until 4.20.40, 4.21.35 and 4.22.14. Can we go back to naming those releases? That just says which ones leak, so it doesn't claim any OpenShift support. It also gives the "see Prerequisites for the recommended versions" links on byo-bridge and connect-vlan something to point at. The same line on the Forklift OpenShift page and the 3.24-2 copies would need it too.
lwr20
left a comment
lwr20
left a comment
There was a problem hiding this comment.
Thanks, naming 4.19 fixes the main problem. One small thing inline: if we also name the first fixed patches, the 'recommended versions' links from byo-bridge and connect-vlan land on something concrete.
Co-authored-by: Lance Robson <lance@tigera.io>
Mirror the reference page wording on the Forklift on OpenShift page and the 3.24-2 copies. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
ctauchen
left a comment
ctauchen
left a comment
There was a problem hiding this comment.
One suggestion, otherwise LGTM
|
|
||
| - Cluster admin access, and `kubectl` or `oc`. | ||
| - A cluster running $[prodname] as the CNI, and Multus for secondary-NIC attachments, with your Installation's [`spec.calicoNetwork.multiInterfaceMode`](../l2-bridge/connect-vlan.mdx) set to `Multus`. | ||
| - An up-to-date version of OpenShift: a Multus bug shipped in OpenShift 4.19 leads to a VM's IP address not being freed when the VM is deleted; it is fixed in 4.20.40, 4.21.35, 4.22.14 and later patch releases. |
There was a problem hiding this comment.
Consider something like this:
| - An up-to-date version of OpenShift: a Multus bug shipped in OpenShift 4.19 leads to a VM's IP address not being freed when the VM is deleted; it is fixed in 4.20.40, 4.21.35, 4.22.14 and later patch releases. | |
| - One of the following OpenShift versions: | |
| - 4.20.40 or later 4.20 patch | |
| - 4.21.35 or later 4.21 patch | |
| - 4.22.14 or later 4.22 patch |
Name the first fixed patch release for each supported OpenShift minor as a list, on the current page and the 3.24-2 copy. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Signed-off-by: Alex O'Regan <alex.oregan@tigera.io>
Product Version(s):
Calico Enterprise 3.24 (unversioned pages and version-3.24-2).
Issue:
https://tigera.atlassian.net/browse/CORE-13910
Link to docs preview:
networking/l2-bridge/connect-vlanandnetworking/l2-bridge/byo-bridge, prerequisites, Multus bullet.networking/kubevirt/install-forklift-openshift, Before you begin.reference/l2-bridge-support, prerequisites, Multus bullet.SME review:
DOCS review:
Additional information:
Follows #3172, which moved the Forklift install page to Multus v4.3.1. The L2 bridge prerequisites (VLAN, BYO bridge and the reference page) listed Multus without a version; they now ask for v4.3.1 or later.
The reference prerequisites also name the OpenShift releases whose bundled Multus does not free IP addresses on delete (all of 4.19, and 4.20, 4.21 and 4.22 before 4.20.40, 4.21.35 and 4.22.14), and say to set the images to the release tag, because the upstream manifests use a floating
snapshotimage. The Forklift-on-OpenShift page names the same releases. Neither page states which OpenShift versions are supported.The general multiple-networks page is unchanged on purpose.
Merge checklist:
🤖 Generated with Claude Code