Multi-VRFs documentation by matthewdupre · Pull Request #2665 · tigera/docs

matthewdupre · 2026-04-27T17:53:58Z

Product Version(s):

Issue:

Link to docs preview:

SME review:

An SME has approved this change.

DOCS review:

A member of the docs team has approved this change.

Additional information:

Merge checklist:

Deploy preview inspected wherever changes were made
Build completed successfully
Test have passed

netlify · 2026-04-27T17:54:04Z

✅ Deploy Preview for calico-docs-preview-next ready!

Name	Link
🔨 Latest commit	`103ce1f`
🔍 Latest deploy log	https://app.netlify.com/projects/calico-docs-preview-next/deploys/6a13cdd25469c80008c1f3a8
😎 Deploy Preview	https://deploy-preview-2665--calico-docs-preview-next.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

netlify · 2026-04-27T17:54:05Z

❌ Deploy Preview for tigera failed. Why did it fail? →

Built without sensitive environment variables

Name	Link
🔨 Latest commit	`103ce1f`
🔍 Latest deploy log	https://app.netlify.com/projects/tigera/deploys/6a13cdd29f268a000829018d

ctauchen

@matthewdupre Thanks for this! A few comments, mostly small suggestions.

One general thing we could improve (perhaps before GA), would be to make the full procedure more specific. Much of the procedural content is pretty high-level, leaving users to fill in the details themselves.

I'm happy enough to get this in now for testing and the release. Might be worth chatting about it and revising before GA.

LGTM, with suggestions.

ctauchen · 2026-05-21T15:20:50Z

