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
01 One command, many systems
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 (
curlandqemu), simple insecure access, and generated.runscripts that show the exact QEMU command (README.md:11-23). - The quick start makes
ubuntu-cloud-24.04.x86_64.runand runs it (README.md:69-89). - The architectures in the data are
x86_64,aarch64,riscv64,s390x,ppc64andloongarch64(rulegen.py:23-29). Which distribution runs on which is in the support matrix.
Read more
02 A list of systems becomes make rules general version
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]indata/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 installputsimage-garden.mkin the include directory and theimage-gardenscript in the bin directory (Makefile:30-46); the script runsmake -fon that file (image-garden:982-993).
Read more
- The support matrix: every system in the list.
- Changing what cloud-init does: your own
.image-garden.mk. - Contributors: the .ini files, what rulegen.py emits, how image-garden.mk is put together.
03 A section of data becomes make rules for contributors in place of the general version
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 setsGroup=ubuntuandVariant=cloud(ubuntu.ini:4-6). rulegen.pytakes INI files as arguments and prints make rules on standard output; with--systems-meta FILEit 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.mkper file, buildsdata/000-systems.mkfrom all of them, and concatenatesdata/000-systems.mk, the sortedmk/*.mkand the sorteddata/050-*.gen.mkintoimage-garden.mk(Makefile:48-64). make installputsimage-garden.mkin the include directory and theimage-gardenscript in the bin directory (Makefile:30-46); the script runsmake -fon that file (image-garden:982-993).- The generated
*.gen.mkfiles andimage-garden.mkare build output and not in git.
04 Download, verify, link
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 runsimage-garden download-with-sha256sums URL SUMS DIR FILE, then linksDIR/<system>.qcow2to the downloaded file (rulegen.py:510-514).SHA512SUMStakes precedence overSHA256SUM, which takes precedence overSHA256SUMS(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
flockonFILE.lock, so systems that share one image, such asubuntu-core-24andubuntu-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
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.qcow2is created withqemu-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 throughtee X.qcow2.log(rulegen.py:593-610). The size isQEMU_IMG_SIZE = 64G(010-qemu.mk:8).- The seed ISO is made with
xorriso -as genisoimage -volid cidatafrom the user-data and meta-data files (010-qemu.mk:268-279). - The common user-data template (010-qemu.mk:187-247):
power_statepowers off at once (line 190);ssh_pwauth: true(197); usersroot/rootand a user named after the distribution with the same password and passwordless sudo (from 200);PermitRootLogin yesappended 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.
Read more
06 A script that boots it
.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
.runscript is written line by line by a make macro; it fills defaults forQEMU_MEM_OPTION,QEMU_SMP_OPTION,QEMU_DISPLAY_OPTIONand the otherQEMU_*_OPTIONvariables, adds"$@"and runs QEMU (010-qemu-x86_64.mk:49-108). With--queryit 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 allocatebuilds the system if needed, picks a free port between 5000 and 9999 (image-garden:1100), forwards127.0.0.1:PORTto the guest's port 22 (image-garden:1107), and runs the.runscript with-snapshot(unlessQEMU_SNAPSHOT_OPTIONsays otherwise),-daemonizeand a pid file (image-garden:1153-1163).- With
--spreadit waits for the SSH banner and prints<ADDRESS localhost:PORT>, else justlocalhost:PORT(image-garden:1203-1205). - spread's
gardenbackend istype: adhoc, withallocaterunningexec image-garden allocate --spreadanddiscardrunningexec image-garden discard(spread.yaml:24-60).
Read more
07 What sits around the core
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
guestfwdto10.0.2.100:3142when its socket is local, or through a URL (010-qemu.mk:20-44). The user-data then asks pkgproxy once, adds apkgproxyhosts entry, runs pkgproxy's apt setup on Debian and Ubuntu and its snap setup on all but Alpine, and setsGOPROXY(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
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.qcow2overlay 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
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):
| Step | File | Made by |
|---|---|---|
| 1 | DL/ubuntu/ubuntu-cloud-24.04.x86_64.url | the URL key, written out |
| 2 | DL/ubuntu/ubuntu-cloud-24.04.x86_64.filename | the local file name, here the URL's basename |
| 3 | DL/ubuntu/noble-server-cloudimg-amd64.img | image-garden download-with-sha256sums |
| 4 | DL/ubuntu/ubuntu-cloud-24.04.x86_64.qcow2 | a symlink to step 3 |
| 5 | ubuntu-cloud-24.04.x86_64.user-data, .meta-data | the cloud-init templates |
| 6 | ubuntu-cloud-24.04.x86_64.seed.iso | xorriso, volume cidata |
| 7 | efi-code.x86_64.img, efi-vars.x86_64.img | copied from the host's or the snap's EDK2 |
| 8 | ubuntu-cloud-24.04.x86_64.efi-code.qcow2, .efi-vars.qcow2 | qemu-img convert, one variable store per system |
| 9 | ubuntu-cloud-24.04.x86_64.qcow2 (and .qcow2.log) | a 64G overlay on step 4, then the provisioning boot |
| 10 | ubuntu-cloud-24.04.x86_64.run | the 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
| Command | What it does |
|---|---|
image-garden make GOAL | runs make on image-garden.mk for GOAL, such as SYSTEM.run or SYSTEM.qcow2 |
image-garden make list-systems | lists every system |
./SYSTEM.run | boots the system in the foreground; changes are kept |
./SYSTEM.run --query | prints the memory size and the users and passwords |
image-garden allocate [--spread] SYSTEM | boots it in the background with -snapshot and SSH on a local port |
image-garden discard ADDRESS or -a | stops one allocated VM, or all |
image-garden ps | lists allocated VMs |
image-garden rebase SYSTEM.ARCH | points 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, distclean | removes what make built in the project and the cache links; distclean also removes the downloads |
Roads from here
START HERE
- Snap, container or native package — the snap, the container and a source build side by side
- How systems are named — how system names are put together
SYSTEMS · distributions
- The support matrix — every distribution, release and architecture there is
RUNTIME · make rules and the CLI
- From a target name to a VM — each file make builds on the way to the .run script
BUILT ON IT · CI integrations
- Projects built on image-garden — the CI projects built on image-garden
FIRST BOOT · cloud-init changes
- Provisioning runs once — what the one provisioning boot changes and why it runs once
PKGPROXY · caching for guests
- What pkgproxy gives a garden — how pkgproxy makes the second run fast
BUILD TIME · data and rules
- The .ini files in data/ — for contributors, how each system is described