fix: add small guide for ctrl as VM in libvirt

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

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
 
@@ -95,7 +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
 
@@ -130,6 +130,7 @@ 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.
 
+
 ### 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.

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
+    <os firmware='efi'>
+      <firmware>
+        <feature enabled='no' name='secure-boot'/>
+      </firmware>
+    </os>
+    ```
+
+- 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)