+  ```
+
+  :::tip
+  On Ubuntu <= 25.04, `apt install linux-generic`.


This < character is killing the build. Suggest you rewrite as follows:

On Ubuntu 25.04 or earlier,

On Ubuntu 25.10 or later,

This does leave me wondering about the .05-.09 releases, for what it's worth.

Ubuntu use a year.month format with 2 releases a year (04 and 10). That said I(/Claude) will just remove these.

ctauchen · 2026-05-21T15:23:11Z

+
+## Big picture
+
+Attach pods to one or more Virtual Routing and Forwarding (VRF) domains


Suggested change

Attach pods to one or more Virtual Routing and Forwarding (VRF) domains

Attach pods to one or more virtual routing and forwarding (VRF) domains

ctauchen · 2026-05-21T15:25:28Z

+- **Reach and be reached from overlapping external IPs.** The same external IP address can be reused
+  in multiple tenant networks outside the cluster. Pods on a VRF can reach the
+  copy of that IP in their own tenant network, and responses come back in the
+  correct VRF.  Services backed by VRF attached pods can also be exported to


Suggested change

correct VRF. Services backed by VRF attached pods can also be exported to

correct VRF. Services backed by VRF attached pods can also be exported to

worth removing all double spaces

ctauchen · 2026-05-21T15:34:42Z

+
+Typically the easiest way to use VRFs will be to attach pods to the flat network
+(with the primary interface), and then whichever VRF networks are required using
+Multus `NetworkAttachmentDefinition`s.  `multus-service` can then be used to


Best to describe generically or use the code as a modifier. Helpful for people not already familiar with what you're referring to.

using Multus network attachment definitions.
using Multus NetworkAttachmentDefinition resources.

Same goes for multus-service and similar cases elsewhere.

ctauchen · 2026-05-21T15:37:30Z

+**Required**
+
+- $[prodname] installed with the **nftables dataplane** (`linuxDataplane: Nftables` in the [Installation](../../reference/installation/api.mdx) resource).
+  The iptables and eBPF dataplanes are not supported in the tech preview, eBPF will be added before GA but iptables support is not planned.


Remove. The first bit is covered in your previous line, and we don't want to be announcing future work. We'll add that when it happens.

ctauchen · 2026-05-21T15:40:39Z

+  ```bash
+  sudo modprobe vrf && lsmod | grep '^vrf '
+  ```
+
+  :::tip
+  On Ubuntu <= 25.04, `apt install linux-generic`.
+  On Ubuntu >= 25.10, the module is built in.
+  On RHEL, the module is built in.
+  :::


I'm inclined to say we can expect people to figure out whether they have this module and to install if necessary. For economy's sake, I'd scrap these lines.

ctauchen · 2026-05-21T15:41:44Z

+  :::
+
+- BGP peering configured between each node and the upstream router on each VRF (see [Create BGPPeers and BGPFilters](#create-bgppeers-and-bgpfilters)).
+- [Multus](./multiple-networks.mdx) installed if you want to attach pods to a VRF using a secondary interface (the most common topology).


Suggested change

- [Multus](./multiple-networks.mdx) installed if you want to attach pods to a VRF using a secondary interface (the most common topology).

- If you want to attach pods to a VRF using a secondary interface (the most common topology), you need to have [Multus](./multiple-networks.mdx) installed on your cluster.

Always best to lead with conditionals.

ctauchen · 2026-05-21T15:42:31Z

+**Recommended**
+
+- Pin `nodeAddressAutodetection` in the [Installation](../../reference/installation/api.mdx) to a specific interface (for example `eth0`) or to `kubernetes: NodeInternalIP`. The default "first found" autodetection can chase a VRF-attached interface when additional interfaces are brought up, breaking the cluster.


This sounds important. Can we just make it a requirement?

ctauchen · 2026-05-21T15:49:52Z

+- **Dataplane**: only the [nftables dataplane](../../operations/nftables.mdx) is supported. iptables and eBPF are not supported.
+- **kube-proxy**: must be in `nftables` mode. `ipvs` mode is **never** supported (this is a permanent restriction, not a tech-preview limitation).


covered already in the requirements section

ctauchen · 2026-05-21T15:51:07Z

+## Requirements
+
+- Linux kernel **5.6 or later** (for the `meta sdifname` nftables match used by VRF policy dispatch).
+- The `vrf` kernel module must be loaded on every node. On Ubuntu this is part of `linux-modules-extra-$(uname -r)`. Confirm with `sudo modprobe vrf && lsmod | grep '^vrf '`.
+- $[prodname] must be installed with `linuxDataplane: Nftables` and kube-proxy must also be in nftables mode.
+- The cluster's [Installation](../installation/api.mdx) should pin `nodeAddressAutodetection` to a specific interface or to `kubernetes: NodeInternalIP`. The default "first found" autodetection can chase a VRF-attached interface and break the cluster when extra interfaces are added.


this is already covered above

Address ctauchen review comment on multi-vrf.mdx:15: > ```suggestion > Attach pods to one or more virtual routing and forwarding (VRF) domains > ``` Resolves tigera#2665 (comment) Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Address ctauchen review comment on multi-vrf.mdx:31: > ```suggestion > correct VRF. Services backed by VRF attached pods can also be exported to > ``` > worth removing all double spaces Applied the suggested fix on line 31 and also collapsed the double-space on line 59 ("`NetworkAttachmentDefinition`s. `multus-service`"). Resolves tigera#2665 (comment) Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Address ctauchen review comment on multi-vrf.mdx:59: > Best to describe generically or use the code as a modifier. Helpful for > people not already familiar with what you're referring to. > > using Multus network attachment definitions. > using Multus `NetworkAttachmentDefinition` resources. > > Same goes for multus-service and similar cases elsewhere. `multus-service` is already code-formatted in this file, so the only edit needed is the NetworkAttachmentDefinition phrasing on line 59. Resolves tigera#2665 (comment) Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Address ctauchen review comment on multi-vrf.mdx:115: > Remove. The first bit is covered in your previous line, and we don't > want to be announcing future work. We'll add that when it happens. Resolves tigera#2665 (comment) Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Address ctauchen review comment on multi-vrf.mdx:116: > Isn't this covered in the first item? Can Calico be in nftables while > kube-proxy is something else? Calico's dataplane and kube-proxy's mode are technically independent knobs, but for multi-VRF both must be nftables. Merging the two bullets keeps both requirements visible without making them look like separate prerequisites. Resolves tigera#2665 (comment) Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

…ments Address ctauchen review comment on multi-vrf.mdx:117: > This is covered already by the general system requirements: > https://docs.tigera.io/calico-enterprise/latest/getting-started/install-on-clusters/requirements#node-requirements Resolves tigera#2665 (comment) Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

…uild) Address ctauchen review comment on multi-vrf.mdx:125: > This `<` character is killing the build. Suggest you rewrite as follows: > > On Ubuntu 25.04 or earlier, > > On Ubuntu 25.10 or later, > > This does leave me wondering about the .05-.09 releases, for what it's worth. Ubuntu does not ship .05-.09 point releases, so the wording covers all Ubuntu versions cleanly. Resolves tigera#2665 (comment) Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Address ctauchen review comment on multi-vrf.mdx:128: > I'm inclined to say we can expect people to figure out whether they > have this module and to install if necessary. For economy's sake, > I'd scrap these lines. Resolves tigera#2665 (comment) Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Address ctauchen review comment on multi-vrf.mdx:131: > ```suggestion > - If you want to attach pods to a VRF using a secondary interface (the most common topology), you need to have [Multus](./multiple-networks.mdx) installed on your cluster. > ``` > Always best to lead with conditionals. Resolves tigera#2665 (comment) Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Address ctauchen review comment on multi-vrf.mdx:135: > This sounds important. Can we just make it a requirement? Moved the `nodeAddressAutodetection` bullet from the **Recommended** section to **Required**, and dropped the now-empty **Recommended** heading. Resolves tigera#2665 (comment) Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Address ctauchen review comment on network.mdx:154: > covered already in the requirements section Removed the kube-proxy bullet from Limitations. The Requirements section already states that kube-proxy must be in nftables mode; the "ipvs is never supported" sub-point (a permanent restriction, not a tech-preview limitation) is folded into that Requirements bullet so it stays documented. Resolves tigera#2665 (comment) Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Address ctauchen review comment on network.mdx:171: > this is already covered above The `nodeAddressAutodetection` recommendation is deployment guidance that belongs in the how-to (Configure multi-VRF networking), not in this API reference page. The how-to lists it as a Required item. Resolves tigera#2665 (comment) Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

…all instructions) Follow-up to the earlier "drop `vrf` kernel module bullet" commit. The full bullet (with the modprobe one-liner and the per-distro tip) was scrapped per ctauchen's suggestion at multi-vrf.mdx:128: > I'm inclined to say we can expect people to figure out whether they > have this module and to install if necessary. For economy's sake, > I'd scrap these lines. Per author follow-up: keep the bare statement that the module must be available — just drop the detection / install instructions. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Follow-up to the earlier "drop duplicated kube-proxy limitation" commit on network.mdx, which folded an `ipvs is never supported` parenthetical into the Requirements bullet. Per author follow-up: drop it. `ipvs` is only minimally supported elsewhere in the product, and requiring nftables mode already implies "not ipvs", so the parenthetical adds noise without information. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

matthewdupre · 2026-05-25T04:21:03Z

@ctauchen thanks! Markups made. I've left them as separate commits (I like reviewing Claude better that way), but we should definitely squash before merging!

Claude WIP

e6f81ae

Copilot AI review requested due to automatic review settings April 27, 2026 17:53

matthewdupre added the [DON'T MERGE] Author wants to postpone the merge label Apr 27, 2026

matthewdupre changed the title ~~[Do not merge] Multi-VRFs documentation~~ [Not ready for review] Multi-VRFs documentation Apr 27, 2026

matthewdupre added 3 commits May 6, 2026 13:24

Claude markups

0d9f479

WIP markups

a358661

Couple more markups

b975dd7

matthewdupre removed the [DON'T MERGE] Author wants to postpone the merge label May 20, 2026

matthewdupre marked this pull request as ready for review May 20, 2026 12:46

matthewdupre requested a review from a team as a code owner May 20, 2026 12:46

matthewdupre changed the title ~~[Not ready for review] Multi-VRFs documentation~~ Multi-VRFs documentation May 20, 2026

ctauchen reviewed May 21, 2026

View reviewed changes

matthewdupre and others added 14 commits May 24, 2026 21:05


		## Big picture

		Attach pods to one or more Virtual Routing and Forwarding (VRF) domains

	correct VRF. Services backed by VRF attached pods can also be exported to
	correct VRF. Services backed by VRF attached pods can also be exported to

	- [Multus](./multiple-networks.mdx) installed if you want to attach pods to a VRF using a secondary interface (the most common topology).
	- If you want to attach pods to a VRF using a secondary interface (the most common topology), you need to have [Multus](./multiple-networks.mdx) installed on your cluster.

		Recommended

		- Pin `nodeAddressAutodetection` in the [Installation](../../reference/installation/api.mdx) to a specific interface (for example `eth0`) or to `kubernetes: NodeInternalIP`. The default "first found" autodetection can chase a VRF-attached interface when additional interfaces are brought up, breaking the cluster.

		- Dataplane: only the [nftables dataplane](../../operations/nftables.mdx) is supported. iptables and eBPF are not supported.
		- kube-proxy: must be in `nftables` mode. `ipvs` mode is never supported (this is a permanent restriction, not a tech-preview limitation).

Conversation

matthewdupre commented Apr 27, 2026

Uh oh!

netlify Bot commented Apr 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for calico-docs-preview-next ready!

Uh oh!

netlify Bot commented Apr 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

❌ Deploy Preview for tigera failed. Why did it fail? →

Uh oh!

ctauchen left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

matthewdupre commented May 25, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

netlify Bot commented Apr 27, 2026 •

edited

Loading

netlify Bot commented Apr 27, 2026 •

edited

Loading