Skip to content

doc/reference/requirements: Document the vxlan module requirement - #1623

Open
wak327 wants to merge 2 commits into
canonical:mainfrom
wak327:doc-raspberry-pi-vxlan
Open

wak327 wants to merge 2 commits into
canonical:mainfrom
wak327:doc-raspberry-pi-vxlan

Conversation

@wak327

@wak327 wak327 commented Oct 22, 2026 •

Copy link
Copy Markdown
Contributor

Fixes #143

When MicroOVN isn't used, MicroCloud falls back to the Ubuntu fan (lxdfan0 with bridge.mode=fan), which needs the vxlan kernel module. On systems without that module, for example some Raspberry Pi kernels, creating the fan network fails after initialization:

Error: Failed adding link: Failed to run: ip link add name lxdfan0-fan type vxlan ...: exit status 2 (Error: Unknown device type.)

This adds the vxlan kernel module to the software requirements, as a hint for users who run into this. How to provide the module is left to the user, since it depends on the platform.

Checklist

@github-actions github-actions Bot added the Documentation Documentation needs updating label Oct 22, 2026
@wak327

wak327 commented Oct 22, 2026

Copy link
Copy Markdown
Contributor Author

@roosterfish @elijahgreenstein a small docs addition, could you take a look when you have a moment?

@elijahgreenstein elijahgreenstein left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@wak327 thank you for your contribution. While you've provided useful details in this PR, my preference would be to provide general requirements in the documentation (in this case the vxlan kernel module) and leave it to users to determine how to meet those requirements. See my comment below.

Comment thread doc/reference/requirements.md Resolved
@wak327
wak327 force-pushed the doc-raspberry-pi-vxlan branch from 435de48 to f8fe405 Compare October 22, 2026 20:45
@wak327 wak327 changed the title doc/reference/requirements: Document the vxlan module requirement on Raspberry Pi doc/reference/requirements: Document the vxlan module requirement Oct 22, 2026
@wak327

wak327 commented Oct 22, 2026

Copy link
Copy Markdown
Contributor Author

@roosterfish following @elijahgreenstein's suggestion, this now only adds the vxlan kernel module requirement to the software requirements, without the Raspberry Pi specific steps. Could you take a look?

@elijahgreenstein elijahgreenstein left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

Comment thread doc/reference/requirements.md Resolved
@wak327

wak327 commented Oct 29, 2026

Copy link
Copy Markdown
Contributor Author

@roosterfish thanks for the review, I've addressed your comments. Could you take another look?

@elijahgreenstein elijahgreenstein left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

Comment thread doc/reference/requirements.md Resolved
Signed-off-by: Waleed Khalid <wak327@gmail.com>
Signed-off-by: Waleed Khalid <wak327@gmail.com>
@wak327
wak327 force-pushed the doc-raspberry-pi-vxlan branch from a749a1d to ca9a973 Compare October 30, 2026 17:10
@wak327

wak327 commented Oct 30, 2026

Copy link
Copy Markdown
Contributor Author

@elijahgreenstein @roosterfish I applied the latest suggestions. Could you take another look?


If you intend to use ZFS storage, use a non-HWE (Hardware Enabled) variant of Ubuntu 22.04.

If you do not set up distributed networking with MicroOVN, MicroCloud falls back on the Ubuntu Fan for networking (see {ref}`exp-networking-ovn-alternatives`), which requires the `vxlan` kernel module.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@elijahgreenstein is it "on Ubuntu Fan" or "on the Ubuntu Fan"? I would guess the first.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@roosterfish -- I don't think there's clear standard here, since I haven't seen that much writing on "the Ubuntu Fan" in other documentation or Ubuntu/Canonical pages. Elsewhere in the MicroCloud docs, though, we have "fall back on the Ubuntu Fan" (alternatives), and in the LXD docs on networking setups, we have "possibly in connection with the Ubuntu Fan," which links to an old video titled "Easy overlay networking in LXD with the Ubuntu Fan". Given that, I think we can leave the definite article in, as "on the Ubuntu Fan." If you prefer "on Ubuntu Fan", though, I'm not opposed to updating elsewhere in the docs too.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Documentation Documentation needs updating

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Docs: List extra requirements for use with Raspberry Pi

3 participants