DOCS-2997: Write the guide for preparing an existing bridge - #2946
DOCS-2997: Write the guide for preparing an existing bridge#2946ctauchen wants to merge 2 commits 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. |
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.
| - **Enslaving the trunk.** $[prodname] adds the trunk interface to the bridge itself. The | ||
| interface only has to exist and be named in the `Network`. |
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>
61fbd1f to
0607df2
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 (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
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)
Add a comment at the top of the page naming the user story it exists to serve. The page ends by handing the reader to the setup guide, so the two pages complete one path between them. That relationship is recorded as subsidiary, to make clear that the host-side work is a distinct goal rather than a section that belongs in the other guide. 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 (3)
calico-enterprise/networking/l2-bridge/byo-bridge.mdx:104
- The page gives conflicting guidance on whether the host must enslave the trunk interface: this section says
$[prodname] adds the trunk, but later the host configuration steps require adding the trunk as a bridge port. Please clarify the distinction (host boot-time reachability vs what $ [prodname] does when programming the L2 network) so readers don't skip a necessary host config step or do redundant/unsafe changes.
- **Enslaving the trunk.**
$[prodname] adds the trunk interface to the bridge itself.
The interface only has to exist and be named in the `Network`.
calico-enterprise/networking/l2-bridge/byo-bridge.mdx:195
- In the NetworkManager example, the inline comment says "Calico" but the rest of the page uses $[prodname]. Keeping the product name consistent avoids confusion when this doc is reused across products/editions.
vlan-filtering=true
# Required. Calico programs 802.1Q membership and sub-devices.
vlan-protocol=802.1Q
calico-enterprise/networking/l2-bridge/byo-bridge.mdx:265
- Step 1 asks readers to find the "current value" of
bpfDataIfacePatternbut doesn't provide a way to retrieve it from the cluster; the linked page is a resource reference, not the live configuration. Adding akubectl/calicoctlcommand here would make the step actionable.
1. Find the current value of `bpfDataIfacePattern` in the default [FelixConfiguration](../../reference/resources/felixconfig.mdx).
|
|
||
| Setting an address explicitly stops the kernel from ever reconsidering it. | ||
|
|
||
| Do not use the trunk interface's own MAC address for the bridge. |
There was a problem hiding this comment.
The issue is a little more subtle than that. @aaaaaaaalex explained that not using the trunk's MAC isn't enough on the affected card, you also have to remove the trunk's fdb entry. Seems a bit messy. We might want to name the specific driver and give an explicit workaround for that card (and then drop the general "don't use the trunk's MAC advice" since the trunk's MAC is a good choice if you don't have a buggy driver!)
| ### What $[prodname] does not require | ||
|
|
||
| Just as useful as the required list, and it keeps the required list credible. | ||
| Just as useful as the list above, and it keeps that list credible. |
There was a problem hiding this comment.
Yep, good to tell the reader that we're trying to be credible 😆
| Just as useful as the required list, and it keeps the required list credible. | ||
| Just as useful as the list above, and it keeps that list credible. | ||
|
|
||
| - **Enslaving the trunk.** |
There was a problem hiding this comment.
Hmm, this might be a bug on our side, we really want the admin to configure it so the trunk is already attached when Calico starts
| - **Bringing the bridge up.** | ||
| $[prodname] brings up a bridge that is administratively down. | ||
| - **Self VLAN memberships.** | ||
| $[prodname] never adds or removes the bridge device's own VLAN memberships, or their PVID and untagged flags. |
There was a problem hiding this comment.
I think we add, but don't remove.
| Nothing rejects the name when you create the `Network`, so this is on you to avoid. | ||
|
|
||
| **Spanning Tree Protocol is allowed, but it costs workload startup time.** | ||
| Every new access port waits out a forwarding delay before it passes traffic, which delays every workload attaching to the bridge. |
There was a problem hiding this comment.
I think it's two forwarding delays by default. The forwarding delay can be set to something lower
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