Alpine Cloud Hypervisor Image

Build customized Alpine Linux disk images (UEFI) for Cloud Hypervisor. The core builder is based on alpine-make-vm-image.

Chinese README: README_CN.md

What It Does

• Creates a bootable disk image (qcow2/raw) with GPT + EFI System Partition.
• Installs Alpine base system and a selected kernel flavor.
• Supports extra packages, filesystem skeleton, and post-install scripts.

Requirements (Host)

• Linux with common userland (Busybox or GNU coreutils)
• POSIX-sh compatible shell (ash, dash, bash, zsh)
• qemu-img, qemu-nbd
• gdisk, mdev or udevadm
• rsync
• e2fsprogs or btrfs-progs or xfsprogs
• dosfstools (for mkfs.vfat)

If you use Docker, you only need qemu-img and qemu-nbd on the host.

Quick Start (Docker)

Check NBD module:

modprobe nbd

Build a qcow2 image (Alpine v3.22):

docker run -it --rm \
  -v ./example:/alpine-make-vm-image \
  -v ./alpine-make-vm-image:/alpine-make-vm-image/alpine-make-vm-image \
  --privileged \
  -v /var/lock:/var/lock \
  -v /dev:/dev \
  -v ./example/rootfs:/rootfs \
  tces1/alpine-make-vm-image:latest \
  bash -c './alpine-make-vm-image --image-format qcow2 --repositories-file ./repositories --kernel-flavor lts --image-size 5G --packages "$(cat ./packages)" --fs-skel-dir /rootfs --fs-skel-chown root:root --script-chroot alpine-v3.22-$(date +%Y-%m-%d).qcow2 -- ./configure.sh'

Output will be in ./example:

• alpine-v3.22-YYYY-MM-DD.qcow2

Run With Cloud Hypervisor

Download the UEFI firmware for Cloud Hypervisor (edk2):

wget -O CLOUDHV.fd https://github.com/cloud-hypervisor/edk2/releases/latest/download/CLOUDHV.fd

Convert qcow2 to raw:

qemu-img convert -p -f qcow2 -O raw \
  ./example/alpine-v3.22-$(date +%Y-%m-%d).qcow2 \
  ./example/alpine-v3.22-$(date +%Y-%m-%d).raw

Boot:

cloud-hypervisor \
  --firmware ./CLOUDHV.fd \
  --disk path=alpine-v3.22-$(date +%Y-%m-%d).raw \
  --cpus boot=8 \
  --memory size=8192M \
  --serial tty \
  --console off \
  --net "tap=tap_hostfw,mac=,ip=,mask="

License

MIT. See LICENSE.