KubeFire runs Kubernetes clusters as Firecracker microVMs on one host

What KubeFire actually runs underneath

KubeFire is a tool to create and manage Kubernetes clusters running on Firecracker microVMs via weaveworks/ignite. The word microVM is doing the important work in that sentence, because a Firecracker virtual machine has its own kernel and its own root filesystem, unlike a container, which shares the host kernel.

That distinction is the whole reason the tool exists. A cluster of containers on one host shares a kernel, shares the network namespace and shares the failure domain, and a multi-tenant setup on top of that has isolation you did not design. MicroVMs give each node a real kernel boundary, which is what you want when the nodes are running different Kubernetes versions or different distributions, or when the tenant is not you.

The README's list of design choices is short. It uses an independent root filesystem and kernel from OCI images, rather than traditional VM images like qcow2 or vhd. That means the node images are pulled from a container registry the same way any other artefact is, and the same way the kernel is. It uses containerd to manage the Firecracker processes. And it supports different cluster bootstrappers to provision the Kubernetes clusters, listing Kubeadm, K3s, RKE2 and K0s.

The bootstrappers matter more than they might appear. Kubeadm is the upstream kubeadm flow, K3s and RKE2 are the lightweight and enterprise distributions with their own opinions about what to run, and K0s is a lightweight Kubernetes distribution. Choosing among them changes what a node actually is, and the tool treats them as interchangeable, which is convenient and slightly lossy.

Architecture support covers x86_64/AMD64 and ARM64/AARCH64, which the README ties to the availability of K3s, RKE2 and K0s on those platforms. The primary language is Go, the licence is Apache-2.0, the repository is not archived, and the last push was on 2026-05-25.

Installing KubeFire and the prerequisites it puts on your host

There are three installation routes, and the prerequisites step is the one that will affect your host the most.

For official releases, the README gives a shell install:

curl -sfSL https://raw.githubusercontent.com/innobead/kubefire/master/hack/install-release-kubefire.sh | bash

Or, if you use huber, a single command:

huber install kubefire

For development, the README asks for Go 1.14 to be installed and then a make target that builds and installs kubefire into the GOBIN path:

make install

The prerequisites are installed separately, and this is the step that needs root. To be able to run kubefire commands without issues like node or cluster management problems, you run kubefire install with root permission, or sudo without a password. The steps it performs are checking that virtualization is supported, and installing the necessary components including runc, containerd, CNI plugins and Ignite. The minimum required versions are given in the README:

- RuncVersion >= v1.1.3 - ContainerdVersion >= v1.6.6 - CniVersion >= v1.1.1 - IgniteVersion >= v0.10.0

There is a matching pair of commands for the rest of the lifecycle: kubefire uninstall removes the prerequisites, and kubefire info checks the installation status.

The reason this deserves attention is that the tool installs containerd, runc and the CNI plugins onto the host, alongside Ignite. That is a container runtime and a network plugin stack installed system wide, on a machine that is presumably also running something else. The alternative approach is to run the whole toolchain inside a container or a VM, which is more isolation and more setup.

Quickstart: a kubeadm cluster in two commands

The quickstart is short enough to state in full, and the README says these commands are to quickly have a cluster deployed by kubeadm running in minutes:

kubefire install
kubefire cluster create demo

The first command is the prerequisite install described above, and the second creates a cluster named demo. There is a companion asciinema recording linked in the README, which is the fastest way to see the sequence of events a real run produces.

The cluster create command carries a substantial set of flags, and the README reproduces the full help output, which is worth reading because it defines what a node is. The bootstrapper flag takes kubeadm, k3s, rke2 or k0s. The image flag is the rootfs container image, defaulting to ghcr.io/innobead/kubefire-opensuse-leap:15.2, and the kernel-image flag defaults to ghcr.io/innobead/kubefire-ignite-kernel:4.19.125-amd64. The kernel arguments default to console=ttyS0 reboot=k panic=1 pci=off ip=dhcp security=apparmor apparmor=1.

The node shape is then explicit. master-count defaults to 1, master-cpu to 2, master-memory to 2GB and master-size to 10GB, with matching defaults for workers, except that worker-count defaults to 0. So a default cluster is a single master node with no workers, which is a control plane for experimentation rather than a cluster that runs workloads.

Two flags are worth singling out because they change the semantics rather than the size. The no-cache flag forgets caches, and the force flag recreates a cluster if it already exists. There is also a version flag for the Kubernetes version supported by the bootstrapper, and the README is explicit that the cluster creation will not be supported if the version is outside the supported set, which for kubeadm is the latest supported version and the last three minor releases.

The declarative config file, and why it is the better interface

The cluster create command provides detailed options, and it also provides a --config flag to accept a cluster configuration file. The README treats the config file as a first-class path rather than a convenience.

You generate a template and edit it:

$ kubefire cluster config-template > cluster.yaml

The template it emits is a small, readable document, and the README prints it in full so you can see every field:

name: ""
bootstrapper: kubeadm
pubkey: ""
prikey: ""
version: ""
image: ghcr.io/innobead/kubefire-opensuse-leap:15.2
kernel_image: ghcr.io/innobead/kubefire-ignite-kernel:4.19.125-amd64
kernel_args: console=ttyS0 reboot=k panic=1 pci=off ip=dhcp security=apparmor apparmor=1
extra_options: {}
deployed: false
master:
  count: 1
  memory: 2GB
  cpus: 2
  disk_size: 10GB
