Named instances
many VMs, one image for users for contributors
One define-instance line in .image-garden.mk makes BASE@NAME.ARCH, a new system with its own meta-data, user-data, seed, overlay and .run script on the base system's download. It inherits group, release, architecture, boot type and users, which its --query lists, gets its own host name, takes the instance template names, and is written with -at- in spread.
On the map: runtime
▶ Watch this deck — 7 scenes, ~4 min
Worth seeing first
- Changing what cloud-init does — where .image-garden.mk goes
Part of journeys
- Your own systems with .image-garden.mk, step 3 of 4 · previous: How a user-data template is chosen · next: Several systems from one base image
01 Two machines, one image
A named instance is a new system made from an existing one: the same download, its own cloud-init, disk and .run script.
Some tests need more than one kind of machine: a web server and the client that talks to it, or a stock system next to one you've changed. They can all start from the same distribution image. Downloading it twice would be wasteful, and one image that does every job gets crowded. A named instance is image-garden's answer: a new system made from an existing one, which shares its download but has its own cloud-init, its own disk and its own launcher.
Details and sources
Details
- The README's "Named Instances": "A single base system can be instantiated multiple times with distinct disk images, cloud-init profiles, and hostnames" (README.md:962-993).
- Instances are made of the systems in
data/*.ini, "which are all but Ubuntu Core" (README.md:976-979). mk/020-instances.mkdocumentsdefine-instanceat its top (020-instances.mk:1-28).- The web server and client are an example, as in the README's
webserveranddatabaseinstances.
Read more
- Several systems from one base image: two worked examples.
02 One line makes an instance
$(eval $(call define-instance,ubuntu-cloud-24.04,webserver)) makes ubuntu-cloud-24.04@webserver.ARCH; with a base like ubuntu-cloud-24.04.x86_64 that architecture is used.
You make one with a single line in .image-garden.mk: an eval of a call to define-instance, with the base system and a name, say Ubuntu 24.04 and webserver. Without an architecture, image-garden adds the one you're on. Give the base system with its architecture, and that one is used. Either way you get a new system whose name has the instance after an at sign, just before the architecture. It behaves like any other system: you make it, run it and allocate it by that name.
Details and sources
Details
- The README's two forms, with and without an architecture, and the resulting names (README.md:966-986).
define-instancetakes the base as$(1): when no metadata exists for that exact name, it appendsGARDEN_ARCH; otherwise the last dot-separated part is the architecture. The instance's full name isBASE@NAME.ARCH(020-instances.mk:29-45). The QEMU rules follow the base'sArch=instead, which differs from the name only for the.ppc64elsystems (020-instances.mk:53-56).- The line goes in the project's
.image-garden.mk, whichmk/999-local.mkincludes (999-local.mk:4-5).
Read more
03 What an instance gets of its own
An instance has its own .meta-data, .user-data, .seed.iso, firmware copies, .qcow2 and .run; its overlay sits on the base system's download.
The instance gets everything a system needs, under its own name: meta-data and user-data, a seed, copies of the firmware when the base boots with UEFI, a disk and a run script. Its disk is an overlay on the base system's verified download, the very same file, so nothing is downloaded twice. It joins the list of systems, and make's all target builds it when its architecture matches yours. Making it doesn't make the base system's own disk: the two share only the download.
Details and sources
Details
- The macro adds the instance to
GARDEN_SYSTEMS, and toall::whenGARDEN_ARCHmatches the base system'sArch=(020-instances.mk:58-65), and writes its meta-data and user-data rules (020-instances.mk:67-79). - For an EFI base, the
.runscript needs the instance's own.efi-code.qcow2and.efi-vars.qcow2, and its.qcow2isqemu-img create -f qcow2 -b $(GARDEN_DL_DIR)/GROUP/BASE.qcow2, the base system's download link, followed by the provisioning boot with the instance's seed (020-instances.mk:84-103). BIOS and platform bases have matching rules without firmware (020-instances.mk:105-146). cleananddistcleanremove the instance's files, not the download (020-instances.mk:148-155);make distcleanremoves the download too, through the base system's own rule (see where image-garden keeps its files).
04 What it inherits, and its host name
Group, release, architecture and boot type come from the base system's entry in image-garden's list of systems. Users stay the same; the host name becomes ubuntu-24-04-webserver.
What the instance doesn't choose, it inherits. Its group, release, architecture and boot type come from the base system's entry in the generated list of systems, so an instance of a UEFI system boots with UEFI too, and one of a ppc64el system runs the ppc64 emulator. The users stay the same, ubuntu and ubuntu here, and its script lists them when a tool asks. Only the host name changes, to group, release and instance, with dashes for dots: ubuntu-24-04-webserver. That's handy in a test log, where you can tell the machines apart at a glance.
Details and sources
Details
define-instancereads_BASE_group,_group_upper,_release,_bootand_archof the base system (020-instances.mk:47-56), whichrulegen.py --systems-metawrites intodata/000-systems.mkfor every system indata/*.ini(rulegen.py:825-833).- The architecture that picks the QEMU rules is the base's
Arch=, not the suffix of its name: "ppc64 systems are named .ppc64el" (020-instances.mk:53-56). The instance's name keeps the suffix,ubuntu-cloud-24.04@webserver.ppc64el, and it joinsallwhenGARDEN_ARCHis that architecture (020-instances.mk:61-65). Run: the launcher made forubuntu-cloud-24.04@webserver.ppc64elrunsqemu-system-ppc64. - The launcher's
--querylists the base system's users,root/rootand the group's user: the instance rules pass the user moderoot distro, as rulegen.py does (020-instances.mk:89, 010-qemu.mk:80-88). Run:ubuntu-cloud-24.04@webserver.x86_64.run --queryprintedrootandubuntuwith their passwords. - The host name is
CLOUD_INIT_HOSTNAME: group, release and instance joined by dashes, with dots and pluses turned into dashes (010-qemu.mk:94-97):ubuntu-24-04-webserver, as the README says (README.md:988-993). The user-data'shostname(010-qemu.mk:196) and the meta-data'slocal-hostnameandinstance-iduse it alike (010-qemu.mk:99-104, 020-instances.mk:68). - Ubuntu Core's systems are not in
data/*.ini, so they have no such metadata and have no instances. The README: "define-instancewith an Ubuntu Core system lists the instance inlist-systems, but make has no rule for it" (README.md:976-979, 020-instances.mk:9-10).
05 Changing just the instance
UBUNTU_24.04@webserver_… changes this instance only; UBUNTU@webserver_… every webserver instance of Ubuntu. The base system keeps its own template.
Most of the time you make an instance to change it, and that's what the first two template names are for. A template for the release and the instance applies to just this one: Ubuntu 24.04, webserver. A template for the group and the instance applies to every webserver instance of any Ubuntu release. Start it from the common template, add what this role needs, and the base system and its other instances are left alone.
Details and sources
Details
- An instance's user-data rule passes the instance name to the picker (020-instances.mk:75), so
GROUP_RELEASE@INSTANCE_…andGROUP@INSTANCE_…are tried first (010-qemu.mk:293-298). - The README's per-instance example installs
nginxandlibssl-devforubuntu-cloud-24.04@webserver, and itsCENTOS@old-server_…example applies to every@old-serverinstance of any CentOS release (README.md:1022-1044). - The base system's user-data never asks for an instance's template, so it keeps its own.
06 Instances in spread
In spread.yaml, ubuntu-cloud-24.04-at-webserver; the allocate hook maps -at- back to @. Credentials are the base system's.
To test on an instance with spread, remember that spread names can't contain an at sign. Write it as -at- in spread.yaml, and the allocate hook turns it back into the at sign before it calls image-garden. The user and password are the base system's, so list ubuntu and ubuntu. And because the instance shares the download, every extra instance costs one more provisioning boot, not another image to fetch.
Details and sources
Details
- The garden backend's allocate hook turns
-plus-into+and the first-at-into@, then runsimage-garden allocate --spread "$SYSTEM"."$ARCH"(spread.yaml:45-47). The README explains the escaping (README.md:720-733). - The instance's launcher lists the base system's users with
--query, as every.runscript does (020-instances.mk:89); spread itself takes the user and password from spread.yaml, which the garden backend's systems list for each system (spread.yaml:60-66). - That spread system names cannot hold
@is the README's advice ("escape them for compatibility"); spread's own rules were not read for this map.
Read more
07 Where to go from here
Next: picking a template, several systems from one base image, and spread names.
An instance is one line in your project file: a new system with its own cloud-init and disk on the same download, and two template names to change it. The template deck explains all five names. The profiles deck builds two complete examples, a system that boots differently and one with heavy software installed once. And the spread names deck shows the -at- mapping in full.
Details and sources
Read more
Basis of the statements on this page
Read in mk/020-instances.mk, mk/010-qemu.mk and the README of image-garden at the commit in garden.commit ("code"); the example names are illustrative. The launchers of ubuntu-cloud-24.04@webserver.x86_64 and ubuntu-cloud-24.04@webserver.ppc64el were generated and asked --query ("run").
An instance, part by part
$(eval $(call define-instance,ubuntu-cloud-24.04,webserver)) on x86_64 | |
|---|---|
| System name | ubuntu-cloud-24.04@webserver.x86_64 |
| In spread.yaml | ubuntu-cloud-24.04-at-webserver |
| Downloaded image | the base system's: ~/.cache/image-garden/dl/ubuntu/ubuntu-cloud-24.04.x86_64.qcow2 (a link) |
| Its own files | .meta-data, .user-data, .seed.iso, .efi-code.qcow2, .efi-vars.qcow2, .qcow2, .qcow2.log, .run |
| Group, release, architecture, boot | ubuntu, 24.04, x86_64, efi, from the base system's metadata |
| Users | ubuntu/ubuntu and root/root, as the base system; --query lists them |
| Host name (user-data and meta-data) | ubuntu-24-04-webserver |
| Templates tried | UBUNTU_24.04@webserver_…, UBUNTU@webserver_…, UBUNTU_24.04_…, UBUNTU_…, then the common one |
Things to know
define-instancereads the base system's metadata fromdata/000-systems.mk, which covers the systems ofdata/*.ini: every system but Ubuntu Core's, which have no instances (README.md:976-979).- The QEMU architecture is the base's
Arch=: an instance ofubuntu-cloud-24.04.ppc64elis named…@NAME.ppc64eland runsqemu-system-ppc64(020-instances.mk:53-56). - Without an architecture in the base name, the instance is for
GARDEN_ARCH, the host's by default. make cleanremoves the instance's files; the download stays.make distcleanremoves the download as well.- Editing
.image-garden.mkrebuilds every system's image, instances included: see changing what cloud-init does.
Roads from here
RUNTIME · make rules and the CLI
- image-garden allocate — allocating an instance like any other system
SPREAD · tests
- spread names and garden names — -at- and -plus- in spread
FIRST BOOT · cloud-init changes
- How a user-data template is chosen — the template names an instance selects
- Several systems from one base image — several systems from one base image, built once
- Changing what cloud-init does — hooks and what an edit rebuilds