Introduction

cloud-container is a builder for a custom initramfs image that allows running containers on cloud-hypervisor. The container root is served over virtiofs.

The initramfs does the following:

• Add all required virtio modules to support virtiofs, pci, and disks
• Expose environment variables from /etc/environment to the container entrypoint. A container manager can simply write down the /etc/environment file in the container root before booting.
• Pre-mount attached disks to configured endpoints
• Configure network interface via cmdline argument passed to the kernel

Kernel Requirements

This repository builds only the initramfs. You must provide a compatible Linux kernel separately.

Tested with Linux 6.8 (or later). Ensure your kernel includes:

• CONFIG_VIRTIO=y, CONFIG_VIRTIO_PCI=y, CONFIG_VIRTIO_BLK=y, CONFIG_VIRTIO_NET=y
• CONFIG_VIRTIO_FS=y (for virtiofs support)
• Basic filesystem support (ext4, vfat, etc.)

Use the config file from this repo as a reference when building your kernel.

Building

Requirements: docker

Build the initramfs:

./build.sh

This produces:

• output/initramfs-linux.img — the initramfs image
• output/hypervisor-fw — cloud-hypervisor firmware

Testing with cloud-hypervisor

Requirements: cloud-hypervisor, a Linux kernel (bzImage)

Extract or mount a container rootfs, then run:

cloud-hypervisor \
  --kernel /path/to/bzImage \
  --initramfs output/initramfs-linux.img \
  --cmdline "console=ttyS0 root=/dev/vda" \
  --console off \
  --serial tty

To edit environment variables available to your entrypoint, edit <rootfs>/etc/environment

See test.sh for a more complete example.