DOCS-2997: Write the L2 bridge networking concept page - #2944
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
Adds the full concept documentation for Calico Enterprise L2 bridge networking, explaining the motivation (preserving VM identity), the Network resource model, bridge/trunk/access-port behavior, bridge-mode selection, and the security/policy implications.
Changes:
- Replaces the placeholder outline with detailed explanatory content for L2 bridge networking (model, tagging, supported topology, traffic flows).
- Clarifies the two bridge modes (Calico-managed vs bring-your-own bridge) and why host IP ownership drives the choice.
- Documents policy enforcement behavior and summarizes key limitations, plus adds a curated “Additional resources” link list.
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
| types, and drops broadcast and multicast traffic. Reverse path filtering on pod | ||
| traffic is strictly enforced. |
Fill in the concept page for L2 bridge networking. The page explains why the feature exists, what a Network resource models, and how frames move between a workload, the bridge, and the fabric. It covers the choice between a Calico-managed bridge and a bridge you prepare yourself, and why that choice depends on whether Calico can have an uplink of its own rather than on how many network cards a node has. Three sections carry the points that reviewers of the plan asked for. Policy enforcement is unchanged on an L2 network, and the page says so early. VMs and pods are configured differently, so the page establishes that before any procedure relies on it. And the reason Calico refuses to build a bridge on a shared uplink is explained in terms of who owns the node's IP address. The page is explanation only. It contains no configuration to apply and no numbered steps. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
b445012 to
1a54816
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 (1)
calico-enterprise/networking/l2-bridge/about-l2-bridge.mdx:193
- This sentence refers to "pod traffic", but this section is describing protections applied to L2 workloads in general (including VMs). Using "pod" here is confusing and reads like the protection only applies to pods.
$[prodname] locks each access port down against those.
It validates the source MAC and source IP address of everything a workload sends, checks the destination address of what it receives, validates the sender fields in ARP, filters unexpected Ethernet types, and drops broadcast and multicast traffic.
Reverse path filtering on pod traffic is strictly enforced.
| You could build something similar yourself with a Linux bridge and a VLAN trunk. | ||
| What you cannot get that way is policy. | ||
| Because the workload's interface is a $[prodname] interface, it gets network policy and flow visibility on that L2 link, exactly as a pod on the $[prodname] pod network does. | ||
|
|
||
| It is worth being straightforward about the tension here. | ||
| $[prodname] was designed to separate security from connectivity and to scale by routing at layer 3. | ||
| L2 bridge networking runs against that grain deliberately: it adapts $[prodname] to the network you already have, rather than asking you to change the network to suit $[prodname]. |
There was a problem hiding this comment.
Agreed. Holding this for the editorial pass with the rest of the language cleanup, rather than in this PR.
Add a comment at the top of the page naming the user story it exists to serve. The page plan derives every page from one story, and a page that cannot carry a distinct story should not exist. Recording the story in the page keeps that test available to whoever edits it next, and makes it easier to see when an addition belongs on a different page. This page also carries a fragment of the network identity story, because the explanation page that owns it is deferred to GA. That is marked as subsidiary rather than left implicit. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
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-enterprise/networking/l2-bridge/about-l2-bridge.mdx:203
- This section is describing L2 workloads (VMs and pods), but the last sentence switches to “pod traffic”, which reads like a copy/paste error and is confusing in a VM-focused feature.
$[prodname] locks each access port down against those.
It validates the source MAC and source IP address of everything a workload sends, checks the destination address of what it receives, validates the sender fields in ARP, filters unexpected Ethernet types, and drops broadcast and multicast traffic.
Reverse path filtering on pod traffic is strictly enforced.
calico-enterprise/networking/l2-bridge/about-l2-bridge.mdx:84
- The text alternates between code-formatted
Networkand plain “Networks”. Since this is the name of a cluster-scoped resource kind, keeping it consistently formatted avoids ambiguity (especially for readers scanning for resource names).
A single `Network` can carry several VLANs, and that is usually the right shape.
Each `Network` you create adds work for $[prodname] on every node it selects, so a handful of Networks each carrying one VLAN costs more than one Network carrying a handful of VLANs.
Reach for additional Networks when you need genuinely separate bridges, not as a way to organize VLANs.
lwr20
left a comment
lwr20
left a comment
There was a problem hiding this comment.
Checked against 2026-08-20-v3-24-2-kettle on OpenShift. The model and the eBPF-only rationale read accurately against the shipped behaviour.
|
|
||
| So the boundary is ownership, not capability. | ||
| On a bridge you built, $[prodname] still does everything else it would otherwise do: it attaches workloads, programs their policy, sets their VLAN membership, and locks their ports down. | ||
| It simply does not touch the parts your host configuration owns. |
There was a problem hiding this comment.
This boundary is not quite held today, on the BYO-bridge path.
Attaching L2 workloads lowers the bridge MTU to Calico's auto-detected value (1480), and because a Linux bridge takes the minimum MTU of its ports, the VLAN sub-device carrying the host's own address and default route drops with it. The operator had explicitly configured the trunk at 1500 and set no MTU on the bridge.
So Calico does change something the host configuration owns. Raised as CORE-13428 — flagging it here because this paragraph is the promise it contradicts.
There was a problem hiding this comment.
Fixed, thanks, and it is a fair catch that this paragraph is the promise it contradicts. The ownership section now says explicitly that one thing crosses the line: workload interfaces are attached at the cluster-wide MTU, a bridge takes the lowest MTU of its ports, and a bridge you built can drop with it. It points at the BYO page for pinning it. CORE-13428 noted.
The page is retitled around the task it performs, because it serves both a VM migrating in with an existing address and a new VM that needs a fixed one.
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 (3)
Previously missed (3) — in code that hasn't changed since the last review.
calico-enterprise/networking/l2-bridge/about-l2-bridge.mdx:203
- The statement that Calico "drops broadcast and multicast traffic" is ambiguous and reads as contradictory to the earlier mention of validating ARP (which relies on broadcast). Clarify that only non-essential broadcast/multicast is filtered/limited, and align the wording "pod traffic" with the broader term used elsewhere (VMs and pods).
$[prodname] locks each access port down against those.
It validates the source MAC and source IP address of everything a workload sends, checks the destination address of what it receives, validates the sender fields in ARP, filters unexpected Ethernet types, and drops broadcast and multicast traffic.
Reverse path filtering on pod traffic is strictly enforced.
calico-enterprise/networking/l2-bridge/about-l2-bridge.mdx:234
- Heading text is grammatically awkward. "Why the eBPF data plane only" reads like a fragment; rephrase to make the intent clear.
## Why the eBPF data plane only
calico-enterprise/networking/l2-bridge/about-l2-bridge.mdx:242
- This sentence starts with "nftables" mid-paragraph. To avoid starting a sentence with a lowercase tool name, restructure the sentence.
nftables, their replacement, has a subtler problem: it presents VLAN headers inconsistently depending on the direction traffic is moving through the bridge.
|
Read this end to end against a live rig (RKE2 + Calico Enterprise v3.24 EP2, BPF dataplane, BYO bridge, plus an openSUSE Leap Micro node standing in for a customer's SLE Micro). I couldn't fault the page — so rather than silence, here is which assertions I've now actually measured, since the review note says assertions are assumed sound unless someone says otherwise. Verified on a live cluster:
One phrasing nuance. In "$[prodname] can have its own uplink":
All true, but a reader may take the middle clause as implying a BYO bridge doesn't survive a reboot. It does, when configured persistently — I rebooted a NetworkManager-based node three times and the bridge, its VLANs and the node's address all came back unaided, with Calico reprogramming its VLANs automatically. What a reboot genuinely cannot undo in managed mode is something narrower and, on the evidence, more valuable: with a bridge Calico owns, the trunk's VLAN list cannot drift from the Suggest tightening that clause to say what it means — something like "nothing on the host that can drift out of step with the |
Attaching workloads can lower the MTU of a bridge the operator built, and of a VLAN device above it, which is the ownership boundary this section describes. Say so rather than leaving the promise unqualified.
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)
Previously missed (1) — in code that hasn't changed since the last review.
calico-enterprise/networking/l2-bridge/about-l2-bridge.mdx:13
- The top-of-page
{/* ... */}block contains internal planning notes (user story/ladder). This is the only instance of this pattern in the repo and it adds non-user-facing content to the published source; please move this information to the tracking issue/PR description and keep the MDX focused on reader content.
{/*
User story, primary
S1: As a network engineer, I want to understand how Calico puts workloads on my existing VLANs, which bridge mode my nodes need, and where policy is still enforced, so that I can judge whether it fits my fabric and my security posture before committing.
User stories, subsidiary
S2: carries the part of the network-identity explanation that says why Calico must own addressing, until the dedicated page exists at GA.
Story ladder and page plan: DOCS-2997.
*/}
calico-enterprise/networking/l2-bridge/about-l2-bridge.mdx:207
- This section describes protections applied to L2 workloads, but the last sentence switches to "pod traffic", which is confusing in context. Consider making the statement workload-agnostic here.
$[prodname] locks each access port down against those.
It validates the source MAC and source IP address of everything a workload sends, checks the destination address of what it receives, validates the sender fields in ARP, filters unexpected Ethernet types, and drops broadcast and multicast traffic.
Reverse path filtering on pod traffic is strictly enforced.
Replace nothing that a reboot can undo, which a reader could take to mean a prepared bridge does not survive a reboot. It does, when configured persistently. What managed mode actually prevents is the trunk's VLAN list drifting from the Network, so say that instead.
|
Thanks Lance, and thanks for listing what you measured rather than staying silent — knowing which assertions are now tested is worth as much as the corrections. Taken on the phrasing. "Nothing that a reboot can undo" is gone. You are right that it invited the wrong inference, and your reboot testing settles it: a persistently configured BYO bridge does come back unaided. The section now names what managed mode actually prevents, close to your wording: with a bridge Calico owns the VLAN list on the trunk cannot drift from the Network, because nothing else is managing it. It also says what happens on a BYO bridge when the two diverge, and links to 2946 where the detail lives. I have also qualified the ownership boundary paragraph further up, following your MTU comment: attaching workloads can lower the MTU of a bridge you built, and of a VLAN device above it, so that promise is no longer unqualified. CORE-13475 is now warned about on 2946 in two places, by the trunk example and as a verification round for later host changes. |
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)
Previously missed (1) — in code that hasn't changed since the last review.
calico-enterprise/networking/l2-bridge/about-l2-bridge.mdx:183
- This sentence frames L2 interface policy in terms of pods, but the page explicitly covers both VMs and pods. Using pod-specific wording here can confuse readers about whether enforcement differs for VMs.
An L2 workload gets an ordinary $[prodname] virtual interface, carrying the same policy program as any pod on the $[prodname] pod network.
calico-enterprise/networking/l2-bridge/about-l2-bridge.mdx:212
- This refers to "pod traffic", but the section is describing protection mechanisms for workloads on the L2 network (including VMs). Consider using workload-neutral language to avoid implying the behavior is pod-specific.
Reverse path filtering on pod traffic is strictly enforced.
Fills in the concept page for L2 bridge networking. Second in the DOCS-2997 sequence, building on the structure already merged.
The page explains why the feature exists, what a Network resource models, and how frames move between a workload, the bridge, and your fabric. It covers the choice between a Calico-managed bridge and a bridge you prepare yourself, and why that choice depends on whether Calico can have an uplink of its own rather than on how many network cards a node has.
Three sections carry points that came out of the engineering review:
The page is explanation only. It contains no configuration to apply and no numbered steps. Those live in the two setup guides.
Two things for reviewers to weigh in on:
Changed page: https://deploy-preview-2944--calico-docs-preview-next.netlify.app/calico-enterprise/next/networking/l2-bridge/about-l2-bridge