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

Part of journeys

01 Two machines, one image

NAMED INSTANCES web server client one Ubuntu 24.04 download downloaded twice: wasteful one image for every job: crowded a named instance: its own cloud-init, disk and launcher, the same download
A web server and a client both start from one Ubuntu 24.04 download; downloading twice is wasteful; a named instance gives each role its own cloud-init, disk and launcher on the same download

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.mk documents define-instance at its top (020-instances.mk:1-28).
  • The web server and client are an example, as in the README's webserver and database instances.

Read more

02 One line makes an instance

DEFINE-INSTANCE $(eval $(call define-instance,ubuntu-cloud-24.04,webserver)) no architecture: the one you're on (GARDEN_ARCH) $(eval $(call define-instance,ubuntu-cloud-24.04.x86_64,database)) ubuntu-cloud-24.04@webserver.x86_64 ubuntu-cloud-24.04@database.x86_64 the instance after @, just before the architecture $ image-garden make ubuntu-cloud-24.04@webserver.x86_64.run
Two define-instance lines in .image-garden.mk: one without an architecture, which uses GARDEN_ARCH, and one with x86_64; they make ubuntu-cloud-24.04@webserver.x86_64 and ubuntu-cloud-24.04@database.x86_64, used like any other system

$(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-instance takes the base as $(1): when no metadata exists for that exact name, it appends GARDEN_ARCH; otherwise the last dot-separated part is the architecture. The instance's full name is BASE@NAME.ARCH (020-instances.mk:29-45). The QEMU rules follow the base's Arch= instead, which differs from the name only for the .ppc64el systems (020-instances.mk:53-56).
  • The line goes in the project's .image-garden.mk, which mk/999-local.mk includes (999-local.mk:4-5).

03 What an instance gets of its own

ITS OWN FILES ubuntu-cloud-24.04@webserver.x86_64 .meta-data .user-data .seed.iso .efi-code.qcow2 .efi-vars.qcow2 .qcow2 .run the base system's download the very same file, downloaded once in GARDEN_SYSTEMS; make all builds it on its architecture the base system's own disk is not made: only the download is shared
The files of ubuntu-cloud-24.04@webserver.x86_64: meta-data, user-data, seed ISO, UEFI code and variables, qcow2 and run; its qcow2 is an overlay on the base system's verified download; it joins GARDEN_SYSTEMS and make all; the base system's own disk is not made

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 to all:: when GARDEN_ARCH matches the base system's Arch= (020-instances.mk:58-65), and writes its meta-data and user-data rules (020-instances.mk:67-79).
  • For an EFI base, the .run script needs the instance's own .efi-code.qcow2 and .efi-vars.qcow2, and its .qcow2 is qemu-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).
  • clean and distclean remove the instance's files, not the download (020-instances.mk:148-155); make distclean removes 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

INHERITED the base system, in image-garden's list of systems _ubuntu-cloud-24.04.x86_64_group := ubuntu _…_release := 24.04 _…_arch := x86_64 _…_boot := efi the instance: ubuntu, 24.04, x86_64, efi a .ppc64el base: arch ppc64, qemu-system-ppc64 users: ubuntu / ubuntu, root / root listed by its .run --query hostname: ubuntu-24-04-webserver machines told apart in a test log
The base system's metadata, from image-garden's list of systems, gives the instance its group ubuntu, release 24.04, architecture x86_64 and boot type efi; an instance of a ppc64el system gets the ppc64 architecture and runs qemu-system-ppc64. The users stay ubuntu and root, and --query lists them; the host name becomes ubuntu-24-04-webserver, easy to tell apart in a test log

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-instance reads _BASE_group, _group_upper, _release, _boot and _arch of the base system (020-instances.mk:47-56), which rulegen.py --systems-meta writes into data/000-systems.mk for every system in data/*.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 joins all when GARDEN_ARCH is that architecture (020-instances.mk:61-65). Run: the launcher made for ubuntu-cloud-24.04@webserver.ppc64el runs qemu-system-ppc64.
  • The launcher's --query lists the base system's users, root/root and the group's user: the instance rules pass the user mode root distro, as rulegen.py does (020-instances.mk:89, 010-qemu.mk:80-88). Run: ubuntu-cloud-24.04@webserver.x86_64.run --query printed root and ubuntu with 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's hostname (010-qemu.mk:196) and the meta-data's local-hostname and instance-id use 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-instance with an Ubuntu Core system lists the instance in list-systems, but make has no rule for it" (README.md:976-979, 020-instances.mk:9-10).

05 Changing just the instance

ITS OWN TEMPLATE UBUNTU_24.04@webserver_CLOUD_INIT_USER_DATA_TEMPLATE just this one UBUNTU@webserver_CLOUD_INIT_USER_DATA_TEMPLATE every webserver of Ubuntu define UBUNTU_24.04@webserver_CLOUD_INIT_USER_DATA_TEMPLATE $(CLOUD_INIT_USER_DATA_TEMPLATE) packages: - nginx base: unchanged and the other instances too
UBUNTU_24.04@webserver_CLOUD_INIT_USER_DATA_TEMPLATE applies to this instance only; UBUNTU@webserver_CLOUD_INIT_USER_DATA_TEMPLATE to every webserver instance of Ubuntu; a template starting from the common one adds nginx; the base system and other instances are unchanged

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_… and GROUP@INSTANCE_… are tried first (010-qemu.mk:293-298).
  • The README's per-instance example installs nginx and libssl-dev for ubuntu-cloud-24.04@webserver, and its CENTOS@old-server_… example applies to every @old-server instance 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 systems: - ubuntu-cloud-24.04-at-webserver: SYSTEM="${SYSTEM/-at-/@}" ubuntu-cloud-24.04@webserver.x86_64 username: ubuntu password: ubuntu the base system's user and password every extra instance: one more provisioning boot, no new download
spread.yaml lists ubuntu-cloud-24.04-at-webserver with user ubuntu and password ubuntu; the allocate hook replaces -at- with @ and calls image-garden allocate for ubuntu-cloud-24.04@webserver.x86_64; each extra instance costs one provisioning boot, no new download

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 runs image-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 .run script 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.

07 Where to go from here

ROADS Named instances Picking a template all five names One base, many VMs two complete examples Names in spread -plus- and -at- Your own changes .image-garden.mk
Roads from this deck: picking a template, several systems from one base image, spread names, and changing what cloud-init does

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 nameubuntu-cloud-24.04@webserver.x86_64
In spread.yamlubuntu-cloud-24.04-at-webserver
Downloaded imagethe 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, bootubuntu, 24.04, x86_64, efi, from the base system's metadata
Usersubuntu/ubuntu and root/root, as the base system; --query lists them
Host name (user-data and meta-data)ubuntu-24-04-webserver
Templates triedUBUNTU_24.04@webserver_…, UBUNTU@webserver_…, UBUNTU_24.04_…, UBUNTU_…, then the common one

Things to know

  • define-instance reads the base system's metadata from data/000-systems.mk, which covers the systems of data/*.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 of ubuntu-cloud-24.04.ppc64el is named …@NAME.ppc64el and runs qemu-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 clean removes the instance's files; the download stays. make distclean removes the download as well.
  • Editing .image-garden.mk rebuilds every system's image, instances included: see changing what cloud-init does.

Roads from here

RUNTIME · make rules and the CLI

SPREAD · tests

FIRST BOOT · cloud-init changes