How to use Kata Containers with virtio-fs

Update for Kata Containers 1.7 and later

This HowTo is obsolete as of Kata Containers 1.7. virtio-fs has been included in Kata Containers and can be enabled as described in the official Kata Containers documentation. It is no longer necessary to build from virtio-fs repositories since mainline Kata Containers now includes virtio-fs.


This document describes how to set up Kata Containers with virtio-fs. Container images will be exposed to the sandbox VM using virtio-fs.

Use this guide if you wish to test or benchmark Kata Container workloads. It is easier to develop and debug virtio-fs standalone without Kata due to the smaller number of components involved. A guide for manually running QEMU with virtio-fs is available here.

Kata Containers is an OCI runtime that runs containers inside a virtual machine for better isolation. Docker and Kubernetes (CRI-O) can be configured to launch Kata Containers instead of their default OCI runtimes.

Each VM is called a sandbox. In Kubernetes a sandbox can be thought of the same thing as a pod.

Containers run inside sandboxes. Each sandbox contains an agent process that communicates with the Kata runtime on the host. Commands include creating new containers, executing processes inside containers, querying sandbox information, etc.



The following components need to be built:

  1. A guest kernel with virtio-fs support
  2. A QEMU with virtio-fs support
  3. The example virtio-fs daemon (virtiofsd)
  4. Kata Containers with virtio-fs support
  5. A Kata Containers initramfs with virtio-fs support

The instructions assume that you already have available a Linux host on which you can build and run the components.

The guest kernel

On the host, download the virtio-fs kernel tree by:

git clone

Configure and build this kernel with the following .config file:

wget -O .config
make -j$(nproc)

Building QEMU

On the host, download and install the virtio-fs QEMU tree by:

git clone
cd qemu
./configure --target-list=x86_64-softmmu
make -j$(nproc)
and in the same tree, the virtio-fs daemon needs to be built:
make -j$(nproc) virtiofsd

Building Kata Containers

Setting up environment variables

Decide where you want Go to put source code and packages:

export GOPATH=$HOME/go

Decide where you want to build the sandbox root filesystem:

export ROOTFS_DIR=$GOPATH/src/

Cloning Kata Containers repositories

Kata consists of several components, each with its own git repository. You need them all.

go get -d -u
go get -d -u
go get -d -u
go get -d -u
go get -d -u

Ensure you are on Kata 1.6.1:

(cd $GOPATH/src/ && git checkout 1.6.1)
(cd $GOPATH/src/ && git checkout 1.6.1)
(cd $GOPATH/src/ && git checkout 1.6.1)
(cd $GOPATH/src/ && git checkout 1.6.1)

Use the virtio-fs repositories for Kata components that require virtio-fs integration:

    cd $GOPATH/src/
    git remote add virtio-fs
    git fetch virtio-fs
    git checkout virtio-fs/virtio-fs
    cd -

Building the runtime

The runtime presents an OCI-compliant runtime interface to Docker and CRI-O. This is where sandbox setup happens and containers are orchestrated.

cd $GOPATH/src/

Building the proxy

The proxy forwards communications between the host and the sandbox.

cd $GOPATH/src/

Building the shim

The shim is a placeholder process on the host that forwards terminal I/O and signals to the actual container process running inside the sandbox.

cd $GOPATH/src/

Building the Kata Containers initramfs

Build the Fedora root file system:

cd $GOPATH/src/
./ clearlinux

Now build the sandbox initramfs:

cd $GOPATH/src/

Configuring Kata

The Kata configuration file controls the behavior of all Kata components.

wget -O /etc/kata-containers/configuration.toml

Set the following [hypervisor.qemu] variables:

Set the following [proxy.kata] variables:

Set the following [shim.kata] variables:

Also set all enable_debug variables to true for verbose output.

Add the Kata OCI runtime to Docker:

# mkdir -p /etc/systemd/system/docker.service.d
# cat >/etc/systemd/system/docker.service.d/kata-containers.conf
ExecStart=/usr/bin/dockerd-current -D \
          --add-runtime oci=/usr/libexec/docker/docker-runc-current \
          --add-runtime kata-runtime=YOUR_GOPATH/src/ \
          --default-runtime=oci \
          --containerd /run/containerd.sock \
          --userland-proxy-path=/usr/libexec/docker/docker-proxy-current \
          --init-path=/usr/libexec/docker/docker-init-current \
          $OPTIONS \
          $ADD_REGISTRY \
          $BLOCK_REGISTRY \
# sed -i "s%YOUR_GOPATH%$GOPATH%g" /etc/systemd/system/docker.service.d/kata-containers.conf
# systemctl daemon-reload
# systemctl restart docker

Ensure there are enough hugepages available on the host for the Kata sandbox VM. The default sandbox RAM size is 2G, so reserve 1024 * 2MB hugepages. This is necessary since QEMU is launched with the memory options (share=on) required by vhost-user.

sysctl vm.nr_hugepages=1024

Running containers

Launch a container:

docker run --runtime kata-runtime -it busybox sh