drivers: Add Virtiofs mounts for vfkit and krunkit

Replace 9p mounts with virtiofs for vfkit and krunkit. Testing shows
that virtiofs mount is 23 times faster with krunkit, and 8 times faster
with vfkit.

vfkit and krunkit support multiple virtiofs mounts but minikube
--mount-* flags are not ready for multiple mounts. We have the same
issue with KIC drivers, supporting multiple mounts but using only one.
We hope to improve this in the next release.

Example usage:

    minikube start --mount-string ~/models:/mnt/models

We don't use the --mount flag since it does not make sense. We want to
eliminate this flag also for 9p mounts soon.

The arguments are parsed and validated when configuring the driver, so
invalid arguments fail quickly without starting the driver. The
validated mounts are stored in the machine config:

    $ jq '.Driver.VirtiofsMounts' < ~/.minikube/machines/minikube/config.json
    [
      {
        "HostPath": "/Users/joe/models",
        "GuestPath": "/mnt/models",
        "Tag": "f845b54d-00e3-493d-9541-3b37490b96db"
      }
    ]

Minikube generates a new random UUID for every virtiofs mount to
identify the file system inside the guest. In krunkit and vfkit, every
mount is add as:

    --device virtio-fs,sharedDir=/host-path,mountTag=f845b54d-00e3-493d-9541-3b37490b96db

When the guest is started the shared directory is mounted via SSH using:

    sudo mkdir -p /mnt/models
    sudo mount -t virtiofs f845b54d-00e3-493d-9541-3b37490b96db /mnt/models

Example mount:

    $ minikube ssh findmnt /mnt/models
    TARGET      SOURCE                               FSTYPE   OPTIONS
    /mnt/models f845b54d-00e3-493d-9541-3b37490b96db virtiofs rw,relatime

More work is needed to add VirtioFS to qemu. I'm starting with vfkit and
krunkit since they have identical interface (krunkit was designed as
drop-in replacement for vfkit).

Author: nirs

pkg/drivers/common/virtiofs/virtiofs.go