worker:
  count: 0
  memory: 2GB
  cpus: 2
  disk_size: 10GB

Then you create the cluster from it:

kubefire cluster create demo --config=cluster.yaml

Two things in that template matter. The pubkey and prikey fields hold the SSH key pair, so a generated config is a complete description of a cluster including how you get into its nodes. And the deployed field is part of the config, which tells you the tool tracks deployment state in the file itself rather than only in its own storage, so a config file can be committed and re-applied.

The alternative approach, and it is the honest comparison, is to script the flag form. The advantage of the file is that a cluster definition becomes a reviewable artefact that two people can diff, which is what you want when the cluster is a fixture for testing rather than a one-off.

Version selection and passing options through to the bootstrapper

Version handling is documented with worked examples, and the behaviour has two distinct modes.

Without a version, the cluster is created with the latest versions. With a minor version such as v1.18, you get the latest patch of that release. With a full version such as v1.18.8, you get exactly that build. And the README is clear about the boundary: if the version is outside the supported versions, described as the last three minor versions given the latest is v1.18, the cluster creation will not be supported.

That last part is the significant design decision in the whole tool. KubeFire is not a general Kubernetes installer that fetches whatever version you name. It constrains you to a window of versions, which means a version of Kubernetes that goes out of support stops being installable even though the tool itself is still there.

The bootstrapper is chosen with a flag, and the kubeadm case is shown directly:

kubefire cluster create demo --bootstrapper=kubeadm

For kubeadm specifically, the README notes it supports the latest supported version and the last three minor versions, with a link to the upstream stable version file. The other bootstrappers, K3s, RKE2 and K0s, have their own support rules linked in the same way.

There is also a way to pass extra deployment options through to the bootstrapper, which matters when the control plane components need configuration the tool does not expose. The --extra-options flag takes key-value pairs, and the README names the keys: init_options, api_server_options, controller_manager_options and scheduler_options. The pairs are separated by comma, and the example shows adding a service DNS domain to the init and an audit log retention to the API server:

kubefire cluster create demo --bootstrapper=kubeadm --extra-options="init_options='--service-dns-domain=yourcluster.local' api_server_options='--audit-log-maxage=10'"

The separation of concerns is the point. Options that belong to kubeadm go to kubeadm, options that belong to the kernel or the rootfs go in the config, and the tool does not try to be a single opaque blob of settings.

Where KubeFire is the wrong tool

Three limits, and the first is about the age of the software rather than its design.

The first is the version gap. The most recent tagged release listed is v0.3.10 from 2023-04-16, with v0.3.9 the day before and v0.3.8 from June 2022, while the last push was on 2026-05-25, so the repository receives work without a release. The Makefile then pins the components the tool installs: ContainerdVersion v1.6.20, IgniteVersion v0.10.0, CniVersion v1.1.1 and RuncVersion v1.1.6, and it links those values into the binary through ldflags so that kubefire can check the installation against the versions it expects. Those pins are more than a year behind current containerd and runc releases, and Ignite v0.10.0 is the version the whole design depends on. Nothing in the visible documentation says these are minimums rather than exact expectations.

The second is the host requirement. The tool installs containerd, runc and CNI plugins on your machine, and it needs virtualization support it checks for. That is a heavy footprint for a developer laptop that already has Docker on it, since the two container runtimes will conflict, and the answer to that conflict is a separate machine, a VM, or the containerised route in the wiki.

The third is the scope of a node. A Firecracker microVM is a real virtual machine with its own kernel, and the default kernel image is a 4.19 kernel, which is a long way from current. For a cluster used to test how an application behaves under different kernel and distribution combinations, that isolation is the whole point and the overhead is justified. For a cluster where you simply want some pods running, the overhead is not justified and a normal node pool is a better answer.

The alternative approach is to use a virtualisation-aware Kubernetes distribution or a sandboxed runtime, where the same isolation goal is reached through a different mechanism. The difference in approach is that KubeFire gives you a whole cluster, with a bootstrapper and a Kubernetes version, on one host under your control, whereas a sandboxed runtime gives you the isolation for the pods on a normal cluster. If what you need is several clusters to test upgrades against each other, KubeFire's model fits. If you need isolation for a multi-tenant cluster, the runtime-level approach is smaller.

Editorial conclusion

Adopt KubeFire if you want disposable or multi-tenant Kubernetes clusters on a single Linux host, since microVMs give each node its own kernel and root filesystem and the tool handles the whole lifecycle from a config file. Do not adopt it for a production cluster, because the last tagged release is v0.3.10 from 2023-04-16 and the component versions it pins, containerd v1.6.20, Ignite v0.10.0, CNI v1.1.1 and runc v1.1.6, are all well behind current releases. Verify first that your host supports the virtualisation KubeFire checks for, that the Kubernetes versions your bootstrapper supports still match the versions you need, that the kernel and rootfs images it defaults to still exist in ghcr.io, and that the ignition and containerd versions in your environment are compatible with what the pinned Makefile expects.

Frequently asked questions

Official sources

1. innobead/kubefire on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases