DOCS-2997: Write the L2 bridge networking concept page - #2944
Open
ctauchen wants to merge 2 commits into
Open
Conversation
✅ Deploy Preview for calico-docs-preview-next ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
❌ Deploy Preview for tigera failed. Why did it fail? →Built without sensitive environment variables
|
Contributor
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.
Comment on lines
+230
to
+231
| 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>
ctauchen
force-pushed
the
DOCS-2997-2-about-l2-bridge
branch
from
August 21, 2026 11:08
b445012 to
1a54816
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 (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.
fasaxc
reviewed
Aug 21, 2026
Comment on lines
+29
to
+35
| 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]. |
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>
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 (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.
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 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