This project provides a script for making customized Alpine
Linux disk images for x86_64 and aarch64
virtual machines. You can choose between BIOS mode (using
Syslinux, only for x86_64) and UEFI mode
(using Linux EFI
stub). It’s quite
simple (400 LoC of shell), fast (~32 seconds on GitHub Actions),
requires minimum dependencies (QEMU and filesystem tools).
aarch64 currently only works with the kernel (linux-virt or linux-lts)
from Alpine edge! See Create Alpine v3.18 (latest-stable) image for
aarch64 for more information and a workaround.
Don’t need VM, just wanna chroot into Alpine Linux? Try
alpine-chroot-install!
Or do you want to create a custom rootfs? Then
alpine-make-rootfs
is for you!
Requirements
-
Linux system with common userland (Busybox or GNU coreutils)
-
POSIX-sh compatible shell (e.g. Busybox ash, dash, Bash, ZSH)
-
qemu-img
andqemu-nbd
tools -
rsync
(needed only for--fs-skel-dir
) -
sfdisk
(needed only for--partition
,--boot-mode UEFI
and
non-x86 architectures) -
mdev
orudevadm
(needed only for--partition
,
--boot-mode UEFI
and non-x86 architectures if device hotplug
doesn’t work) -
e2fsprogs
(for ext4),btrfs-progs
(for Btrfs), orxfsprogs
(for XFS) -
dosfstools
(needed only for--boot-mode UEFI
and non-x86
architectures)
All dependencies except the first two are automatically installed by the
script when running on Alpine Linux.
Usage
Read documentation in alpine-make-vm-image. See
.github/workflows/ci.yml for GitHub Actions
example.
You can copy alpine-make-vm-image into your
repository or download it on demand, e.g.:
wget https://raw.githubusercontent.com/alpinelinux/alpine-make-vm-image/v0.12.0/alpine-make-vm-image \
&& echo '75aafcb883155bcaad9ad0dadb3e22e082152c1e alpine-make-vm-image' | sha1sum -c \
|| exit 1
Or, if you are on Alpine Linux, you can simply install the
alpine-make-vm-image
package.
Howtos
Create Alpine v3.18 (latest-stable) image for aarch64
The Linux kernel (linux-virt, linux-lts or linux-edge package) in
Alpine v3.18 and earlier doesn’t have
EFI_ZBOOT enabled,
so EFI stub cannot load a compressed vmlinuz. We backported it to v3.18,
but then we had to revert it due to a problem with Grub (see
alpine/aports#15263).
If you want to build an image with a stable branch of Alpine Linux, you
can, but you must install the kernel from the edge branch. This is
relatively safe because the kernel package doesn’t have any dynamic
dependencies and the version in v3.18 and edge will be in sync at least
until v3.19 is released.
-
Create a
repositories
file with a pinned main repository from
edge, e.g.:@edge https://dl-cdn.alpinelinux.org/alpine/edge/main https://dl-cdn.alpinelinux.org/alpine/v3.18/main https://dl-cdn.alpinelinux.org/alpine/v3.18/community
-
Run alpine-make-vm-image with the options
--repositories-file ./repositories
and
--packages linux-virt@edge
(orlinux-lts@edge
if you use
--kernel-flavor lts
).
This will first install linux-virt from v3.18, but in the later step
it will reinstall it from the edge branch.
Create images for aarch64 on x86_64 host
All you need to do is install the QEMU User space
emulator for aarch64
and register it in
binfmt_misc as
the interpreter for aarch64 binaries.
On Alpine Linux
apk add qemu-aarch64 qemu-openrc
rc-service qemu-binfmt start
On Debian/Ubuntu
apt-get install -y --no-install-recommends binfmt-support qemu-user-static
update-binfmts --enable
On Fedora
dnf install qemu-user-static
On GitHub Actions
- name: Install qemu-aarch64 and register in binfmt
uses: jirutka/setup-alpine@v1
with:
arch: aarch64
See .github/workflows/ci.yml for a complete
example.
After that, run alpine-make-vm-image with the option --arch aarch64
.
Create image for VMware (ESXi)
VMware and disk images (virtual disks) is one big mess. You can find
that VMware uses the VMDK format, but the problem is that this is not a
single format. Actually it has many subformats with very different
structure and various (in)compatibility with VMware hypervisors.
When I’ve created a disk image using qemu-img create -f vmdk
or
converted Qcow2 to VMDK using qemu-img convert -O vmdk
, vSphere client
loaded this image without any problem, but the data was corrupted.
Eventually I found in some old documentation that ESXi does not support
“sparse” disks…
So after many trials I found out that the least bad and functional
solution is to create Qcow2 image and then convert it to VMDK using:
qemu-img convert -f qcow2 -O vmdk -o adapter_type=lsilogic,subformat=monolithicFlat alpine.qcow2 alpine.vmdk
Unfortunately, this creates a “thick” image, i.e. its size equals the
“provisioned space”, not actually used space as in Qcow2. However, you
can compress it with gzip to avoid transferring multiple gigabytes of
zeros over network.
License
This project is licensed under MIT
License. For the full text of the
license, see the LICENSE file.