DOCS-2997: Write the guide for connecting workloads to a VLAN - #2947
Open
ctauchen wants to merge 1 commit into
Open
DOCS-2997: Write the guide for connecting workloads to a VLAN#2947ctauchen wants to merge 1 commit into
ctauchen wants to merge 1 commit into
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. |
Contributor
There was a problem hiding this comment.
Pull request overview
Adds the main “connect workloads to a VLAN” setup guide for Calico Enterprise L2 bridge networking (Calico-managed bridge), covering prerequisites, configuration steps, and verification for both KubeVirt VMs (primary path) and pods (secondary path).
Changes:
- Expands the guide with explicit prerequisites and a required “MultiInterfaceMode=Multus” configuration step.
- Documents end-to-end resource setup: IPPools (L2Workload),
Network(managed bridge + trunk + VLAN/subnets), and per-VLANNetworkAttachmentDefinition. - Adds workload attachment examples (KubeVirt VM spec + pod Multus annotations) and a structured verification checklist.
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Comment on lines
+16
to
+18
| If the only uplink on your nodes also carries the node's own IP address, $[prodname] | ||
| cannot create the bridge. Start with [Prepare an existing bridge](byo-bridge.mdx), then | ||
| return here from step 3 onwards. |
Comment on lines
+331
to
+333
| A workload can take an L2 network as its primary interface instead of an additional one, | ||
| set with annotations rather than through Multus. See the | ||
| [Network resource](../../reference/resources/network.mdx) for the annotations. |
ctauchen
force-pushed
the
DOCS-2997-5-connect-vlan
branch
from
August 21, 2026 11:08
f5dd80b to
ddd7e3a
Compare
Fill in the main setup guide for L2 bridge networking, for nodes where Calico can take over an interface of its own. The guide leads with VMs, because the feature is aimed at them and because a VM is configured differently from a pod. The interface is declared in the VM specification, and the guide says plainly that the launcher pod is not annotated by hand. Pods follow as a secondary case. Setting the multi-interface mode gets a step of its own. Installing Multus is not sufficient, nothing reports the omission, and the symptom appears much later as a workload with two interfaces called eth0 and no connectivity. The IP pool step explains why the pool is marked as an L2 workload pool, since the consequence of leaving it out is a blackhole route and a BGP advertisement for addresses that live on the reader's own VLAN. The guide also notes that KubeVirt's bridge interface binding is unrelated to the Calico L2 bridge, because the same word means two different things in adjacent configuration. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
ctauchen
force-pushed
the
DOCS-2997-5-connect-vlan
branch
from
August 21, 2026 11:10
ddd7e3a to
34d01e5
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 (4)
calico-enterprise/networking/l2-bridge/connect-vlan.mdx:17
- The text says to return here “from step 3 onwards”, but the linked “Prepare an existing bridge” page currently has no numbered steps, so readers won’t know what “step 3” refers to.
If the only uplink on your nodes also carries the node's own IP address, $[prodname] cannot create the bridge.
calico-enterprise/networking/l2-bridge/connect-vlan.mdx:318
- This section sends readers to the generic Network resource reference for the primary-interface annotations, but that reference page currently documents only VRF networks and states that only
vrfis supported. That makes it a confusing reference for L2 bridge users.
A workload can take an L2 network as its primary interface instead of an additional one, set with annotations rather than through Multus.
See the [Network resource](../../reference/resources/network.mdx) for the annotations.
calico-enterprise/networking/l2-bridge/connect-vlan.mdx:32
- This sentence points readers to “L2 bridge support and limitations” for the “full set of constraints”, but
calico-enterprise/reference/l2-bridge-support.mdxis currently just an outline (headings only). As written, this over-promises content that isn’t there yet.
calico-enterprise/networking/l2-bridge/connect-vlan.mdx:97 - The guide introduces
allowedUses: [L2Workload], butcalico-enterprise/reference/resources/ippool.mdxdoes not listL2Workloadas an acceptedallowedUsesvalue (it currently lists Workload/Tunnel/HostSecondaryInterface/LoadBalancer). This mismatch is likely to confuse readers or make them think the example is invalid.
spec:
cidr: 10.10.0.0/24
allowedUses:
- L2Workload
disableBGPExport: true
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/connect-vlan.mdx:33
- This sentence claims the linked page contains the full set of constraints, but
calico-enterprise/reference/l2-bridge-support.mdxcurrently appears to be a stub (headings only). That makes this wording misleading for readers; either populate the target page in this PR sequence or soften the claim here.
For the full set of constraints, see [L2 bridge support and limitations](../../reference/l2-bridge-support.mdx).
calico-enterprise/networking/l2-bridge/connect-vlan.mdx:318
- This section says primary-interface attachment is done "with annotations" but doesn’t name the annotation key, even though it’s already documented in
calico-enterprise/reference/resources/network.mdx. Naming the key here would make this step actionable without forcing readers to context-switch.
A workload can take an L2 network as its primary interface instead of an additional one, set with annotations rather than through Multus.
See the [Network resource](../../reference/resources/network.mdx) for the annotations.
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 main setup guide for L2 bridge networking. Fifth in the DOCS-2997 sequence. It follows the guide for preparing an existing bridge, because a reader on a shared uplink needs that first.
This is the path for nodes where Calico can take over an interface of its own, so Calico creates and owns the bridge.
The guide leads with VMs. The feature is aimed at them, and a VM is configured differently from a pod: the interface is declared in the VM specification, and the guide says plainly that the launcher pod KubeVirt creates is not annotated by hand. Pods follow as the secondary case.
Points worth a reviewer's attention:
Three things I could not verify and would like checked:
Changed page: https://deploy-preview-2947--calico-docs-preview-next.netlify.app/calico-enterprise/next/networking/l2-bridge/connect-vlan