From a system's name to a running VM

the whole path in one deck for everyone

What image-garden is for and the path one system takes. Its entry in image-garden's list of systems becomes make rules when image-garden is built; at run time make downloads and verifies the cloud image, prepares a copy-on-write overlay with one cloud-init boot, and writes a .run script that boots it. allocate and spread build on that script.

On the map: start here

▶ Watch this deck — 8 scenes, ~6 min

01 One command, many systems

WHY IMAGE-GARDEN Ubuntu Fedora Debian Alpine openSUSE and more x86_64 · aarch64 · riscv64 · s390x · ppc64 · loongarch64 curl fetches the distribution's own cloud image QEMU runs it, on any of the six architectures $ image-garden make ubuntu-cloud-24.04.x86_64.run a script that boots it
Six distributions and five architectures on top; curl fetches a cloud image and QEMU runs it; the command image-garden make ubuntu-cloud-24.04.x86_64.run produces a script that boots the system

image-garden builds test VMs from distributions' own cloud images with curl and QEMU. image-garden make ubuntu-cloud-24.04.x86_64.run gives you a script that boots Ubuntu 24.04.

Say you maintain a tool that has to work on Ubuntu, Fedora, Debian and a handful of other distributions, and not only on x86 but on Arm and RISC-V too. You could keep a shelf of virtual machines by hand, and keep them all up to date. image-garden does it with tools you already have: curl, to fetch a distribution's own cloud image, and QEMU, to run it. You name the system you want, such as Ubuntu 24.04 on x86, and one make command gives you a script that boots it. This deck follows that one system from a few lines of data to a running machine.

Details and sources

Details

  • image-garden's four aims: test images for many operating systems, commonly available tools (curl and qemu), simple insecure access, and generated .run scripts that show the exact QEMU command (README.md:11-23).
  • The quick start makes ubuntu-cloud-24.04.x86_64.run and runs it (README.md:69-89).
  • The architectures in the data are x86_64, aarch64, riscv64, s390x, ppc64 and loongarch64 (rulegen.py:23-29). Which distribution runs on which is in the support matrix.

02 A list of systems becomes make rules general version

BUILD TIME ubuntu-cloud-24.04.x86_64 one entry in image-garden's list of systems image: cloud-images.ubuntu.com/… checksums: SHA256SUMS beside it arch: x86_64 boot: efi release: 24.04 the build before you run it generated rules rules written by hand image-garden.mk the image-garden command $ image-garden make … installed together: the one file make reads
image-garden's list of systems has a five-line entry for ubuntu-cloud-24.04.x86_64: image, checksums, architecture, boot type and release. When image-garden is built, the list becomes generated make rules, which are joined with hand-written rules into image-garden.mk, installed beside the image-garden command; image-garden make reads that one file

image-garden carries a list of the systems it knows. Its build turns that list into make rules and joins them with hand-written ones into image-garden.mk, installed beside the image-garden command.

Everything starts with a list. image-garden ships a description of every system it knows, and the one we follow, ubuntu-cloud-24.04.x86_64, takes five lines: where its image lives, where to find the checksums that prove the download is intact, the architecture, how it boots, and the release. When image-garden itself is built, long before you run it, that list is turned into make rules, one set per system. They're joined with rules written by hand into a single makefile, image-garden.mk. It's installed next to the image-garden command, and when you run image-garden make, it's the one file make reads.

Details and sources

Details

  • The entry followed in this deck is [ubuntu-cloud-24.04.x86_64] in data/ubuntu.ini: URL, SHA256SUMS, Arch=x86_64, Boot=efi, Release=24.04 (ubuntu.ini:237-242). The slide shows the five keys in plain words.
  • image-garden's build turns each data file into generated make rules and concatenates them, a list of every system and the hand-written makefiles into image-garden.mk (Makefile:48-64). The snap, the container and the distribution packages carry the file that build produced.
  • make install puts image-garden.mk in the include directory and the image-garden script in the bin directory (Makefile:30-46); the script runs make -f on that file (image-garden:982-993).

Read more

03 A section of data becomes make rules for contributors in place of the general version

