krunvm

krunvm is a CLI-based utility designed to create microVMs directly from OCI images. It leverages libkrun and buildah to provide a lightweight virtualization experience.

Key Features

• Minimal footprint: Optimized for low resource usage.
• Fast boot time: Rapidly initializes microVMs.
• Zero disk image maintenance: Uses OCI images directly.
• Zero network configuration: Simplifies networking setup.
• Volume Mapping: Supports mapping host volumes into the guest.
• Port Forwarding: Supports exposing guest ports to the host.

Supported Platforms

• Linux/KVM on x86_64.
• Linux/KVM on AArch64.
• macOS/Hypervisor.framework on ARM64.

To build krunvm from source, ensure you have the following dependencies installed:

• Rust Toolchain
• libkrun
• buildah
• asciidoctor

Then, run the cargo build command.

cargo build --release

To install krunvm on macOS, use Homebrew by tapping the slp/krun repository and then installing the package.

brew tap slp/krun
brew install krunvm

To install krunvm on Fedora, enable the necessary Copr repositories for libkrunfw, libkrun, and krunvm, then install the package using dnf.

dnf copr enable -y slp/libkrunfw
dnf copr enable -y slp/libkrun
dnf copr enable -y slp/krunvm
dnf install -y krunvm

On macOS, krunvm requires a dedicated, case-sensitive APFS volume for storage. If a valid volume is not configured, the CLI will prompt you to provide a mountpoint and will perform a case-sensitivity test.

You can create a suitable volume using diskutil in a separate terminal:

diskutil apfs addVolume disk3 "Case-sensitive APFS" krunvm

When prompted by krunvm, you can enter the mountpoint (defaulting to /Volumes/krunvm) or provide a custom path.

On macOS (Aarch64), you can run x86_64 microVMs using the --x86 flag. This requires setting up a Rosetta support file for Linux.

1. Create a file named .krunvm-rosetta in your $HOME directory.
2. Populate it with the contents that the rosetta binary expects to be served from its specific ioctl.

Limitations:

• x86 microVMs on Aarch64 are restricted to exactly 1 CPU.

The VmConfig struct defines the specific configuration for an individual virtual machine.

#[derive(Default, Debug, Serialize, Deserialize)]
pub struct VmConfig {
    name: String,
    cpus: u32,
    mem: u32,
    container: String,
    workdir: String,
    dns: String,
    mapped_volumes: HashMap<String, String>,
    mapped_ports: HashMap<String, String>,
}

The KrunvmConfig struct defines the global configuration for the krunvm application. It is persisted using confy under the name krunvm.

Fields:

• version: Configuration version (defaults to 1).
• default_cpus: Default number of CPUs for new VMs (defaults to 2).
• default_mem: Default memory in MB for new VMs (defaults to 1024).
• default_dns: Default DNS server (defaults to 1.1.1.1).
• storage_volume: The mountpoint for the dedicated storage volume.
• vmconfig_map: A map of VM names to their specific VmConfig settings.

#[derive(Debug, Serialize, Deserialize)]
pub struct KrunvmConfig {
    version: u8,
    default_cpus: u32,
    default_mem: u32,
    default_dns: String,
    storage_volume: String,
    vmconfig_map: HashMap<String, VmConfig>,
}

The following flags are available when using the create command to configure the microVM: