libkrun virtio-net driver enables TSO offloading and checksum
offloading by default, so we must use vment-helper --enable-tso and
--enable-checksum-offload with krunkit. These options do not work with
vfkit.
* vfkit: Log serial console to file
To make debugging easier, add virtio-serial device logging serial
console to file:
~/.minikube/machines/NAME/serial.log
To enable logging, we need to enable the console in the kernel command
line, since we still use direct kernel boot.
Example log:
% cat /Users/nir/.minikube/machines/vfkit/vfkig.log
[ 0.896094] cacheinfo: Unable to detect cache hierarchy for CPU 0
[ 0.897186] loop: module loaded
[ 0.897670] virtio_blk virtio2: [vda] 840488 512-byte logical blocks (430 MB/410 MiB)
[ 0.897733] vda: detected capacity change from 0 to 430329856
[ 0.898460] virtio_blk virtio3: [vdb] 40960000 512-byte logical blocks (21.0 GB/19.5 GiB)
[ 0.898533] vdb: detected capacity change from 0 to 20971520000
...
[ 1.794714] systemd[1]: Detected virtualization vm-other.
[ 1.794752] systemd[1]: Detected architecture arm64.
Welcome to Buildroot 2025.02!
[ 1.794944] systemd[1]: Hostname set to <minikube>.
[ 1.795011] systemd[1]: Initializing machine ID from random generator.
...
[ OK ] Started Container Runtime Interface for OCI (CRI-O).
[ OK ] Reached target Multi-User System.
Welcome to minikube
vfkit login: [ 6.681578] systemd-ssh-generator[630]: Binding SSH to AF_UNIX socket /run/ssh-unix-local/socket.
* vfkit: Use EFI bootloader
With the fixed iso, we can simplify the driver using the EFI bootloader
option[1] instead of the legacy and deprecated --kernel, --kernel-cmdline,
and --initrd options[2].
Example run:
% minikube start -p vfkit --driver vfkit --container-runtime containerd --network vmnet-shared
😄 [vfkit] minikube v1.36.0 on Darwin 15.5 (arm64)
✨ Using the vfkit driver based on user configuration
👍 Starting "vfkit" primary control-plane node in "vfkit" cluster
🔥 Creating vfkit VM (CPUs=2, Memory=6000MB, Disk=20000MB) ...
📦 Preparing Kubernetes v1.33.1 on containerd 1.7.23 ...
▪ Generating certificates and keys ...
▪ Booting up control plane ...
▪ Configuring RBAC rules ...
🔗 Configuring bridge CNI (Container Networking Interface) ...
🔎 Verifying Kubernetes components...
▪ Using image gcr.io/k8s-minikube/storage-provisioner:v5
🌟 Enabled addons: default-storageclass, storage-provisioner
🏄 Done! kubectl is now configured to use "vfkit" cluster and "default" namespace by default
Comparing direct kernel boot and --bootloader efi shows that it is little bit faster and boot time is more consistent.
% hyperfine -r 10 -C "minikube delete" \
"vfkit-efi/out/minikube start --driver vfkit --network vmnet-shared --container-runtime containerd --no-kubernetes" \
"vfkit-direct/out/minikube start --driver vfkit --network vmnet-shared --container-runtime containerd --no-kubernetes"
Benchmark 1: vfkit-efi/out/minikube start --driver vfkit --network vmnet-shared --container-runtime containerd --no-kubernetes
Time (mean ± σ): 10.205 s ± 0.656 s [User: 0.381 s, System: 0.266 s]
Range (min … max): 9.106 s … 11.254 s 10 runs
Benchmark 2: vfkit-direct/out/minikube start --driver vfkit --network vmnet-shared --container-runtime containerd --no-kubernetes
Time (mean ± σ): 10.933 s ± 1.616 s [User: 0.402 s, System: 0.406 s]
Range (min … max): 9.155 s … 14.168 s 10 runs
Summary
vfkit-efi/out/minikube start --driver vfkit --network vmnet-shared --container-runtime containerd --no-kubernetes ran
1.07 ± 0.17 times faster than vfkit-direct/out/minikube start --driver vfkit --network vmnet-shared --container-runtime containerd --no-kubernetes
[1] https://github.com/crc-org/vfkit/blob/main/doc/usage.md#efi-bootloader
[2] https://github.com/crc-org/vfkit/blob/main/doc/usage.md#deprecated-options
* docs: Update vfkit driver documentation
- Separate vfkit requirements and vmnet-shared requirements
- Update minimal macOS version required for --bootloader efi
- Simplify vfkit upgrade, it is available in brew now
* Fix KVM driver tests timeouts
Rewrite KVM driver waiting logic for domain start, getting ip address
and shutting domain down. Add more config/state outputs to aid future
debugging.
Bump go/libvirt to v1.11002.0 and set the minimum memory required for
running all tests to 3GB to avoid some really weird system behaviour.
* revert reduction of timelimit for TestCert tests run
* set memory and debug output in TestNoKubernetes tests
* extend kvm waitForStaticIP timeout
* add console log to debug output
* Updating ISO to v1.36.0-1748823857-20852
---------
Co-authored-by: minikube-bot <minikube-bot@google.com>
* fix QF1011: could omit type *os.File from declaration; it will be inferred from the right-hand side
* fix QF1012: Use fmt.Fprintf(x, ...) instead of x.Write(fmt.Sprintf(...))
* fix QF1001: could apply De Morgan's law
* fix QF1003: could use tagged switch
* fix weakCond: suspicious ; nil check may not be enough, check for len (gocritic)
* fix docStub: silencing go lint doc-comment warnings is unadvised
* fix builtinShadow: shadowing of predeclared identifier: error
* fix importShadow: shadow of imported package
* fix nestingReduce: invert if cond, replace body with , move old body after the statement
* useless-break: useless break in case clause (revive)
* Clear the redundant content in golangci.yaml file
* Kicbase/ISO: Update cni-plugins from v1.6.2 to v1.7.1
* Updating kicbase image to v0.0.46-1747341282-20771
* Updating ISO to v1.35.0-1747341198-20771
* Kicbase/ISO: Update cri-dockerd from v0.3.15 to v0.4.0
* Updating kicbase image to v0.0.46-1747166185-20747
* Updating ISO to v1.35.0-1747160120-20747
* vmnet: Improve --network vmnet-shared validation
Previously we did not check that the helper can run with the
--close-from=4 option, so the command could succeed when incorrect
sudoers configuration. For example a user with liberal NOPASSWD rule,
but without the closefrom_override option.
When the check failed, we log unhelpful log:
libmachine: Failed to run vmnet-helper:
%!w(*exec.ExitError=&{0x14000135e30 [115 117 100 111 58 32 97 ... 101 100 10]})
And we returned a bool, so the caller could not provide a suggestion how
to resolve the issue.
Fix by:
- Rename vment.HelperAvaialble to vment.ValidateHelper
- Return an error describing the issue, including a reason.Kind that can
be used to provide a suggestion for resolving the issue.
- Include the ExitError.Stderr int the error. This includes helpful
error messages from sudo.
- Add new reason.NotConfiguredVmnetHelper error
- Improve log when vment.ValidateHelper() succeeded
Example error flow - vment-helper not installed:
% minikube start --driver vfkit --network vmnet-shared
😄 minikube v1.35.0 on Darwin 15.4.1 (arm64)
✨ Using the vfkit (experimental) driver based on user configuration
🙈 Exiting due to NOT_FOUND_VMNET_HELPER: failed to validate vmnet-shared network:
stat /opt/vmnet-helper/bin/vmnet-helper: no such file or directory
💡 Suggestion:
vmnet-helper was not found on the system, resolve by:
Option 1) Installing vmnet-helper:
https://github.com/nirs/vmnet-helper#installation
Option 2) Using the nat network:
minikube start<no value> --driver vfkit --network nat
I resolved the issue by installing vmnet-helper but I did not configured
the sudoers rule:
% minikube start --driver vfkit --network vmnet-shared
😄 minikube v1.35.0 on Darwin 15.4.1 (arm64)
✨ Using the vfkit (experimental) driver based on user configuration
🙈 Exiting due to NOT_CONFIGURED_VMNET_HELPER: failed to validate vmnet-shared network:
exit status 1: sudo: you are not permitted to use the -C option
💡 Suggestion:
Configure vmnet-helper to run without a password.
Please install a vmnet-helper sudoers rule using these instructions:
https://github.com/nirs/vmnet-helper#granting-permission-to-run-vmnet-helper
After installing the sudoers rule minikube could start.
* vfkit: Use helper --socket instead of --fd
The --fd option avoids the need to manage a bound unix sockets, in
particular the limit on unix socket length. It is also more secure;
only the process inheriting the socket can access the helper. However it
requires the sudo --close-from= option, which may not work for some
users. We don't understand why it does not work, and debugging it is
hard since users are not happy to share their local sudoers
configuration.
Avoid the trouble by switching to the --socket option. In this case we
pass a unix socket path to the helper and vfkit. The helper creates a
bound unix datagram socket in the specified path, and waits until vfkit
connects to the socket. When vfkit connects to the unix socket the
programs are connected in the same way they are connected by passing
file descriptors.
When running minikube we will see 3 new files in the machine directory:
- `vfkit-fb64-7802.sock`: vfkit unix datagram socket
- `vmnet-helper.sock`: vmnet-helper unix datagram socket
- `vmnet-helper.sock.lock`: lockfile for vment-helper socket
The files are deleted when vmnet-helper and vfkit are terminated
gracefully. If they are killed the stale files are replaced on the next
start.
Issues:
- If the path exceeds the limit (104 characters), opening the socket
will fail. We have the sames issue with vfkit management socket.
* vment: Fallback to interactive sudo
If vmnet-helper sudoers rule is not configured or does not work for the
user, maybe because the user has disabled the NOPASSWD option, we used
to fail, recommending to configure vmnet sudoers rule. This does not
help a user that cannot fix the sudoers configuration.
Since we switched to --socket mode, we can work without a sudoers rule.
If we can interact with the user, we fall back to interactive sudo. The
user can enter a password to start the machine.
Example run with --interactive=false:
% minikube start --driver vfkit --network vmnet-shared --interactive=false
😄 minikube v1.35.0 on Darwin 15.4.1 (arm64)
✨ Using the vfkit (experimental) driver based on user configuration
🙈 Exiting due to NOT_CONFIGURED_VMNET_HELPER: failed to validate vmnet-shared network:
exit status 1: sudo: a password is required
💡 Suggestion:
Configure vmnet-helper to run without a password.
Please install a vmnet-helper sudoers rule using these instructions:
https://github.com/nirs/vmnet-helper#granting-permission-to-run-vmnet-helper
Example run with --interactive (default):
% minikube start --driver vfkit --network vmnet-shared
😄 minikube v1.35.0 on Darwin 15.4.1 (arm64)
✨ Using the vfkit (experimental) driver based on user configuration
💡 Unable to run vmnet-helper without a password
To configure vment-helper to run without a password, please check the documentation:
https://github.com/nirs/vmnet-helper/#granting-permission-to-run-vmnet-helper
Password:
👍 Starting "minikube" primary control-plane node in "minikube" cluster
🔥 Creating vfkit VM (CPUs=2, Memory=6000MB, Disk=20000MB) ...
🐳 Preparing Kubernetes v1.33.0 on Docker 27.4.0 ...
▪ Generating certificates and keys ...
▪ Booting up control plane ...
▪ Configuring RBAC rules ...
🔗 Configuring bridge CNI (Container Networking Interface) ...
🔎 Verifying Kubernetes components...
▪ Using image gcr.io/k8s-minikube/storage-provisioner:v5
🌟 Enabled addons: storage-provisioner, default-storageclass
🏄 Done! kubectl is now configured to use "minikube" cluster and "default" namespace by default
* vfkit: Remove temporary variable
Remove temporary and unneeded mac variable. It is easier to follow the
code when we use d.MACAddress.
* vfkit: Promote state change to INFO level
System state changes should be more visible to make debugging easier.
* vmnet: Add vmnet package
The package manages the vmnet-helper[1] child process, providing
connection to the vmnet network without running the guest as root.
We will use vmnet-helper for the vfkit driver, which does not have a way
to use shared network, when guests can access other guest in the
network. We can use it later with the qemu driver as alternative to
socket_vmnet.
[1] https://github.com/nirs/vmnet-helper
* vfkit: add vmnet-shared network
Add new network option for vfkit "vmnet-shared", connecting vfkit to the
vmnet shared network. Clusters using this network can access other
clusters in the same network, similar to socket_vmnet with QEMU driver.
If network is not specified, we default to the "nat" network, keeping
the previous behavior. If network is "vmnet-shared", the vfkit driver
manages 2 processes: vfkit and vmnet-helper.
Like vfkit, vmnet-helper is started in the background, in a new process
group, so it not terminated if the minikube process group is terminate.
Since vmnet-helper requires root to start the vmnet interface, we start
it with sudo, creating 2 child processes. vmnet-helper drops privileges
immediately after starting the vmnet interface, and run as the user and
group running minikube.
Stopping the cluster will stop sudo, which will stop the vmnet-helper
process. Deleting the cluster kill both sudo and vmnet-helper by killing
the process group.
This change is not complete, but it is good enough to play with the new
shared network.
Example usage:
1. Install vmnet-helper:
https://github.com/nirs/vmnet-helper?tab=readme-ov-file#installation
2. Setup vmnet-helper sudoers rule:
https://github.com/nirs/vmnet-helper?tab=readme-ov-file#granting-permission-to-run-vmnet-helper
3. Start 2 clusters with vmnet-shared network:
% minikube start -p c1 --driver vfkit --network vmnet-shared
...
% minikube start -p c2 --driver vfkit --network vmnet-shared
...
% minikube ip -p c1
192.168.105.18
% minikube ip -p c2
192.168.105.19
4. Both cluster can access the other cluster:
% minikube -p c1 ssh -- ping -c 3 192.168.105.19
PING 192.168.105.19 (192.168.105.19): 56 data bytes
64 bytes from 192.168.105.19: seq=0 ttl=64 time=0.621 ms
64 bytes from 192.168.105.19: seq=1 ttl=64 time=0.989 ms
64 bytes from 192.168.105.19: seq=2 ttl=64 time=0.490 ms
--- 192.168.105.19 ping statistics ---
3 packets transmitted, 3 packets received, 0% packet loss
round-trip min/avg/max = 0.490/0.700/0.989 ms
% minikube -p c2 ssh -- ping -c 3 192.168.105.18
PING 192.168.105.18 (192.168.105.18): 56 data bytes
64 bytes from 192.168.105.18: seq=0 ttl=64 time=0.289 ms
64 bytes from 192.168.105.18: seq=1 ttl=64 time=0.798 ms
64 bytes from 192.168.105.18: seq=2 ttl=64 time=0.993 ms
--- 192.168.105.18 ping statistics ---
3 packets transmitted, 3 packets received, 0% packet loss
round-trip min/avg/max = 0.289/0.693/0.993 ms
* reason: Remove trailing whitepsace
Trailing whitespace is removed by some editors or displayed as a
warning. Clean up to make it easy to make maintain this file.
* start: Validate vfkit --network option
The vfkit driver supports now `nat` and `vmnet-shared` network options.
The `nat` option provides the best performance and is always available,
so it is the default network option. The `vmnet-shared` option provides
access between machines with lower performance compared to `nat`.
If `vment-shared` option is selected, we verify that vmnet-helper is
available. The check ensure that vmnet-helper is installed and sudoers
configuration allows the current user to run vment-helper without a
password.
If validating vment-helper failed, we return a new NotFoundVmnetHelper
reason pointing to vment-helper installation docs or recommending to use
`nat`. This is based on how we treat missing socket_vmnet for QEMU
driver.
* site: Document vfkit network options
* Add process package
Current code contains multiple implementations for managing a process
using pids, with various issues:
- Some are unsafe, terminating a process by pid without validating that
the pid belongs to the right process. Some use unclear
- Using unclear terms like checkPid() (what does it mean?)
- Some are missing tests
Let's clean up the mess by introducing a process package. The package
provides:
- process.WritePidfile(): write a pid to file
- process.ReadPidfile(): read pid from file
- process.Exists(): tells if process matching pid and name exists
- process.Terminate() terminates a process matching pid and name
- process.Kil() kill a process matching pid and name
The library is tested on linux, darwin, and windows. On windows we don't
have a standard way to terminate a process gracefully, so
process.Terminate() is the same as process.Kill().
I want to use this package in vfkit and the new vment package, and later
we can use it for qemu, hyperkit, and other code using managing
processes with pids.
* vfkit: Use process pidfile helpers
- Simplify GetState() using process.ReadPidfile()
- Simplify Start() using process.WritePidfile()
* vfkit: Simpler and more robust GetState()
GetState() had several issues:
- When accessing vfkit HTTP API, we handled only "running",
"VirtualMachineStateRunning", "stopped", and
"VirtualMachineStateStopped", but there are other 10 possible states,
which we handled as state.None, when vfkit is running and need to be
stopped. This can lead to wrong handling in the caller.
- When handling "stopped" and "VirtualMachineStateStopped" we returned
state.Stopped, but did not remove the pidfile. This can cause
termination of unrelated process or reporting wrong status when the
pid is reused.
- Accessing the HTTP API will fail after we stop or kill it. This
cause GetState() to fail when the process is actually stopped, which
can lead to unnecessary retries and long delays (#20503).
- When retuning state.None during Remove(), we use tried to do graceful
shutdown which does not make sense in minikube delete flow, and is not
consistent with state.Running handling.
Accessing vfkit API to check for state does not add much value for our
used case, checking if the vfkit process is running, and it is not
reliable.
Fix all the issues by not using the HTTP API in GetState(), and use only
the process state. We still use the API for stopping and killing vfkit
to do graceful shutdown. This also simplifies Remove(), since we need to
handle only the state.Running state.
With this change we consider vfkit as stopped only when the process does
not exist, which takes about 3 seconds after the state is reported as
"stopped".
Example stop flow:
I0309 18:15:40.260249 18857 main.go:141] libmachine: Stopping "minikube"...
I0309 18:15:40.263225 18857 main.go:141] libmachine: set state: {State:Stop}
I0309 18:15:46.266902 18857 main.go:141] libmachine: Machine "minikube" was stopped.
I0309 18:15:46.267122 18857 stop.go:75] duration metric: took 6.127761459s to stop
Example delete flow:
I0309 17:00:49.483078 18127 out.go:177] * Deleting "minikube" in vfkit ...
I0309 17:00:49.499252 18127 main.go:141] libmachine: set state: {State:HardStop}
I0309 17:00:49.569938 18127 lock.go:35] WriteFile acquiring /Users/nir/.kube/config: ...
I0309 17:00:49.573977 18127 out.go:177] * Removed all traces of the "minikube" cluster.
* vfkit: Use process.Exists()
Previously we did not check the process name when checking a pid from a
pidfile. If the pidfile became state we would assume that vfkit is
running and try to stop it via the HTTP API, which would never succeed.
Now we detect stale pidfile and remove it.
If removing the stale pidfile fails, we don't want to fail the operation
since we know that vfkit is not running. We log the failure to aid
debugging of stale pidfile.
* vfkit: More robust Stop()
If setting vfkit state to "Stop" fails, we used to return an error.
Retrying the operation may never succeed.
Fix by falling back to terminating vfkit using a signal. This terminates
vfkit immediately similar to HardStop[1].
We can still fail if the pidfile is corrupted but this is unlikely and
requires manual cleanup.
In the case when we are sure the vfkit process does not exist, we remove
the pidfile immediately, avoiding leftover pidfile if the caller does
not call GetState() after Stop().
[1] https://github.com/crc-org/vfkit/issues/284
* vfkit: More robust Kill()
We know that setting the state to `HardStop` typically fails:
I0309 19:19:42.378591 21795 out.go:177] 🔥 Deleting "minikube" in vfkit ...
W0309 19:19:42.397472 21795 delete.go:106] remove failed, will retry: kill: Post "http://_/vm/state": EOF
This may lead to unnecessary retries and delays. Fix by falling back to
sending a SIGKILL signal.
Example delete flow when setting vfkit state fails:
I0309 20:07:41.688259 25540 out.go:177] 🔥 Deleting "minikube" in vfkit ...
I0309 20:07:41.712017 25540 main.go:141] libmachine: Failed to set vfkit state to 'HardStop': Post "http://_/vm/state": EOF
We use `HardStop` which seems to do a forced shutdown instead of
graceful shutdown, and to make things worse, always fails with:
I0309 15:00:42.452986 13723 stop.go:66] stop err: Post "http://_/vm/state": EOF
Which leads to unneeded retry and pointless backup attempt timing out
after 135 seconds because vkfit was stopped.
With this change we do a graceful shutdown, and the time to stop the
cluster decreased from 135 seconds to 3 seconds (45 times faster).
Example stop log:
I0309 15:34:33.104429 14440 main.go:141] libmachine: Stopping "minikube"...
I0309 15:34:33.105225 14440 main.go:141] libmachine: get state: {State:VirtualMachineStateRunning}
I0309 15:34:33.105799 14440 main.go:141] libmachine: set state: {State:Stop}
I0309 15:34:33.106099 14440 main.go:141] libmachine: get state: {State:VirtualMachineStateRunning}
I0309 15:34:36.109380 14440 main.go:141] libmachine: Machine "minikube" was stopped.
* Kicbase/ISO: Update cni-plugins from v1.6.1 to v1.6.2
* Updating kicbase image to v0.0.45-1736763277-20236
* Updating ISO to v1.34.0-1736762773-20236
On darwin bootp uses non-standard MAC address format[1]:
"8e:1:99:9c:54:b1" instead of "8e:01:99:9c:54:b1". We fixed this by
trimming leading "0" in the string before looking up the IP address.
There are several issues with the current code:
- Fragile, will break if bootp changes the format (unlikely)
- Fixing the wrong place, the drivers should not care about the MAC
address format.
- The tests were confusing, showing that we can match standard MAC
addresses while the actual code could match only non-standard bootp
addresses.
- Logging wrong MAC address since we trimmed leading zeros before
logging
This change replace trimming leading zeros with parsing MAC address
strings and comparing the bytes. The test includes now both standard and
non-standard MAC addresses.
[1] https://openradar.appspot.com/FB15382970
* Add new macOS vfkit driver, like hyperkit and qemu
It uses the new Virtualization.framework from macOS 11,
instead of the older Hypervisor.framework (hvf) in QEMU.
* Start vfkit in a new process group
* vfkit: Add firewall workaround from minikube
* vfkit: Add HostIP implementation for gateway
* vfkit: Add driver to extra-disks supported
* Add documentation for vfkit driver
* vfkit: Add usual integration tests
* Update site/content/en/docs/drivers/vfkit.md
Co-authored-by: Steven Powell <44844360+spowelljr@users.noreply.github.com>
---------
Co-authored-by: Nir Soffer <nsoffer@redhat.com>
Co-authored-by: Medya Ghazizadeh <medyagh@users.noreply.github.com>
Co-authored-by: Steven Powell <44844360+spowelljr@users.noreply.github.com>
Nir Soffer
Predrag Rogic
Tian
minikube-bot
Steven Powell
Nir Soffer
fbyrne
Steven Powell
Anders Björklund