DOCS-2997: Write the guide for preparing an existing bridge - #2946
Open
ctauchen wants to merge 1 commit into
Open
DOCS-2997: Write the guide for preparing an existing bridge#2946ctauchen 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
This PR fills in the Calico Enterprise “Prepare an existing bridge” guide for L2 bridge networking in the shared-uplink (“bring your own bridge”) scenario, focusing on making the host bring the bridge up correctly at boot and verifying behavior before/after the first workload attaches.
Changes:
- Expands the page with explicit prerequisites, required bridge properties, and ordering/caution guidance (VLAN filtering, MAC pinning, VLAN protocol).
- Adds detailed host configuration steps, including a NetworkManager keyfile example and bridge/VLAN verification workflow.
- Adds guidance for setting Felix
bpfDataIfacePatternand for referencing an existing bridge from aNetwork.
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Comment on lines
+103
to
+104
| - **Enslaving the trunk.** $[prodname] adds the trunk interface to the bridge itself. The | ||
| interface only has to exist and be named in the `Network`. |
ctauchen
force-pushed
the
DOCS-2997-4-byo-bridge
branch
from
August 21, 2026 11:08
1a7868c to
61fbd1f
Compare
Fill in the guide for nodes whose only uplink also carries the node's own IP address, where Calico cannot create the bridge itself. The guide is written around configuring the host to bring the bridge up correctly at boot. Moving a running IP address onto a bridge is the dangerous way to reach the same end state, so the page does not teach it. The page states the three properties Calico checks, and what it deliberately does not require. It covers why the bridge MAC address must be set explicitly and must not be the trunk's, the VLAN membership the bridge device needs in its own right, and two hazards that are not settings: a bridge named with the prefix Calico treats as its own, and the startup cost of spanning tree. Verification runs in two rounds, because the failures that matter most only appear when the first workload attaches. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
ctauchen
force-pushed
the
DOCS-2997-4-byo-bridge
branch
from
August 21, 2026 11:10
61fbd1f to
0607df2
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 (3)
calico-enterprise/networking/l2-bridge/byo-bridge.mdx:246
- The step to “find the current value” of
bpfDataIfacePatternlinks to the FelixConfiguration reference, but that page doesn’t reflect your cluster’s livedefaultresource. This is likely to mislead readers into looking in docs rather than querying their cluster config.
Validate this in a lab before you apply it to a cluster you care about.
Host network configuration varies with distribution and with whatever manages it, and the failure mode is a node you cannot reach.
calico-enterprise/networking/l2-bridge/byo-bridge.mdx:303
- The “Network resource” link currently points to the VRF-focused
NetworkCRD reference (it states onlyvrfis supported) and does not document the L2 bridge host config fields shown above (for example,bridge.existingBridge). This reference is likely incorrect/misleading in the context of L2 bridge networking.
If the bridge does not meet all three requirements, nothing is programmed and workloads on that `Network` stay administratively down rather than attaching to a bridge that cannot isolate them.
The only signal is the Felix log in `calico-node`, which names the bridge, the `Network`, and the command that fixes it, and repeats every few seconds until you do.
calico-enterprise/networking/l2-bridge/byo-bridge.mdx:175
- Inside the NetworkManager example, the inline comment says “Calico programs 802.1Q…”, which is ambiguous in Calico Enterprise docs (it can be read as Calico OSS). Consider naming the specific product here for consistency/clarity.
This issue also appears in the following locations of the same file:
- line 245
- line 301
```ini
# /etc/NetworkManager/system-connections/br-l2.nmconnection
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/byo-bridge.mdx:257
bpfDataIfacePatternis documented as a regular expression (not a glob). The suggested patternbr-l2.*treats.as “any character”, so it can also match unintended interfaces (e.g.,br-l20,br-l2x). Consider using an anchored regex and escaping the dot so it matches onlybr-l2and its VLAN subinterfaces.
1. Find the current value of `bpfDataIfacePattern` in the default [FelixConfiguration](../../reference/resources/felixconfig.mdx).
2. Add a pattern that matches the device holding the node's address.
For a node whose address is on `br-l2.100`, `br-l2.*` matches it.
calico-enterprise/networking/l2-bridge/byo-bridge.mdx:313
- The linked Network resource page currently documents only VRF networks (it states “Currently only
vrfis supported”), and does not cover the L2 bridgeNetworkfields described in this guide. Including it here is likely to confuse readers looking for thebridge.existingBridgeschema.
- [L2 bridge support and limitations](../../reference/l2-bridge-support.mdx)
- [Network resource](../../reference/resources/network.mdx)
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 guide for preparing an existing bridge. Fourth in the DOCS-2997 sequence. It comes before the main setup guide because its output feeds it.
This is the page for nodes whose only uplink also carries the node's own IP address, where Calico cannot create the bridge itself.
The guide is written around configuring the host so it brings the bridge up correctly at boot. Moving a running IP address onto a bridge reaches the same end state by a much more dangerous route, so the page does not teach it.
What the page covers:
This is the page in the set that most needs an engineering read, for two reasons.
The annotated NetworkManager example is constructed from the documented requirements rather than copied from a working node. It carries a caution telling readers to validate it in a lab first. Alex has a working configuration from the EP2 hash release, and if we can get it, it should either replace this example or be added alongside it. I would rather not ship an invented host network configuration without someone confirming it.
The failure behaviour described in the last section, and the three requirements, come from the code audit rather than from testing. Worth a confirmation that they still hold.
One known interim issue: the link to the concept page uses a section anchor that does not exist in main until the concept page PR merges. The file exists, so the link resolves, but the anchor will not jump until then.
Changed page: https://deploy-preview-2946--calico-docs-preview-next.netlify.app/calico-enterprise/next/networking/l2-bridge/byo-bridge