From 5d0bb6a711c03e93b49501cc37d7ca4223047f20 Mon Sep 17 00:00:00 2001 From: Logan Blyth Date: Mon, 13 Jul 2026 17:08:53 -0400 Subject: [PATCH 1/5] fix: add small guide for ctrlr as VM Signed-off-by: Logan Blyth --- docs/install-upgrade/install.md | 26 +++++++++++++++++++++++++- 1 file changed, 25 insertions(+), 1 deletion(-) diff --git a/docs/install-upgrade/install.md b/docs/install-upgrade/install.md index ff4d721c..3d8e7426 100644 --- a/docs/install-upgrade/install.md +++ b/docs/install-upgrade/install.md @@ -95,7 +95,10 @@ There are utilities that assist this process such as [etcher](https://etcher.bal ## Install Control Node -This control node should be given a static IP address. Either a lease or statically assigned. +This control node should be given a static IP address. Either a lease or +statically assigned. Running the control node as a virtual machine isn't +officially supported but there are recommendations [in this +section](#controller-as-virtual-machine). 1. Configure the server to use UEFI boot **without** secure boot @@ -130,6 +133,27 @@ interface. It runs a DHCP server, as well as a small HTTP server. The `external` network allows the user to access the control node via their local IT network. It provides SSH access to the host operating system on the control node. +### Controller as Virtual Machine + +These instructions are provided for `libvirt`, adapt as needed for the chosen +hypervisor: + +- Ensure the hardware specs match [the control node](./requirements.md#control-node) +- Disable secure boot: +```xml + + + + + +``` +- Configure the `efi` firmware and `q35` machine type +- Configure the virtual machine for auto start when the host system boots up. +- Configure both NICs as `virtio` +- Ensure a console device is present +- Use VirtIO devices wherever possible + + ### Fabric Manages Switches Now that the install has finished, you can start interacting with the Fabric using `kubectl`, `kubectl fabric` and `k9s`, all pre-installed as part of the Control Node installer. From b30451957a012be7a21f2075ce7f21e9cd5da19a Mon Sep 17 00:00:00 2001 From: Logan Blyth Date: Tue, 21 Jul 2026 10:30:21 -0400 Subject: [PATCH 2/5] feat(guest agent): link to flatcar docs on guest agent Signed-off-by: Logan Blyth --- docs/install-upgrade/install.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/install-upgrade/install.md b/docs/install-upgrade/install.md index 3d8e7426..fb0b68a5 100644 --- a/docs/install-upgrade/install.md +++ b/docs/install-upgrade/install.md @@ -152,6 +152,9 @@ hypervisor: - Configure both NICs as `virtio` - Ensure a console device is present - Use VirtIO devices wherever possible +- The qemu guest agent is built into the flatcar image, create a virtio-port + with the name `org.qemu.guest_agent.0`. More information is on the [flatcar +website](https://www.flatcar.org/docs/latest/os-config/network/acpi/?highlight=guest#qemu-guest-agent) ### Fabric Manages Switches From 3ab650defdb08e3228b35b57523ae01b79f91636 Mon Sep 17 00:00:00 2001 From: Logan Blyth Date: Wed, 29 Jul 2026 14:39:59 -0400 Subject: [PATCH 3/5] chore: move vm info to dedicated page Signed-off-by: Logan Blyth --- docs/install-upgrade/.pages | 1 + docs/install-upgrade/install.md | 27 +------------ docs/install-upgrade/virtual-machines.md | 49 ++++++++++++++++++++++++ 3 files changed, 51 insertions(+), 26 deletions(-) create mode 100644 docs/install-upgrade/virtual-machines.md diff --git a/docs/install-upgrade/.pages b/docs/install-upgrade/.pages index 6842624c..f0c8d8f4 100644 --- a/docs/install-upgrade/.pages +++ b/docs/install-upgrade/.pages @@ -4,5 +4,6 @@ nav: - System Requirements: requirements.md - Build Wiring Diagram: build-wiring.md - Fabric Configuration: config.md + - Virtual Machines: virtual-machines.md - ... - Upgrade: upgrade.md diff --git a/docs/install-upgrade/install.md b/docs/install-upgrade/install.md index fb0b68a5..bac31cf9 100644 --- a/docs/install-upgrade/install.md +++ b/docs/install-upgrade/install.md @@ -96,9 +96,7 @@ There are utilities that assist this process such as [etcher](https://etcher.bal ## Install Control Node This control node should be given a static IP address. Either a lease or -statically assigned. Running the control node as a virtual machine isn't -officially supported but there are recommendations [in this -section](#controller-as-virtual-machine). +statically assigned. 1. Configure the server to use UEFI boot **without** secure boot @@ -133,29 +131,6 @@ interface. It runs a DHCP server, as well as a small HTTP server. The `external` network allows the user to access the control node via their local IT network. It provides SSH access to the host operating system on the control node. -### Controller as Virtual Machine - -These instructions are provided for `libvirt`, adapt as needed for the chosen -hypervisor: - -- Ensure the hardware specs match [the control node](./requirements.md#control-node) -- Disable secure boot: -```xml - - - - - -``` -- Configure the `efi` firmware and `q35` machine type -- Configure the virtual machine for auto start when the host system boots up. -- Configure both NICs as `virtio` -- Ensure a console device is present -- Use VirtIO devices wherever possible -- The qemu guest agent is built into the flatcar image, create a virtio-port - with the name `org.qemu.guest_agent.0`. More information is on the [flatcar -website](https://www.flatcar.org/docs/latest/os-config/network/acpi/?highlight=guest#qemu-guest-agent) - ### Fabric Manages Switches diff --git a/docs/install-upgrade/virtual-machines.md b/docs/install-upgrade/virtual-machines.md new file mode 100644 index 00000000..e50f7e1d --- /dev/null +++ b/docs/install-upgrade/virtual-machines.md @@ -0,0 +1,49 @@ +# Virtual Machines + +!!! warning "Not officially supported" + Hedgehog does not officially support running control or gateway nodes as + virtual machines. + +The examples on this page use libvirt/QEMU. The underlying requirements — UEFI +without secure boot, VirtIO devices, and PCI passthrough for gateway data-plane +NICs — apply to any hypervisor. + +## Common Settings + +These apply to both control and gateway nodes. + +- Use the `q35` machine type with `efi` firmware. Only UEFI boot is supported. +- Disable secure boot: + + ```xml + + + + + + ``` + +- Use VirtIO devices wherever possible. +- Attach a console device. +- Enable autostart so the VM starts with the host. +- The QEMU guest agent is built into the Flatcar image. To use it, add a + virtio-serial port named `org.qemu.guest_agent.0`. See the + [Flatcar documentation](https://www.flatcar.org/docs/latest/os-config/network/acpi/?highlight=guest#qemu-guest-agent) + for details. + +## Control Node + +- Size the VM to meet or exceed [the control node requirements](./requirements.md#control-node). +- Configure both NICs as `virtio`: one for the outside world, one for the + out-of-band management network of the fabric switches. + +## Gateway Node + +- There are no minimum performance guarantees when the gateway is in a VM. +- Size the VM to meet or exceed [the gateway node requirements](./requirements.md#gateway-node). +- Configure the management NIC as `virtio`. +- Use PCI passthrough — not SR-IOV — for the data-plane NICs. Passthrough + usually requires host-side configuration (IOMMU, driver binding) before the + device can be attached: + - [RHEL passthrough documentation](https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/10/html/configuring_and_managing_linux_virtual_machines/attaching-host-devices-to-virtual-machines#attaching-pci-devices-to-virtual-machines-by-using-the-command-line) + - [Ubuntu passthrough documentation](https://ubuntu.com/server/docs/how-to/virtualisation/libvirt/#device-passthrough-hotplug) From 9c2d4a42b6e3817145c0ffb6f2053365a3827112 Mon Sep 17 00:00:00 2001 From: Logan Blyth Date: Wed, 29 Jul 2026 15:37:32 -0400 Subject: [PATCH 4/5] chore: link to virtual machine page Signed-off-by: Logan Blyth --- docs/install-upgrade/install.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/install-upgrade/install.md b/docs/install-upgrade/install.md index bac31cf9..09573ec2 100644 --- a/docs/install-upgrade/install.md +++ b/docs/install-upgrade/install.md @@ -11,7 +11,7 @@ !!! tip "Control nodes on virtual machines" Running control nodes on virtual machines is possible, although not officially supported. If you use virtual - machines, make sure to use UEFI boot. + machines, make sure to use UEFI boot. See [Virtual Machines](./virtual-machines.md) for the required settings. ## Overview of Install Process From ed4a9bf4d7065aeb208a136e34704a7141be517a Mon Sep 17 00:00:00 2001 From: Logan Blyth Date: Wed, 29 Jul 2026 17:08:29 -0400 Subject: [PATCH 5/5] chore: improve grammar Signed-off-by: Logan Blyth --- docs/install-upgrade/install.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/install-upgrade/install.md b/docs/install-upgrade/install.md index 09573ec2..895ea45a 100644 --- a/docs/install-upgrade/install.md +++ b/docs/install-upgrade/install.md @@ -95,8 +95,7 @@ There are utilities that assist this process such as [etcher](https://etcher.bal ## Install Control Node -This control node should be given a static IP address. Either a lease or -statically assigned. +The control node should be given a static IP address or a DHCP reservation. 1. Configure the server to use UEFI boot **without** secure boot