customized alpine images
Find a file
2019-12-22 17:34:39 +01:00
example Change default ALPINE_BRANCH to v3.11 2019-12-22 15:26:30 +01:00
.editorconfig Prepare project 2017-08-29 20:01:51 +02:00
.travis.yml CI: Change dist to bionic 2019-12-22 17:31:34 +01:00
alpine-make-vm-image Add option to activate serial console 2019-12-22 17:26:14 +01:00
LICENSE License: Bump year 2019-12-22 17:34:39 +01:00
Makefile Makefile: Declare "install" as PHONY and sort targets 2017-11-15 13:18:59 +01:00
README.adoc Readme: Update LoC and run time 2019-12-22 17:32:50 +01:00

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

= Make Alpine Linux VM Image
:script-name: alpine-make-vm-image
:script-sha1: 979de8f0ae8646ae1b6738e039e9dd0555628d60
:gh-name: alpinelinux/{script-name}
:version: 0.5.0

ifdef::env-github[]
image:https://travis-ci.org/{gh-name}.svg?branch=master["Build Status", link="https://travis-ci.org/{gh-name}"]
endif::env-github[]

This project provides a script for making customized https://alpinelinux.org/[Alpine Linux] disk images for virtual machines.
Its quite simple (300 LoC of shell), fast (~22 seconds on Travis CI, without Travis VM initialization) and requires minimum dependencies (QEMU and filesystem tools).

TIP: Dont need VM, just want to chroot into Alpine Linux (e.g. on CI)?
     Try https://github.com/alpinelinux/alpine-chroot-install[alpine-chroot-install]!


== 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 (automatically installed by the script if running on Alpine)
* e2fsprogs (for ext4), btrfs-progs (for Btrfs), or xfsprogs (for XFS) (automatically installed by the script if running on Alpine)


== Usage

Read documentation in link:{script-name}[{script-name}].
See link:.travis.yml[.travis.yml] for Travis example.

You can copy link:{script-name}[{script-name}] into your repository or download it on demand, e.g.:

[source, sh, subs="+attributes"]
wget https://raw.githubusercontent.com/{gh-name}/v{version}/{script-name} \
    && echo '{script-sha1}  {script-name}' | sha1sum -c \
    || exit 1


== Pitfalls

=== Creating 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 Ive 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:

[source, sh]
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 http://opensource.org/licenses/MIT/[MIT License].
For the full text of the license, see the link:LICENSE[LICENSE] file.