@@ -0,0 +1,143 @@
+/*
+Copyright 2025 The Kubernetes Authors All rights reserved.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package virtiofs
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"github.com/docker/machine/libmachine/drivers"
+	"github.com/google/uuid"
+)
+
+// Mount is a directory on the host shared with the guest using
+// virtiofs.
+type Mount struct {
+	// HostPath is an absolute path to existing directory to share with the guest.
+	HostPath string
+	// GuestPath is a path in the guest for mounting the shared directory.
+	GuestPath string
+	// Tag is a string identifying the shared file system in the guest.
+	Tag string
+}
+
+// ValidateMountString parses the mount-string flag and validates that the
+// specified paths can be used for virtiofs mount. Returns list with one
+// validated mount, ready for configuring the driver.
+// TODO: Drop when we have a flag supporting multiple mounts.
+func ValidateMountString(s string) ([]*Mount, error) {
+	if s == "" {
+		return nil, nil
+	}
+	return validateMounts([]string{s})
+}
+
+func validateMounts(args []string) ([]*Mount, error) {
+	var mounts []*Mount
+
+	seenHost := map[string]*Mount{}
+	seenGuest := map[string]*Mount{}
+
+	for _, s := range args {
+		mount, err := ParseMount(s)
+		if err != nil {
+			return nil, err
+		}
+
+		if err := mount.Validate(); err != nil {
+			return nil, err
+		}
+
+		if existing, ok := seenHost[mount.HostPath]; ok {
+			return nil, fmt.Errorf("host path %q is already shared at guest path %q", mount.HostPath, existing.GuestPath)
+		}
+		seenHost[mount.HostPath] = mount
+
+		if existing, ok := seenGuest[mount.GuestPath]; ok {
+			return nil, fmt.Errorf("guest path %q is already shared from host path %q", mount.GuestPath, existing.HostPath)
+		}
+		seenGuest[mount.GuestPath] = mount
+
+		mounts = append(mounts, mount)
+	}
+
+	return mounts, nil
+}
+
+// ParseMount parses a string in the format "/host-path:/guest-path" and returns
+// a new Mount instance. The mount must be validated before using it to
+// configure the driver.
+func ParseMount(s string) (*Mount, error) {
+	pair := strings.SplitN(s, ":", 2)
+	if len(pair) != 2 {
+		return nil, fmt.Errorf("invalid virtiofs mount %q: (expected '/host-path:/guest-path')", s)
+	}
+
+	return &Mount{
+		HostPath:  pair[0],
+		GuestPath: pair[1],
+		Tag:       uuid.NewString(),
+	}, nil
+}
+
+// Validate that the mount can be used for virtiofs device configuration. Both
+// host and guest paths must be absolute. Host path must be a directory and must
+// not include virtiofs configuration separator (",").
+func (m *Mount) Validate() error {
+	// "," is a --device configuration separator in vfkit and krunkit.
+	if strings.Contains(m.HostPath, ",") {
+		return fmt.Errorf("host path %q must not contain ','", m.HostPath)
+	}
+
+	if !filepath.IsAbs(m.HostPath) {
+		return fmt.Errorf("host path %q is not an absolute path", m.HostPath)
+	}
+
+	if fs, err := os.Stat(m.HostPath); err != nil {
+		return fmt.Errorf("failed to validate host path %q: %w", m.HostPath, err)
+	} else if !fs.IsDir() {
+		return fmt.Errorf("host path %q is not a directory", m.HostPath)
+	}
+
+	if !filepath.IsAbs(m.GuestPath) {
+		return fmt.Errorf("guest path %q is not an absolute path", m.GuestPath)
+	}
+
+	return nil
+}
+
+// SetupMounts connects to the host via SSH, creates the mount directory if
+// needed, and mount the virtiofs file system. It should be called by
+// driver.Start().
+func SetupMounts(d drivers.Driver, mounts []*Mount) error {
+	var script strings.Builder
+
+	script.WriteString("set -e\n")
+
+	for _, mount := range mounts {
+		script.WriteString(fmt.Sprintf("sudo mkdir -p \"%s\"\n", mount.GuestPath))
+		script.WriteString(fmt.Sprintf("sudo mount -t virtiofs %s \"%s\"\n", mount.Tag, mount.GuestPath))
+	}
+
+	if _, err := drivers.RunSSHCommandFromDriver(d, script.String()); err != nil {
+		return err
+	}
+
+	return nil
+}

pkg/drivers/krunkit/krunkit.go

@@ -42,6 +42,7 @@ import (
 
 	"k8s.io/klog/v2"
 	"k8s.io/minikube/pkg/drivers/common"
+	"k8s.io/minikube/pkg/drivers/common/virtiofs"
 	"k8s.io/minikube/pkg/drivers/common/vmnet"
 	"k8s.io/minikube/pkg/minikube/exit"
 	"k8s.io/minikube/pkg/minikube/firewall"
@@ -71,6 +72,7 @@ type Driver struct {
 	CPU            int
 	Memory         int
 	ExtraDisks     int
+	VirtiofsMounts []*virtiofs.Mount
 	MACAddress     string
 	VmnetHelper    vmnet.Helper
 }
@@ -207,8 +209,18 @@ func (d *Driver) Start() error {
 	}
 
 	log.Infof("Waiting for VM to start (ssh -p %d docker@%s)...", d.SSHPort, d.IPAddress)
+	if err := WaitForTCPWithDelay(fmt.Sprintf("%s:%d", d.IPAddress, d.SSHPort), time.Second); err != nil {
+		return err
+	}
+
+	if len(d.VirtiofsMounts) > 0 {
+		log.Infof("Setup virtiofs mounts ...")
+		if err := virtiofs.SetupMounts(d, d.VirtiofsMounts); err != nil {
+			return err
+		}
+	}
 
-	return WaitForTCPWithDelay(fmt.Sprintf("%s:%d", d.IPAddress, d.SSHPort), time.Second)
+	return nil
 }
 
 // startKrunkit starts the krunkit child process.
@@ -231,6 +243,11 @@ func (d *Driver) startKrunkit(socketPath string) error {
 			"--device", fmt.Sprintf("virtio-blk,path=%s", common.ExtraDiskPath(d.BaseDriver, i)))
 	}
 
+	for _, mount := range d.VirtiofsMounts {
+		args = append(args,
+			"--device", fmt.Sprintf("virtio-fs,sharedDir=%s,mountTag=%s", mount.HostPath, mount.Tag))
+	}
+
 	log.Debugf("executing: krunkit %s", strings.Join(args, " "))
 	cmd := exec.Command(driverName, args...)
 

pkg/drivers/vfkit/vfkit.go

@@ -44,6 +44,7 @@ import (
 
 	"k8s.io/klog/v2"
 	"k8s.io/minikube/pkg/drivers/common"
+	"k8s.io/minikube/pkg/drivers/common/virtiofs"
 	"k8s.io/minikube/pkg/drivers/common/vmnet"
 	"k8s.io/minikube/pkg/minikube/detect"
 	"k8s.io/minikube/pkg/minikube/exit"
@@ -72,6 +73,7 @@ type Driver struct {
 	CPU            int
 	Memory         int
 	ExtraDisks     int
+	VirtiofsMounts []*virtiofs.Mount
 	Network        string        // "", "nat", "vmnet-shared"
 	MACAddress     string        // For network=nat, network=""
 	VmnetHelper    *vmnet.Helper // For network=vmnet-shared
@@ -250,8 +252,18 @@ func (d *Driver) Start() error {
 	}
 
 	log.Infof("Waiting for VM to start (ssh -p %d docker@%s)...", d.SSHPort, d.IPAddress)
+	if err := WaitForTCPWithDelay(fmt.Sprintf("%s:%d", d.IPAddress, d.SSHPort), time.Second); err != nil {
+		return err
+	}
+
+	if len(d.VirtiofsMounts) > 0 {
+		log.Infof("Setup virtiofs mounts ...")
+		if err := virtiofs.SetupMounts(d, d.VirtiofsMounts); err != nil {
+			return err
+		}
+	}
 
-	return WaitForTCPWithDelay(fmt.Sprintf("%s:%d", d.IPAddress, d.SSHPort), time.Second)
+	return nil
 }
 
 // startVfkit starts the vfkit child process. If socketPath is not empty, vfkit
@@ -308,6 +320,12 @@ func (d *Driver) startVfkit(socketPath string) error {
 	startCmd = append(startCmd,
 		"--device", fmt.Sprintf("virtio-serial,logFilePath=%s", serialPath))
 
+	for _, mount := range d.VirtiofsMounts {
+		startCmd = append(startCmd,
+			"--device", fmt.Sprintf("virtio-fs,sharedDir=%s,mountTag=%s", mount.HostPath, mount.Tag))
+
+	}
+
 	log.Debugf("executing: vfkit %s", strings.Join(startCmd, " "))
 	os.Remove(d.sockfilePath())
 	cmd := exec.Command("vfkit", startCmd...)

pkg/minikube/driver/driver.go

@@ -228,6 +228,11 @@ func SupportsNetworkFlag(name string) bool {
 	return IsKIC(name) || IsKVM(name) || IsQEMU(name) || IsVFKit(name)
 }
 
+// SupportsVirtiofsMounts returns if driver supports virtiofs mounts
+func SupportsVirtiofsMounts(name string) bool {
+	return IsVFKit(name) || IsKrunkit(name)
+}
+
 // AllowsPreload returns if preload is allowed for the driver
 func AllowsPreload(driverName string) bool {
 	return !BareMetal(driverName) && !IsSSH(driverName)

pkg/minikube/node/config.go

@@ -73,7 +73,7 @@ func configureMounts(wg *sync.WaitGroup, cc config.ClusterConfig) {
 	wg.Add(1)
 	defer wg.Done()
 
-	if cc.MountString == "" || driver.IsKIC(cc.Driver) {
+	if cc.MountString == "" || driver.IsKIC(cc.Driver) || driver.SupportsVirtiofsMounts(cc.Driver) {
 		return
 	}
 

pkg/minikube/registry/drvs/krunkit/krunkit.go

@@ -28,6 +28,7 @@ import (
 	"github.com/docker/machine/libmachine/drivers"
 	"github.com/google/uuid"
 
+	"k8s.io/minikube/pkg/drivers/common/virtiofs"
 	"k8s.io/minikube/pkg/drivers/common/vmnet"
 	"k8s.io/minikube/pkg/drivers/krunkit"
 	"k8s.io/minikube/pkg/minikube/config"
@@ -65,6 +66,11 @@ func configure(cfg config.ClusterConfig, n config.Node) (interface{}, error) {
 		u = uuid.NewString()
 	}
 
+	mounts, err := virtiofs.ValidateMountString(cfg.MountString)
+	if err != nil {
+		return nil, err
+	}
+
 	return &krunkit.Driver{
 		BaseDriver: &drivers.BaseDriver{
 			MachineName: machineName,
@@ -76,6 +82,7 @@ func configure(cfg config.ClusterConfig, n config.Node) (interface{}, error) {
 		Memory:         cfg.Memory,
 		CPU:            cfg.CPUs,
 		ExtraDisks:     cfg.ExtraDisks,
+		VirtiofsMounts: mounts,
 		VmnetHelper: vmnet.Helper{
 			MachineDir:  filepath.Join(storePath, "machines", machineName),
 			InterfaceID: u,

pkg/minikube/registry/drvs/vfkit/vfkit.go

@@ -28,6 +28,7 @@ import (
 	"github.com/docker/machine/libmachine/drivers"
 	"github.com/google/uuid"
 
+	"k8s.io/minikube/pkg/drivers/common/virtiofs"
 	"k8s.io/minikube/pkg/drivers/common/vmnet"
 	"k8s.io/minikube/pkg/drivers/vfkit"
 	"k8s.io/minikube/pkg/minikube/config"
@@ -88,6 +89,11 @@ func configure(cfg config.ClusterConfig, n config.Node) (interface{}, error) {
 		return nil, fmt.Errorf("unsupported network: %q", cfg.Network)
 	}
 
+	mounts, err := virtiofs.ValidateMountString(cfg.MountString)
+	if err != nil {
+		return nil, err
+	}
+
 	return &vfkit.Driver{
 		BaseDriver: &drivers.BaseDriver{
 			MachineName: machineName,
@@ -99,6 +105,7 @@ func configure(cfg config.ClusterConfig, n config.Node) (interface{}, error) {
 		Memory:         cfg.Memory,
 		CPU:            cfg.CPUs,
 		ExtraDisks:     cfg.ExtraDisks,
+		VirtiofsMounts: mounts,
 		Network:        cfg.Network,
 		MACAddress:     mac,
 		VmnetHelper:    helper,

site/content/en/docs/handbook/mount.md

@@ -67,20 +67,26 @@ This directory may then be referenced from a Kubernetes manifest, for example:
 
 Some hypervisors, have built-in host folder sharing. Driver mounts are reliable with good performance, but the paths are not predictable across operating systems or hypervisors:
 
-| Driver | OS | HostFolder | VM |
-| --- | --- | --- | --- |
-| VirtualBox | Linux | /home | /hosthome |
-| VirtualBox | macOS | /Users | /Users |
-| VirtualBox | Windows | C://Users | /c/Users |
-| VMware Fusion | macOS | /Users | /mnt/hgfs/Users |
-| KVM | Linux | Unsupported | |
-| HyperKit | macOS | Supported |  |
-
-These mounts can be disabled by passing `--disable-driver-mounts` to `minikube start`.
-
-HyperKit mounts can use the following flags:
-`--nfs-share=[]`: Local folders to share with Guest via NFS mounts
-`--nfs-shares-root='/nfsshares'`: Where to root the NFS Shares, defaults to /nfsshares
+| Driver         | OS      | Host         | Guest             |
+|----------------|---------|--------------|-------------------|
+| VirtualBox     | Linux   | /home        | /hosthome         |
+| VirtualBox     | macOS   | /Users       | /Users            |
+| VirtualBox     | Windows | C://Users    | /c/Users          |
+| VMware Fusion  | macOS   | /Users       | /mnt/hgfs/Users   |
+| Vfkit          | macOS   | configurable | configurable      |
+| Krunkit        | macOS   | configurable | configurable      |
+| KVM            | Linux   | unsupported  |                   |
+| HyperKit       | macOS   | configurable | configurable      |
+
+Built-in mounts can be disabled by passing `--disable-driver-mounts` to `minikube start`.
+
+Vfkit and Krunkit drivers can use the following start flags:
+- `--mount-string`: Local folder to share with guest via Virtiofs. The folder is
+  specified with a pair: `/host-path:/guest-path`.
+
+HyperKit driver can use the following start flags:
+- `--nfs-share=[]`: Local folders to share with Guest via NFS mounts
+- `--nfs-shares-root='/nfsshares'`: Where to root the NFS Shares, defaults to /nfsshares
 
 ## File Sync