Git Product home page Git Product logo

alpine-make-vm-image's Introduction

Make Alpine Linux VM Image

Build Status

This project provides a script for making customized Alpine Linux disk images for x86_64 and aarch64 [1] 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).

Tip
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 and qemu-nbd tools

  • rsync (needed only for --fs-skel-dir)

  • sfdisk (needed only for --partition, --boot-mode UEFI and non-x86 architectures)

  • mdev or udevadm (needed only for --partition, --boot-mode UEFI and non-x86 architectures if device hotplug doesn’t work)

  • e2fsprogs (for ext4), btrfs-progs (for Btrfs), or xfsprogs (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.13.0/alpine-make-vm-image \
    && echo '0fe2deca927bc91eb8ab32584574eee72a23d033  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 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 aarch64 image with Alpine v3.18 or older

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 an older branch of Alpine Linux, you can, but you must install the kernel from the v3.19 branch (or newer). This is relatively safe because the kernel package doesn’t have any dynamic dependencies.

  1. Create a repositories file with a pinned main repository from v3.19, e.g.:

    @v319 https://dl-cdn.alpinelinux.org/alpine/v3.19/main
    https://dl-cdn.alpinelinux.org/alpine/v3.18/main
    https://dl-cdn.alpinelinux.org/alpine/v3.18/community
  2. Run alpine-make-vm-image with the options --repositories-file ./repositories and --packages linux-virt@v319 (or linux-lts@v319 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 v3.19 branch.

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.


1. Supported since Alpine Linux v3.19. See Create aarch64 image with Alpine v3.18 or older.

alpine-make-vm-image's People

Contributors

jirutka avatar roboman2444 avatar hpresnall avatar ofrzeta avatar olljanat avatar xpecex avatar petrm avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.