docs: Update documentation for vfkit hypervisor support

Updates all documentation to reflect the addition of vfkit as a new
hypervisor option for running MicroVMs on macOS.

Changes:
- Add vfkit to hypervisor comparison table with its restrictions
- Update intro and README to mention macOS support
- Document vfkit's user-mode (NAT) networking support
- Note that vfkit has built-in virtiofs (no separate virtiofsd needed)
- Add vfkit-specific configuration options to options table
- Include vfkit-example in the examples section

Author: luizribeiro

README.md

@@ -14,7 +14,7 @@
 </p>
 
 A Nix Flake to build NixOS and run it on one of several Type-2
-Hypervisors on NixOS/Linux. The project is intended to provide a more
+Hypervisors on NixOS/Linux or macOS. The project is intended to provide a more
 isolated alternative to `nixos-container`. You can either build and
 run MicroVMs like Nix packages, or alternatively install them as
 systemd services declaratively in your host's Nix Flake or
@@ -26,8 +26,8 @@ imperatively with the provided `microvm` command.
 
 - MicroVMs are Virtual Machines but use special device interfaces
   (virtio) for high performance.
-- This project runs them on NixOS hosts.
-- You can choose one of five hypervisors for each MicroVM.
+- This project runs them on NixOS/Linux hosts and macOS (via vfkit).
+- You can choose from eight hypervisors for each MicroVM.
 - MicroVMs have a fixed RAM allocation (default: 512 MB) but can be
   shrunk using `microvm-balloon`
 - MicroVMs have a read-only root disk with either a prepopulated
@@ -40,20 +40,21 @@ imperatively with the provided `microvm` command.
   a block device, or alternatively as a shared directory hierarchy
   through *9p* or *virtiofs*.
 - Zero, one, or more virtual tap ethernet network interfaces can be
-  attached to a MicroVM. `qemu` and `kvmtool` also support *user*
+  attached to a MicroVM. `qemu`, `kvmtool`, and `vfkit` also support *user*
   networking which requires no additional setup on the host.
 
 ## Hypervisors
 
