hetzner_robot_rhai/alpine-cloud_hypervisor.md

How to Install and Run Alpine Linux with Cloud Hypervisor

This guide walks you through installing Alpine Linux into a QCOW2 disk image using QEMU, and then running that image with Cloud Hypervisor. It includes all the steps you’ll need, from creating the disk, performing the OS install, preparing kernel/initramfs, and finally running the VM with Cloud Hypervisor.

---

Goal

• Install Alpine Linux into a disk image using QEMU
• Extract the installed kernel and initramfs from the disk
• Boot the VM with Cloud Hypervisor, using direct kernel/initramfs boot

---

Prerequisites

• Ubuntu (or Debian-based) host
• sudo privileges

---

Instructions

1. Install required tools

sudo apt update
sudo apt install -y qemu-utils wget curl qemu-system-x86 libguestfs-tools

2. Download Cloud Hypervisor binary

wget https://github.com/cloud-hypervisor/cloud-hypervisor/releases/download/v47.0/cloud-hypervisor-static
chmod +x cloud-hypervisor-static

3. Download Alpine Linux ISO

We will download the alpine-virt ISO, which is similar to the standard ISO but has a slimmed down kernel and is optimized for virtual systems.

wget https://dl-cdn.alpinelinux.org/alpine/v3.22/releases/x86_64/alpine-virt-3.22.1-x86_64.iso

4. Create a blank disk image

The command below will create a blank disk image called alpine-vm.qcow2 with a size of 2GB.

qemu-img create -f qcow2 alpine-vm.qcow2 2G

5. Install Alpine into the disk image

NOTE: Cloud Hypervisor does not emulate legacy BIOS/UEFI, so we use QEMU for the initial install.

qemu-system-x86_64 -m 1024M \
    -cdrom alpine-standard-3.22.1-x86_64.iso \
    -drive file=alpine-vm.qcow2,format=qcow2 \
    -boot d \
    -net nic -net user,hostfwd=tcp::2222-:22 \
    -nographic

• Inside the VM:
  • Log in as root (no password by default).
  • Run setup-alpine and complete the installation steps.

6. (Optional): Boot into the installed Alpine system with QEMU

1. Boot into VM:

qemu-system-x86_64 \
    -m 1024M \
    -drive file=alpine-vm.qcow2,format=qcow2 \
    -net nic -net user,hostfwd=tcp::2222-:22 \
    -nographic

2. Install curl and k3s on the VM:

apk update
apk add curl
curl -sfL https://get.k3s.io | sh -

7. Enable serial console in Alpine VM

Edit the /etc/update-extlinux.conf in the VM and set:

serial_port=0

This ensures the kernel output is available on the serial port, which we use later when launching the VM with Cloud Hypervisor (using the --serial tty command line argument).

8. Extract kernel, initramfs and kernel parameters from the installed disk

Note

: You only need to mount the QCOW2 disk once to get all necessary files and information.

1. Mount the disk using guestmount

sudo guestmount -a alpine-vm.qcow2 -i /mnt

2. Copy the kernel and initramfs:

cp /mnt/boot/vmlinuz-lts ./vmlinuz-lts
cp /mnt/boot/initramfs-lts ./initramfs-lts

3. Get the kernel command line parameters and the root UUID:

cat /mnt/boot/extlinux.conf

Look for the APPEND line under your boot label (e.g. LABEL lts). Example:

LABEL lts
  MENU DEFAULT
  MENU LABEL Linux lts
  LINUX vmlinuz-lts
  INITRD initramfs-lts
  APPEND root=UUID=8b578951-b524-42b9-a757-67fa90b56ec8 modules=sd-mod,usb-storage,ext4 quiet rootfstype=ext4

• Copy everything from root=UUID=... to the end of the line (after APPEND).
• You will use this as your kernel command line in Cloud Hypervisor

4. Unmount the disk

guestunmount /mnt

9. Boot Alpine VM with Cloud Hypervisor

Use the kernel and initramfs you extracted, and set the full kernel command line (adjust UUID and modules as needed):

./cloud-hypervisor-static \
  --kernel ./vmlinuz-lts \
  --initramfs ./initramfs-lts \
  --disk path=alpine-vm.qcow2 \
  --cpus boot=2 \
  --memory size=1024M \
  --net "tap=,mac=,ip=192.168.100.2,mask=255.255.255.0" \
  --serial tty \
  --cmdline "console=ttyS0 root=UUID=8b578951-b524-42b9-a757-67fa90b56ec8 modules=sd-mod,usb-storage,ext4 quiet rootfstype=ext4" \
  --console off

• Replace the UUID and modules with your values from step 8.