DOCS-2997: Write the L2 bridge support and limitations reference - #2945
Open
ctauchen wants to merge 1 commit into
Open
DOCS-2997: Write the L2 bridge support and limitations reference#2945ctauchen wants to merge 1 commit into
ctauchen wants to merge 1 commit into
Conversation
✅ 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. |
Contributor
There was a problem hiding this comment.
Pull request overview
Adds a Calico Enterprise reference page documenting L2 bridge networking support and limitations.
Changes:
- Documents platform, kernel, data-plane, Multus, topology, and addressing requirements.
- Covers Kubernetes integration, lifecycle, sizing, and observability limitations.
- Lists unsupported or deferred capabilities.
Suppressed comments (3)
calico-enterprise/reference/l2-bridge-support.mdx:34
- VPP is a valid
linuxDataplanevalue in the Installation API (reference/installation/_api.mdx:4040-4053), but it is missing from this data-plane table. Add an explicitVPP | Norow so VPP users can rule the feature out without relying on the prose.
| Data plane | Supported |
| ---------- | --------- |
| eBPF | Yes. Required. |
| iptables | No, and not planned. |
| nftables | No. Deferred to a later release. |
calico-enterprise/reference/l2-bridge-support.mdx:38
about-l2-bridge.mdxcurrently contains only section outlines; itsWhy the eBPF data plane onlysection has no explanation. This sentence therefore links to a page that does not provide the promised rationale. Fill the target before publishing or remove/rephrase this link until the supporting content exists.
For why the feature is tied to eBPF, see
[About L2 bridge networking](../networking/l2-bridge/about-l2-bridge.mdx).
calico-enterprise/reference/l2-bridge-support.mdx:82
byo-bridge.mdxcurrently contains an outline but no bridge-preparation steps, so this "For the procedure" link sends readers to a page without a procedure. Complete the target before publishing this promise, or change the link to an available procedure.
full contract, including what $[prodname] does not require, see the
[Network resource](resources/network.mdx). For the procedure, see
[Prepare an existing bridge](../networking/l2-bridge/byo-bridge.mdx).
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Comment on lines
+22
to
+23
| There is nothing extra to install. The `Network` resource and the components that act | ||
| on it ship with the $[prodname] operator. |
Comment on lines
+60
to
+64
| - [Multus](../networking/configuring/multiple-networks.mdx), for attaching workloads to | ||
| a network as an additional interface. Multus is not shipped by $[prodname]. | ||
| - `multiInterfaceMode: Multus` set in the `calicoNetwork` section of the | ||
| [Installation](installation/api.mdx) resource. Installing Multus is not enough on its | ||
| own, and nothing reports the omission until a workload fails to get connectivity. |
Comment on lines
+110
to
+113
| | Kubernetes Services | Not available | | ||
| | NAT | Not available | | ||
| | Maglev load balancing | Not available | | ||
| | Nested BGP to local workloads | Not supported | |
Comment on lines
+99
to
+102
| Two categories of traffic are handled differently from the pod network. | ||
|
|
||
| - Broadcast and multicast traffic is dropped, in both directions. | ||
| - Reverse path filtering on pod traffic is strictly enforced. |
Comment on lines
+170
to
+171
| - Protection against deleting a `Network` that is still in use, and status reporting on | ||
| the `Network` resource. |
Comment on lines
+22
to
+23
| There is nothing extra to install. The `Network` resource and the components that act | ||
| on it ship with the $[prodname] operator. |
ctauchen
force-pushed
the
DOCS-2997-3-support-limitations
branch
from
August 21, 2026 11:08
b85ba39 to
da19886
Compare
Fill in the support and limitations page for L2 bridge networking. The page is a lookup table rather than prose, so a reader can rule the feature in or out quickly. It records the data plane requirement, the kernel floor, the prerequisites, the one supported bridge topology, and the addressing rules. Several entries exist because they are easy to miss and expensive to discover later. The kernel floor is higher than the floor for the eBPF data plane on its own. Installing Multus is not sufficient without also setting the multi interface mode. Connect-time load balancing cannot be disabled for a single interface, which affects pods but not VMs. And a flow that crosses two segments on one node can be double-counted in flow logs. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
ctauchen
force-pushed
the
DOCS-2997-3-support-limitations
branch
from
August 21, 2026 11:10
da19886 to
662d671
Compare
Contributor
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 (8)
calico-enterprise/reference/l2-bridge-support.mdx:105
- The PR description says the Kubernetes Services, NAT, Maglev, and nested-BGP rows are taken from the design document rather than tested behavior and need an engineering check. These rows are currently published as unconditional limitations, so readers may incorrectly rule out or design around these features. Please get that confirmation before merging or explicitly mark these entries as unverified.
| ------- | ------------------ |
| Kubernetes Services | Not available |
| NAT | Not available |
| Maglev load balancing | Not available |
calico-enterprise/reference/l2-bridge-support.mdx:155
- This says status reporting is not in the release, but the linked Network resource currently documents
Network.status.conditionsas reporting the observed state. Unless this limitation is specifically L2-only, the two references contradict each other; please remove the status-reporting claim or scope/update the resource documentation.
- eBPF-accelerated forwarding within the bridge.
calico-enterprise/reference/l2-bridge-support.mdx:35
- The page directs readers here for the reason eBPF is required, but the target's eBPF section currently contains only a heading and a one-sentence placeholder, not that explanation. This leaves the promised rationale missing from the published documentation. Add the explanation to the target page or link to an existing page that provides it.
calico-enterprise/reference/l2-bridge-support.mdx:32 - The support matrix conflicts with the API reference this page links to:
reference/resources/network.mdx:63still saysNetwork.specsupports onlyvrf, and:153says only the nftables dataplane is supported. As published, readers cannot create the advertised L2 Network and may choose the wrong dataplane. Update the Network API/CRD documentation in the same change, or do not publish this matrix yet.
| Data plane | Supported |
| ---------- | --------- |
| eBPF | Yes. Required. |
| iptables | No, and not planned. |
calico-enterprise/reference/l2-bridge-support.mdx:60
- These are stated as prerequisites before creating every
Network, but the Multus bullet limits them to additional interfaces while lines 114-118 claim that an L2 network can be primary. The existing Network API also documents primary attachment without Multus (reference/resources/network.mdx:121-137). Make Multus/multiInterfaceModeconditional on secondary-interface use, or remove the primary-interface claim.
Existing `Network` resources keep working if a license lapses.
- The eBPF data plane, enabled cluster-wide.
- [Multus](../networking/configuring/multiple-networks.mdx), for attaching workloads to a network as an additional interface.
Multus is not shipped by $[prodname].
- `multiInterfaceMode: Multus` set in the `calicoNetwork` section of the [Installation](installation/api.mdx) resource.
calico-enterprise/reference/l2-bridge-support.mdx:93
- As written, this drops ARP frames too. An IPv4 workload on an external VLAN needs ARP to resolve its router or peer, while this page simultaneously says IPv4 L2 networking and KubeVirt DHCP are supported. If the dataplane drops only application broadcast/multicast, document the ARP/DHCP exceptions; otherwise this limitation makes the advertised connectivity unusable.
calico-enterprise/reference/l2-bridge-support.mdx:74 - This promises that the Network resource contains the full L2 contract, but
reference/resources/network.mdxcurrently says that onlyvrfis supported and documents no L2 fields. Following this link therefore contradicts the support page and leaves readers without the schema/topology details needed to create an L2 Network. Update the resource reference in this change or qualify/remove this claim.
This issue also appears on line 155 of the same file.
A bridge you prepare yourself must meet three requirements, which $[prodname] checks and will not correct for you: VLAN filtering enabled, an explicitly set MAC address that is not the trunk's own, and the 802.1Q tag protocol rather than 802.1ad.
calico-enterprise/reference/l2-bridge-support.mdx:22
- This says that nothing extra needs to be installed, but Multus is an explicit prerequisite below and is not shipped by
$[prodname]. A reader can stop here and miss the required Multus installation. Please distinguish the absence of an additional $ [prodname] component from the separate Multus prerequisite.
There is nothing extra to install.
Contributor
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 (5)
calico-enterprise/reference/l2-bridge-support.mdx:23
There is nothing extra to installcontradicts the required Multus prerequisite below: Multus is not shipped by $[prodname] and must be installed separately. As written, readers may stop here and omit it; qualify this as no extra Calico component or mention the Multus exception.
There is nothing extra to install.
The `Network` resource and the components that act on it ship with the $[prodname] operator.
calico-enterprise/reference/l2-bridge-support.mdx:75
- The linked
Networkreference currently says that only thevrfnetwork type is supported and contains no L2 type, VLAN, or bridge fields. Readers therefore cannot use this promised "full contract" to create or validate the L2Network; update that API reference in this release or link to the L2-specific schema before publishing.
For the full contract, including what $[prodname] does not require, see the [Network resource](resources/network.mdx).
calico-enterprise/reference/l2-bridge-support.mdx:94
- As written, dropping all broadcast traffic in both directions also drops ARP, which an IPv4 workload on an external VLAN needs to resolve its peers and gateway. That makes the advertised IPv4 L2 connectivity impossible unless ARP (and possibly DHCP) is special-cased; document those exceptions explicitly or revise the support and addressing rows.
- Broadcast and multicast traffic is dropped, in both directions.
calico-enterprise/reference/l2-bridge-support.mdx:106
- The PR description says these four support rows come from the design document rather than tested behavior. Because this page is a lookup reference that readers will use to rule designs in or out, please get engineering confirmation for each row or mark the entries as unverified before shipping.
| Kubernetes Services | Not available |
| NAT | Not available |
| Maglev load balancing | Not available |
| Nested BGP to local workloads | Not supported |
calico-enterprise/reference/l2-bridge-support.mdx:156
- This says status reporting is absent, but the linked
NetworkAPI reference documentsNetwork.status.conditionsas the observed-state field. Scope this limitation to L2 Networks if only that implementation lacks status, or reconcile the API reference; the current wording gives contradictory guidance.
- Protection against deleting a `Network` that is still in use, and status reporting on the `Network` resource.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fills in the support and limitations reference for L2 bridge networking. Third in the DOCS-2997 sequence.
The page is a lookup table rather than prose, so a reader can rule the feature in or out quickly. It records the data plane requirement, the kernel floor, the prerequisites, the one supported bridge topology, the addressing rules, and what is not in this release.
Several entries exist because they are easy to miss and expensive to discover later:
Two entries need an engineering check before this ships. The rows for Kubernetes Services, NAT, Maglev, and nested BGP come from the design document rather than from tested behaviour, and this is an expensive page to be wrong on. Flagging rather than dropping them.
Changed page: https://deploy-preview-2945--calico-docs-preview-next.netlify.app/calico-enterprise/next/reference/l2-bridge-support