-| Hypervisor                                                              | Language | Restrictions                             |
-|-------------------------------------------------------------------------|----------|------------------------------------------|
-| [qemu](https://www.qemu.org/)                                           | C        |                                          |
-| [cloud-hypervisor](https://www.cloudhypervisor.org/)                    | Rust     | no 9p shares                             |
-| [firecracker](https://firecracker-microvm.github.io/)                   | Rust     | no 9p/virtiofs shares                    |
-| [crosvm](https://chromium.googlesource.com/chromiumos/platform/crosvm/) | Rust     | 9p shares broken                         |
-| [kvmtool](https://github.com/kvmtool/kvmtool)                           | C        | no virtiofs shares, no control socket    |
-| [stratovirt](https://github.com/openeuler-mirror/stratovirt)            | Rust     | no 9p/virtiofs shares, no control socket |
-| [alioth](https://github.com/google/alioth)                              | Rust     | no virtiofs shares, no control socket    |
+| Hypervisor                                                              | Language | Restrictions                                          |
+|-------------------------------------------------------------------------|----------|-------------------------------------------------------|
+| [qemu](https://www.qemu.org/)                                           | C        |                                                       |
+| [cloud-hypervisor](https://www.cloudhypervisor.org/)                    | Rust     | no 9p shares                                          |
+| [firecracker](https://firecracker-microvm.github.io/)                   | Rust     | no 9p/virtiofs shares                                 |
+| [crosvm](https://chromium.googlesource.com/chromiumos/platform/crosvm/) | Rust     | 9p shares broken                                      |
+| [kvmtool](https://github.com/kvmtool/kvmtool)                           | C        | no virtiofs shares, no control socket                 |
+| [stratovirt](https://github.com/openeuler-mirror/stratovirt)            | Rust     | no 9p/virtiofs shares, no control socket              |
+| [alioth](https://github.com/google/alioth)                              | Rust     | no virtiofs shares, no control socket                 |
+| [vfkit](https://github.com/crc-org/vfkit)                               | Go       | macOS only, no 9p shares, no tap/bridge networking    |
 
 
 ## Installation
@@ -85,6 +86,9 @@ nix run microvm#cloud-hypervisor-example
 nix run microvm#crosvm-example
 nix run microvm#kvmtool-example
 nix run microvm#stratovirt-example
+
+# On macOS only:
+nix run microvm#vfkit-example
 ```
 
 ### Run a MicroVM example with nested MicroVMs on 5 different Hypervisors

doc/src/interfaces.md

@@ -20,12 +20,15 @@ configuration:
 
 ## `type = "user"`
 
-User-mode networking is only provided by qemu and kvmtool, providing
+User-mode networking is provided by qemu, kvmtool, and vfkit, providing
 outgoing connectivity to your MicroVM without any further setup.
 
 As kvmtool seems to lack a built-in DHCP server, additional static IP
 configuration is necessary inside the MicroVM.
 
+**Note:** vfkit (macOS) only supports user-mode networking. TAP and bridge
+networking are not available.
+
 ## `type = "tap"`
 
 Use a virtual tuntap Ethernet interface. Its name is the value of

doc/src/intro.md

@@ -1,9 +1,9 @@
 # Intro
 
 **microvm.nix** is a Flake to run lightweight NixOS virtual machines
-on NixOS. Starting with the reasons why for the remainder of this
+on NixOS and macOS. Starting with the reasons why for the remainder of this
 chapter, this handbook guides you through the provisioning of MicroVMs
-on your NixOS machine.
+on your NixOS or macOS machine.
 
 ## Compartmentalization
 
@@ -47,4 +47,5 @@ overhead has been reduced a lot by replacing emulated devices with
 This Flake offers you to run your MicroVMs not only on QEMU but with
 other Hypervisors that have been explicitly authored for
 *virtio*. Some of them are written in Rust, a programming language
-that is renowned for being safer than C.
+that is renowned for being safer than C. On macOS, vfkit leverages
+Apple's native Virtualization.framework for running Linux VMs.

doc/src/options.md

@@ -15,6 +15,8 @@ available for customization. These are the most important ones:
 | `microvm.socket`               | Control socket for the Hypervisor so that a MicroVM can be shutdown cleanly                         |
 | `microvm.user`                 | (qemu only) User account which Qemu will switch to when started as root                             |
 | `microvm.forwardPorts`         | (qemu user-networking only) TCP/UDP port forwarding                                                 |
+| `microvm.vfkit.extraArgs`      | (vfkit only) Extra arguments to pass to vfkit                                                       |
+| `microvm.vfkit.logLevel`       | (vfkit only) Log level: "debug", "info", or "error" (default: "info")                              |
 | `microvm.kernelParams`         | Like `boot.kernelParams` but will not end up in `system.build.toplevel`, saving you rebuilds        |
 | `microvm.storeOnDisk`          | Enables the store on the boot squashfs even in the presence of a share with the host's `/nix/store` |
 | `microvm.writableStoreOverlay` | Optional string of the path where all writes to `/nix/store` should go to.                          |

doc/src/shares.md

@@ -10,7 +10,7 @@ In `microvm.shares` elements the `proto` field allows either of two
 values:
 
 - `9p` (default) is built into many hypervisors, allowing you to
-  quickly share a directory tree
+  quickly share a directory tree. Not supported by vfkit on macOS.
 
 - `virtiofs` requires a separate virtiofsd service which is started as
   a prerequisite when you start MicroVMs through a systemd service
@@ -21,6 +21,9 @@ values:
 
   Expect `virtiofs` to yield better performance over `9p`.
 
+  **Note:** vfkit (macOS) has built-in virtiofs support and does not
+  require a separate virtiofsd service.
+
 ```nix
 microvm.shares = [ {
   proto = "virtiofs";