Skip to content

DOCS-2997: Point existing pages at L2 bridge networking #2951

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
ctauchen wants to merge 5 commits into
base: main
Choose a base branch
from
Open

DOCS-2997: Point existing pages at L2 bridge networking #2951

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
c91e292
DOCS-2997: Point existing pages at L2 bridge networking
ctauchen Aug 21, 2026
64d1973
DOCS-2997: Update the link text for the VM IP and MAC guide
ctauchen Aug 27, 2026
ba801a1
DOCS-2997: Add L2Workload to the IPPool allowed uses
ctauchen Aug 27, 2026
777e704
DOCS-2997: Keep Additional resources last on two pages
ctauchen Aug 27, 2026
a69ec26
DOCS-2997: Explain L2Workload, and align the kernel statement
ctauchen Aug 27, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions calico-enterprise/networking/configuring/multiple-networks.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -249,3 +249,8 @@ spec:
- kns.default
- ksa.default.default
```

## L2 bridge networks

To attach a workload to one of your existing VLANs rather than to another routed network, see [L2 bridge networking](../l2-bridge/about-l2-bridge.mdx).
It uses Multus in the same way, and additionally requires `multiInterfaceMode: Multus` in the [Installation](../../reference/installation/api.mdx) resource.
10 changes: 10 additions & 0 deletions calico-enterprise/networking/configuring/pod-mac-address.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,3 +33,13 @@ Annotate the pod with cni.projectcalico.org/hwAddr set to the desired MAC addres
```

The annotation must be present when the pod is created; adding it later has no effect.

## Setting the MAC address on other interfaces

The annotation above applies to a pod's primary interface.
To set the MAC address on an additional interface, prefix the annotation with the interface name — for example, `cni.projectcalico.org/vlan10.hwAddr`.