BUILD TIME [ubuntu-cloud-24.04.x86_64] data/ubuntu.ini, one file per distribution URL=http://cloud-images.ubuntu.com/… SHA256SUMS=https://cloud-images.ubuntu… Arch=x86_64 Boot=efi Release=24.04 rulegen.py at build time 050-ubuntu.gen.mk 000-systems.mk mk/*.mk, by hand image-garden.mk the image-garden command installed together: all the command needs
The ubuntu-cloud-24.04.x86_64 section of data/ubuntu.ini, five keys long, goes into rulegen.py, which writes 050-ubuntu.gen.mk; with 000-systems.mk and the hand-written mk files it is joined into image-garden.mk, installed beside the image-garden command

rulegen.py turns each section of data/*.ini into make rules. The build concatenates data/000-systems.mk, mk/*.mk and data/050-*.gen.mk into image-garden.mk.

Everything starts in the data directory, with one INI file per distribution. The Ubuntu file has a section for each system, and the one we follow is five lines long: the image URL, the URL of its checksum file, the architecture, the boot type, and the release. When image-garden itself is built, a small Python program called rulegen reads these files and prints make rules for every section. The build then joins three parts into one makefile: a list of systems, the rules written by hand, and the generated ones. That file, image-garden.mk, is installed next to the image-garden command, and it's all the command needs.

Details and sources

Details

  • The section followed in this deck is [ubuntu-cloud-24.04.x86_64]: URL, SHA256SUMS, Arch=x86_64, Boot=efi, Release=24.04 (ubuntu.ini:237-242). The file's [META] section sets Group=ubuntu and Variant=cloud (ubuntu.ini:4-6).
  • rulegen.py takes INI files as arguments and prints make rules on standard output; with --systems-meta FILE it appends each system's group, release, architecture and boot type to FILE (rulegen.py:741-752).
  • The top-level Makefile runs ./rulegen.py data/X.ini > data/050-X.gen.mk per file, builds data/000-systems.mk from all of them, and concatenates data/000-systems.mk, the sorted mk/*.mk and the sorted data/050-*.gen.mk into image-garden.mk (Makefile:48-64).
  • make install puts image-garden.mk in the include directory and the image-garden script in the bin directory (Makefile:30-46); the script runs make -f on that file (image-garden:982-993).
  • The generated *.gen.mk files and image-garden.mk are build output and not in git.

04 Download, verify, link

DOWNLOAD AND VERIFY $ image-garden make ubuntu-cloud-24.04.x86_64.run SHA256SUMS the cloud image both over HTTPS through pkgproxy when there is one check against the checksum mismatch: delete both files, download once more systems sharing an image take turns ~/.cache/image-garden/dl/ubuntu/noble-server-cloudimg-amd64.img ~/.cache/image-garden/dl/ubuntu/ubuntu-cloud-24.04.x86_64.qcow2 -> that image shared and never changed: every VM of this system starts from it
image-garden make starts from the .run target; the SHA256SUMS list and the cloud image both come over HTTPS, through pkgproxy when there is one; the image is checked against the list, and on a mismatch both files are deleted and the download is tried once more; systems that share an image take turns; the verified image stays in the cache with a link named after the system

The checksum list and the image come over HTTPS, through pkgproxy if there is one, and nothing is used until they match. The download is cached and linked as ubuntu-cloud-24.04.x86_64.qcow2.

Now you type image-garden make, and the system's name with .run on the end. Make works backwards from that file, and the first thing it needs is the cloud image. image-garden fetches the distribution's checksum list, then the image itself, both over HTTPS, and through pkgproxy when you have one. A partial download is resumed. A mismatch throws both files away and tries once more. Two systems that share an image take turns, so it's fetched only once. The verified image stays in your cache, under the distribution's name, and make puts a link beside it named after the system. Every VM of this system starts from it, untouched.

Details and sources

Details

  • For a system with SHA256SUMS, the download rule runs image-garden download-with-sha256sums URL SUMS DIR FILE, then links DIR/<system>.qcow2 to the downloaded file (rulegen.py:510-514). SHA512SUMS takes precedence over SHA256SUM, which takes precedence over SHA256SUMS (rulegen.py:498-514).
  • Both URLs of the section are https://cloud-images.ubuntu.com/… (ubuntu.ini:238-239); every image definition uses https.
  • The checksum list is asked from pkgproxy's volatile files first, then from the origin (image-garden:211-269); the image is asked from pkgproxy by URL and checksum, then from the origin (image-garden:281-327).
  • A transfer that ends short (curl exit 18) or breaks (56) is resumed with --continue-at - (image-garden:310-326).
  • The download runs under flock on FILE.lock, so systems that share one image, such as ubuntu-core-24 and ubuntu-core-24+tpm, do not fetch it twice (image-garden:470-477).
  • The file is checked with sha256sum --check; on failure both the image and its checksum file are removed and the whole download runs once more (image-garden:480-559).
  • The cache directory is $XDG_CACHE_HOME/image-garden/dl (by default ~/.cache/image-garden/dl); the snap and the container put it elsewhere (image-garden:20-29, 000-garden.mk:9-12).
  • The README: "Images and their checksum lists are downloaded over HTTPS, through pkgproxy when one is available, and every image is checked against its checksum" (README.md:34-35). What becomes http is the guests' apt sources, so that pkgproxy can cache packages (README.md:32-33).

05 Prepared once, then powered off

PREPARED ONCE the download, unchanged qcow2 overlay, 64G records only the differences user-data meta-data seed ISO · cidata QEMU: the provisioning boot cloud-init: sets the passwords SSH password logins writes a few files disables itself powers off ubuntu-cloud-24.04.x86_64.qcow2 the prepared image ubuntu-cloud-24.04.x86_64.qcow2.log the console of that boot
A 64G qcow2 overlay is created on the unchanged download; user-data and meta-data are packed into a cidata seed ISO; QEMU boots the overlay with the seed once; cloud-init sets passwords, enables SSH password logins, disables itself and powers off, leaving a prepared image and its console log

A 64G copy-on-write overlay on the download, a cidata seed ISO, and one provisioning boot. cloud-init disables itself and powers off; the console log is ubuntu-cloud-24.04.x86_64.qcow2.log.

The download is never changed. Instead, make creates an overlay on top of it: a 64 gigabyte qcow2 disk that records only the differences. Then it writes two small files for cloud-init, user-data and meta-data, and packs them into a seed ISO labelled cidata. Now comes the one boot that does the work. QEMU starts the overlay with the seed attached as a CD-ROM. cloud-init sets the passwords, turns on SSH password logins, writes a few files, then disables itself and powers the machine off. When QEMU exits, make is done with the image, and the console log stays beside it.

Details and sources

Details

  • X.qcow2 is created with qemu-img create -f qcow2 -b <download> -F qcow2 X.qcow2 64G, then booted with the seed attached as a read-only virtio-blk CD-ROM, its output piped through tee X.qcow2.log (rulegen.py:593-610). The size is QEMU_IMG_SIZE = 64G (010-qemu.mk:8).
  • The seed ISO is made with xorriso -as genisoimage -volid cidata from the user-data and meta-data files (010-qemu.mk:268-279).
  • The common user-data template (010-qemu.mk:187-247): power_state powers off at once (line 190); ssh_pwauth: true (197); users root/root and a user named after the distribution with the same password and passwordless sudo (from 200); PermitRootLogin yes appended to sshd_config; datasource_list: [NoCloud]; the last command, touch /etc/cloud/cloud-init.disabled (246).
  • Ubuntu Core, Amazon Linux 2 and Gentoo differ; see per-distro quirks. The +tpm systems also start swtpm for this boot; see Secure Boot and TPM.

06 A script that boots it

RUN IT ubuntu-cloud-24.04.x86_64.run plain bash, the exact QEMU command QEMU_MEM_OPTION="-m 4096" QEMU_SMP_OPTION="-smp 4" $ ./ubuntu-cloud-24.04.x86_64.run login prompt; changes are kept $ image-garden allocate --spread … <ADDRESS localhost:PORT> background · -snapshot · SSH on a local port spread image-garden discard
The .run script is bash with the exact QEMU command and QEMU option variables; running it boots to a login prompt and keeps changes; image-garden allocate runs it in the background with -snapshot and SSH on a local port and prints an ADDRESS line; spread uses it and image-garden discard stops the VM

.run boots in the foreground and keeps changes. image-garden allocate boots it in the background with -snapshot and prints <ADDRESS localhost:PORT> for spread; discard stops it.

Last comes the file you asked for, the .run script. It's plain bash with the exact QEMU command inside, so you can read it, copy it, or change the memory and CPU count with environment variables. Run it and the machine boots to a login prompt and keeps its changes. For tests you'll more often use image-garden allocate. It starts the same script in the background, in snapshot mode so nothing is written back, forwards a free local port to SSH, and prints the address. spread uses exactly that, and image-garden discard stops the machine when the tests are done.

Details and sources

Details

  • The .run script is written line by line by a make macro; it fills defaults for QEMU_MEM_OPTION, QEMU_SMP_OPTION, QEMU_DISPLAY_OPTION and the other QEMU_*_OPTION variables, adds "$@" and runs QEMU (010-qemu-x86_64.mk:49-108). With --query it prints the memory size and the users (010-qemu.mk:63-92). The two values on the slide are examples, not defaults: the default memory is 2048 MiB (010-qemu.mk:9).
  • image-garden allocate builds the system if needed, picks a free port between 5000 and 9999 (image-garden:1100), forwards 127.0.0.1:PORT to the guest's port 22 (image-garden:1107), and runs the .run script with -snapshot (unless QEMU_SNAPSHOT_OPTION says otherwise), -daemonize and a pid file (image-garden:1153-1163).
  • With --spread it waits for the SSH banner and prints <ADDRESS localhost:PORT>, else just localhost:PORT (image-garden:1203-1205).
  • spread's garden backend is type: adhoc, with allocate running exec image-garden allocate --spread and discard running exec image-garden discard (spread.yaml:24-60).

07 What sits around the core

AROUND THE CORE image-garden pkgproxy on the host packages, snaps, Go modules and the cloud images three ways in packages · your QEMU container · patched QEMU snap · + pkgproxy, spread built on it snap/rock/charmcraft-gitlab-ci spread-gitlab-ci image-garden-action GitLab: the container · GitHub: the snap
image-garden in the centre; pkgproxy on the left caches packages, snaps, Go modules and cloud images; on the right the three ways to install: native packages with your QEMU, the container and the snap with a patched QEMU, the snap adding pkgproxy and spread; at the bottom the projects built on it: the craft GitLab components, spread-gitlab-ci and image-garden-action

pkgproxy caches what guests download. image-garden ships as native packages, a container and a snap. GitLab CI components and a GitHub action are built on it.

Around this core sit three more pieces. The first is pkgproxy, a caching proxy on the host. When it's there, the user-data teaches the guest to fetch packages, snaps and Go modules through it, and cloud images come through it too. The second is how you get image-garden itself. A native package uses your own QEMU. The container and the snap bring a patched QEMU, and the snap also brings pkgproxy and spread as components. The third is the projects built on it: GitLab CI components that build snaps, rocks and charms or run spread inside the container, and a GitHub action that installs the snap.

Details and sources

Details

  • pkgproxy reaches a guest through a QEMU guestfwd to 10.0.2.100:3142 when its socket is local, or through a URL (010-qemu.mk:20-44). The user-data then asks pkgproxy once, adds a pkgproxy hosts entry, runs pkgproxy's apt setup on Debian and Ubuntu and its snap setup on all but Alpine, and sets GOPROXY (010-qemu.mk:127-185).
  • Checksum lists and images are fetched through pkgproxy, with the origin as the fallback (image-garden:211-327).
  • The snap declares components for QEMU per architecture, pkgproxy, swtpm, spread and spread-plus (snapcraft.yaml:45-119). The snap and the container build QEMU with qemu-patches/guestfwd-unix-socket.patch; a native package uses the distribution's QEMU.
  • The README compares the three installs (README.md:96-106).
  • The CI projects are separate repositories: snapcraft-, rockcraft-, charmcraft- and spread-gitlab-ci build on the image-garden container, image-garden-action installs the snap on GitHub runners.

08 Where to go from here

ROADS From name to a VM What runs where distributions and architectures Build time how the system list becomes rules First boot what cloud-init changes The target chain each make target in turn Three ways in snap, container, packages Why pkgproxy download once Built on it CI components, action
Seven roads from this deck: the support matrix, build time, first boot, the runtime targets, three ways to install, pkgproxy and the projects built on image-garden

Next: the support matrix, the build-time data, the first boot, the runtime targets, the three ways to install, pkgproxy and the projects built on it.

That's the whole path: data, rules, a verified download, one provisioning boot, and a script. From here, the systems district shows every distribution and architecture. Build time shows contributors how the list of systems becomes rules, and first boot lists every change cloud-init makes. The runtime district takes each make target and command in turn. If you're installing image-garden, start with the comparison of the snap, the container and native packages. And if you run it in CI, the pkgproxy district and the projects built on image-garden come next.

Details and sources

Details

  • The path in one line: data/ubuntu.ini → rulegen.py → image-garden.mk → download and verify → X.qcow2 overlay and one provisioning boot → X.run → allocate.
  • This map describes image-garden at release v0.8.1 (commit a5785d52). Source links point at f6a1d87e, whose code v0.8.1 shares apart from version strings.

Read more

Basis of the statements on this page

Everything here was read in the image-garden source at the commit in garden.commit ("code"); the file names for ubuntu-cloud-24.04.x86_64 follow from the rules ("derived"). Nothing was run for this page.

The files make builds, in order

For image-garden make ubuntu-cloud-24.04.x86_64.run, with DL the download cache (~/.cache/image-garden/dl for a source install):

StepFileMade by
1DL/ubuntu/ubuntu-cloud-24.04.x86_64.urlthe URL key, written out
2DL/ubuntu/ubuntu-cloud-24.04.x86_64.filenamethe local file name, here the URL's basename
3DL/ubuntu/noble-server-cloudimg-amd64.imgimage-garden download-with-sha256sums
4DL/ubuntu/ubuntu-cloud-24.04.x86_64.qcow2a symlink to step 3
5ubuntu-cloud-24.04.x86_64.user-data, .meta-datathe cloud-init templates
6ubuntu-cloud-24.04.x86_64.seed.isoxorriso, volume cidata
7efi-code.x86_64.img, efi-vars.x86_64.imgcopied from the host's or the snap's EDK2
8ubuntu-cloud-24.04.x86_64.efi-code.qcow2, .efi-vars.qcow2qemu-img convert, one variable store per system
9ubuntu-cloud-24.04.x86_64.qcow2 (and .qcow2.log)a 64G overlay on step 4, then the provisioning boot
10ubuntu-cloud-24.04.x86_64.runthe launcher script

Files 5 to 10 are made, in the order make -n prints them, in the current directory, or in .image-garden/ when that directory exists. More in the target chain.

The commands

CommandWhat it does
image-garden make GOALruns make on image-garden.mk for GOAL, such as SYSTEM.run or SYSTEM.qcow2
image-garden make list-systemslists every system
./SYSTEM.runboots the system in the foreground; changes are kept
./SYSTEM.run --queryprints the memory size and the users and passwords
image-garden allocate [--spread] SYSTEMboots it in the background with -snapshot and SSH on a local port
image-garden discard ADDRESS or -astops one allocated VM, or all
image-garden pslists allocated VMs
image-garden rebase SYSTEM.ARCHpoints a prepared overlay at its download in this machine's cache, even when the old cache is gone; SYSTEM.ARCH.qcow2 works too
image-garden make clean, distcleanremoves what make built in the project and the cache links; distclean also removes the downloads

Roads from here

START HERE

SYSTEMS · distributions

RUNTIME · make rules and the CLI

BUILT ON IT · CI integrations

FIRST BOOT · cloud-init changes

PKGPROXY · caching for guests

BUILD TIME · data and rules