rust-vmm community: shared Rust components for hypervisors

What the project is: a shared library of virtualization pieces

rust-vmm is an open source project that lets the community build custom Virtual Machine Monitors and hypervisors. It provides a set of virtualization components that any project can use to quickly develop virtualization solutions while focusing on the key differentiators of their product rather than reimplementing common components like KVM wrappers, virtio devices and other VMM libraries.

That sentence is the whole pitch, and it is a narrow one. This is not a hypervisor. It is the layer underneath several hypervisors, and its value is measured in how much duplicated work it removes.

The origin story explains the shape. The initial idea was to create a place for sharing common virtualization components between two existing VMMs written in Rust, CrosVM and Firecracker. Those two projects have similar code for calling KVM ioctls, managing virtual machine memory and interacting with virtio devices, and the components could live in one place instead of two.

The scope widened from there. The project now covers bindings and low level access libraries for the Xen and Hyper-V hypervisors, and other open source projects have been integrated too, among them Cloud Hypervisor, the Qemu virtiofsd implementation and vhost-device.

The organisation is described as a shared effort and shared ownership open source project, and the contributor list is given by employer: Alibaba, AWS, Cloud Base, Crowdstrike, Intel, Google, Linaro and Red Hat, as well as individual contributors.

Structurally, each virtualization component lives in its own GitHub repository under the rust-vmm organisation, and one repository usually corresponds to one Rust crate. That one-to-one mapping is what makes the governance model work, and it is also the thing the project later revised.

The four arguments for using it, and the one that costs you

The reasons given for adopting rust-vmm are listed explicitly, and they are worth separating because they pull in different directions.

Reduced code duplication is the origin argument and still the strongest one. Faster development follows from it: the components are meant to be generic so they can be consumed by multiple projects, and a custom solution should only need to care about its specialised component, an API and the glue code that connects them. That is a clear statement of what the project expects you to still write.

Security and testability is the argument that carries the most weight for a production user, and it is specific about mechanism. Each component is individually tested with a set of common build-time tests responsible for running unit tests, linters including coding-style checks, and computing the coverage. For critical components that handle untrusted input, they also run fuzzing, with vm-virtio named as the example, and provide threat model documentation that customers can use to improve the security of their solutions.

The clean interface argument is the one with a hidden cost. Because crates are shared between multiple VMMs, reviews for interface changes will typically go through a few rounds of reviews to make sure they are flexible enough to be used by multiple products. That is a benefit when you are a consumer, because the interface you get has survived scrutiny from several angles. It is a cost when you are a contributor, because your proposed change will be argued against by people optimising for a product that is not yours.

That is the trade in one sentence: a conservative, widely reviewed interface, and a slower path to changing it.

The workspace reversal, and why one repository per workspace won

There is a piece of project history in the components section that explains more about the project than its principles do.

When the project started, each crate lived in its own repository. As the number of crates grew quickly, they reverted that decision and started having related crates as part of a single workspace. Now there is one workspace per repository. The vm-virtio repository, for example, accommodates multiple crates including virtio-queue and different virtio device implementations.

The stated reason is maintenance cost of repositories, and the example given is dependency updates. Whenever rust-vmm-ci is updated, Dependabot will open a pull request in each rust-vmm repository to update to the latest version. In most cases the reviews are trivial because very few changes are required, but you still have to go through a long list of pull requests that need to be approved. In rare cases when a change to the infrastructure affects CI, propagating it to individual repositories quickly adds up, and the work is clone, create a branch, provide the update, follow up on the pull requests, and so on.

That is a very concrete piece of engineering reasoning. It also explains the earlier one-to-one rule: the current arrangement, one workspace per repository, still keeps crates grouped so that a dependency bump touches one place rather than many.

The practical consequence for a user is that you consume crates, not repositories. Which repository a crate lives in affects the maintainers, not your dependency.

The three states of a crate and what they mean for you

Each rust-vmm crate is in one of three states, and the state tells you what you can depend on and where the code actually lives.

The first state is empty. The crate repo exists but there is no code there yet. This means the crate was created after a community acknowledgement about its relevance to the project, but either no code has been submitted yet or the initial code base is being reviewed through a pull request. The empty section lists one entry, vmm-vcpu, described as a hypervisor-agnostic abstraction for Virtual CPUs.

The second state is rust-vmm, meaning the code is a work in progress. Once it meets the production requirements, the crate will be pushed to crates.io.

The third state is crates.io, meaning the crate is considered production ready and can be consumed from Rust's canonical crate registry. And here is the sentence that matters most for anyone writing a dependency: the crate repository in rust-vmm is a staging area until the next push to crates.io. The production ready version of the code lives in crates.io while development happens in the rust-vmm git repo.

So there are two copies of the code and they are not the same. The registry version is the one that has passed the production requirements, and the git version is where the work happens. A user pinning a version in Cargo.toml gets the registry copy, which is the one the project considers ready.

For a component that is still in the rust-vmm state, that means you are looking at unreleased work and there is no published artifact to depend on.

The README also carries a section for crates in the rust-vmm state, listing components such as acpi_tables, but the listing is cut off in the text available here, so the full inventory needs to be read from the repository itself.

Governance: maintainers, gatekeepers and the crates.io requirements

The table of contents lists the governance structure, and the repository root shows the documents that back it up.

There are MAINTAINERS.md, CONTRIBUTING.md, INFRASTRUCTURE.md, SECURITY.md and a CODEOWNERS file, plus a docs directory. The sections on maintainers and gatekeepers, community channels, project and community infrastructure, contributing guidelines, adding a new virtualization component, publishing on crates.io with a requirements list, and CI are all in the extended documentation.

The existence of a gatekeeper role is itself informative. In a project where a crate is consumed by several products at several companies, the person who approves a publication is making a judgement that affects all of them. That is a different kind of review from a code review, and it explains why the interface changes go through several rounds.

The publishing requirements list is the gate every crate passes through to reach the crates.io state, and the component tests referenced in the security argument are what it involves: unit tests, linters with coding-style checks, and coverage computation, plus fuzzing for the components handling untrusted input. A crate that cannot produce coverage numbers is not going to be published, which is a reasonable bar for code that ends up in a hypervisor.

The SECURITY.md file is worth noting separately for anyone using these crates with untrusted workloads, and the threat model documentation for vm-superio is given as the example of what a customer can read to improve the security of their own solution.

The repository also carries infrastructure for the effort itself, including a .github directory, an .mdformat.toml for Markdown formatting and an ospp directory. The maintenance model is documented rather than implicit, which is what you want from a project whose crates land in other companies' production hypervisors.

Editorial conclusion

Use the rust-vmm community repository as the map of the ecosystem, and prefer consuming published crates from crates.io over tracking a staging repository, because the production ready version lives on the registry while development happens in the rust-vmm git repos. Do not start a new virtualization component without reading CONTRIBUTING.md and the publishing requirements list first, since a crate has to pass production requirements, common build-time tests and coverage before it is pushed. Before you depend on any component, check the threat model documentation for the ones that handle untrusted input, and note that the repository itself is documentation, so the licence is not the one to look for, the licence of the individual crate is.

Frequently asked questions

Official sources

1. Issues
2. README
3. rust-vmm/community on GitHub