For a KubeVirt VM, prefer KubeVirt's own `macAddress` field on the interface.
$[prodname] honors it, and it keeps the setting with the rest of the interface configuration.
If you set both the field and the annotation, they must agree, or the interface is rejected.
See [Set a VM's IP and MAC address](../l2-bridge/vm-identity.mdx).
9 changes: 9 additions & 0 deletions calico-enterprise/networking/ipam/use-specific-ip.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -60,6 +60,15 @@ tunnel address. To prevent this, there are several options:
- To prevent $[prodname] from using IPs from a certain pool for internal IPIP and/or VXLAN tunnel addresses, you
can set the `allowedUses` field on the [IP Pool](../../reference/resources/ippool.mdx) to `["Workload"]`.

## Requesting an address on another interface

The annotations above apply to a pod's primary interface.
To request an address on an additional interface, prefix the annotation with the interface name — for example, `cni.projectcalico.org/vlan10.ipAddrs`.

For a workload on an [L2 bridge network](../l2-bridge/about-l2-bridge.mdx), use `ipAddrs` rather than `ipAddrsNoIpam`.
Bypassing IPAM leaves $[prodname] without a record of the address, and on an L2 network that record is what lets $[prodname] tell the workload's own traffic from spoofed traffic.
See [Set a VM's IP and MAC address](../l2-bridge/vm-identity.mdx).

## Additional resources

For help configuring $[prodname] CNI and $[prodname] IPAM, see [Configuring the $[prodname] CNI Plugins](../../reference/component-resources/configuration.mdx).
15 changes: 13 additions & 2 deletions calico-enterprise/networking/kubevirt/kubevirt-networking.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,14 @@ $[prodname]'s KubeVirt support ensures that:

### Supported networking mode: bridge

:::note

The **bridge** on this page is KubeVirt's interface binding mode, which connects a VM to its own pod's interface on the $[prodname] pod network.
It is unrelated to [L2 bridge networking](../l2-bridge/about-l2-bridge.mdx), which puts workloads on your existing VLANs through a Linux bridge on the node.
The two features use the same word for different things.

:::

$[prodname] supports KubeVirt live migration using the **bridge** binding mode. In bridge mode,
the VM is connected to the pod network through a Linux bridge, and the VM uses the same IP address
that $[prodname] assigns to the pod. This is required because:
Expand All @@ -42,8 +50,11 @@ policy enforcement.

### BGP networking required

Live migration currently requires BGP networking without overlay. Overlay networking (VXLAN, IP-in-IP)
support is planned for a future release.
Live migration on the $[prodname] pod network, as described on this page, currently requires BGP networking without overlay.
Overlay networking (VXLAN, IP-in-IP) support is planned for a future release.

This requirement applies to the pod network path only.
Live migration of a VM on an [L2 bridge network](../l2-bridge/about-l2-bridge.mdx) does not depend on BGP, because the VM's address is reachable on your own VLAN rather than routed by $[prodname].
Comment on lines +56 to +57

### KubeVirt VM IP address persistence

Expand Down
5 changes: 5 additions & 0 deletions calico-enterprise/operations/ebpf/use-cases-ebpf.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -90,6 +90,11 @@ Is eBPF a replacement for iptables? Not exactly. It’s hard to imagine everythi

We believe the right solution is to leverage eBPF, along with existing mechanisms in the Linux kernel, to achieve your desired outcome. That’s why $[prodname] offers support for multiple data planes, including standard Linux, Windows HNS, and Linux eBPF. Since we have established that both eBPF and iptables are useful, the only logical thing to do in our opinion is to support both. $[prodname] gives you the choice so you can choose the best tool for the job.

## L2 bridge networking

[L2 bridge networking](../../networking/l2-bridge/about-l2-bridge.mdx) requires the eBPF data plane.
Enforcing policy on a bridged, VLAN-tagged segment is not possible with the iptables data plane. That feature also needs a kernel supporting the bridge port `locked` flag, which arrived upstream in 5.18 and is backported by some distributions.

## Additional resources

To learn more and see performance metrics from our test environment, see the blog, [Introducing the eBPF data plane](https://www.projectcalico.org/introducing-the-calico-ebpf-dataplane/).
4 changes: 3 additions & 1 deletion calico-enterprise/reference/resources/ippool.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -49,7 +49,7 @@
| disabled | When set to true, $[prodname] IPAM will not assign addresses from this pool. | true, false | boolean | `false` |
| disableBGPExport _(since v3.11.0)_ | Disable exporting routes from this IP Pool’s CIDR over BGP. | true, false | boolean | `false` |
| nodeSelector | Selects the nodes where $[prodname] IPAM should assign pod addresses from this pool. Can be overridden if a pod [explicitly identifies this IP pool by annotation](../component-resources/configuration.mdx#using-kubernetes-annotations). | | [selector](#node-selector) | all() |
| allowedUses _(since v3.11.0)_ | Controls whether the pool will be used for automatic assignments of certain types. See [below](#allowed-uses). | Workload, Tunnel, HostSecondaryInterface, LoadBalancer | list of strings | `["Workload", "Tunnel"]` |
| allowedUses _(since v3.11.0)_ | Controls whether the pool will be used for automatic assignments of certain types. See [below](#allowed-uses). | Workload, Tunnel, HostSecondaryInterface, LoadBalancer, L2Workload | list of strings | `["Workload", "Tunnel"]` |

Check failure on line 52 in calico-enterprise/reference/resources/ippool.mdx

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'allowedUses'?

Raw Output:
{"message":"[Vale.Spelling] Did you really mean 'allowedUses'?","location":{"path":"calico-enterprise/reference/resources/ippool.mdx","range":{"start":{"line":52,"column":3},"end":{"line":52,"column":14}}},"severity":"ERROR","code":{"value":"Vale.Spelling"}}
| awsSubnetID _(since v3.11.0)_ | May be set to the ID of an AWS VPC Subnet that contains the CIDR of this IP pool to activate the AWS-backed pool feature. See [below](#aws-backed-pools). | Valid AWS Subnet ID. | string | |
| assignmentMode | Controls whether the pool will be used for automatic assignments or only if requested manually | Automatic, Manual | strings | `Automatic` |

Expand All @@ -66,13 +66,15 @@
When automatically assigning IP addresses to workloads, only pools with "Workload" in their `allowedUses` field are
consulted. Similarly, when assigning IPs for tunnel devices, only "Tunnel" pools are eligible. Finally, when
assigning IP addresses for AWS secondary ENIs, only pools with allowed use "HostSecondaryInterface" are candidates.
Pools marked "L2Workload" are used for workloads attached to an [L2 bridge network](../../networking/l2-bridge/about-l2-bridge.mdx), whose addresses live on a VLAN outside the cluster rather than on the pod network. Marking a pool this way also stops $[prodname] programming a blackhole route for it and advertising it over BGP, neither of which is correct for those addresses.

Combining options for the `allowedUses` field is limited. You can specify only the following options and option combinations:
* `allowedUses: ["Tunnel","Workload"]` (default)
* `allowedUses: ["Tunnel"]`
* `allowedUses: ["Workload"]`
* `allowedUses: ["LoadBalancer"]`
* `allowedUses: ["HostSecondaryInterface"]`
* `allowedUses: ["L2Workload"]`

If the `allowedUses` field is not specified, it defaults to `["Workload", "Tunnel"]` for compatibility with older
versions of Calico. It is not possible to specify a pool with no allowed uses.
Expand Down