spread names and garden names

-plus-, -at-, no arch for CI operators

spread system names carry no architecture and cannot hold + or @. Write -plus- and -at- in spread.yaml, let the allocate hook turn them back and append the architecture from uname -m; the modifiers and the instance then select image-garden's rules and cloud-init templates.

On the map: spread

▶ Watch this deck — 6 scenes, ~4 min

Worth seeing first

Part of journeys

01 Two ways to name one machine

TWO WAYS TO NAME image-garden ubuntu-core-24+tpm.x86_64 ubuntu-cloud-24.04@mc.aarch64 the allocate hook .x86_64 .aarch64: the architecture, last +tpm: a modifier @mc: an instance spread ubuntu-core-24-plus-tpm ubuntu-cloud-24.04-at-mc no architecture no + and no @ allocate turns spread's name back into image-garden's
On the left, image-garden names ubuntu-core-24+tpm.x86_64 and ubuntu-cloud-24.04@mc.aarch64, ending with the architecture, with a + modifier and an @ instance; on the right, spread names ubuntu-core-24-plus-tpm and ubuntu-cloud-24.04-at-mc, with no architecture and no + or @; the allocate hook in the middle turns spread's names into image-garden's

image-garden: ubuntu-core-24+tpm.x86_64, ubuntu-cloud-24.04@mc.aarch64. spread: no architecture, no +, no @.

image-garden and spread name the same machine differently, and the allocate hook is where the two meet. An image-garden name ends with the architecture, and it can carry two special characters: a plus before a modifier, such as tpm on Ubuntu Core, and an at sign before an instance, such as mc on Ubuntu 24.04. spread's names are simpler. They have no architecture, and they can't contain a plus or an at sign. This deck shows how to write image-garden's names in spread.yaml, how allocate turns them back, and what the special characters select.

Details and sources

Details

  • define-instance makes BASE@NAME.ARCH, for example ubuntu-cloud-24.04@webserver.x86_64 (mk/020-instances.mk:1-19), from a system defined in data/*.ini: Ubuntu Core systems have modifiers but no instances (README.md:976-979).
  • The README asks to escape + as -plus- and @ as -at- in spread configuration "for compatibility" (README.md:720-732).

02 Writing plus and at in spread.yaml

-PLUS- AND -AT- in spread.yaml in image-garden + is written -plus-, @ is written -at- ubuntu-core-24-plus-dangerous-plus-tpm ubuntu-cloud-24.04-at-mc SYSTEM="${SPREAD_SYSTEM//-plus-/+}" SYSTEM="${SYSTEM/-at-/@}" ubuntu-core-24+dangerous+tpm // replaces every -plus- ubuntu-cloud-24.04@mc / replaces only the first -at- one @ per name, and no system name contains -at-, but an instance name may: ubuntu-cloud-24.04-at-look-at-me → ubuntu-cloud-24.04@look-at-me
In spread.yaml, ubuntu-core-24-plus-dangerous-plus-tpm and ubuntu-cloud-24.04-at-mc; two bash substitutions in allocate replace every -plus- with + and only the first -at- with @, giving ubuntu-core-24+dangerous+tpm and ubuntu-cloud-24.04@mc. A name has one @, and no system name contains -at-, but an instance name may, as in ubuntu-cloud-24.04@look-at-me.

SYSTEM="${SPREAD_SYSTEM//-plus-/+}" replaces every -plus-; SYSTEM="${SYSTEM/-at-/@}" replaces only the first -at-, since an instance name may contain one.

In spread.yaml, you write a plus as -plus-, and an at sign as -at-. So Ubuntu Core 24 with dangerous and tpm becomes ubuntu-core-24-plus-dangerous-plus-tpm, and the mc instance of Ubuntu 24.04 becomes ubuntu-cloud-24.04-at-mc. The allocate hook turns them back with two bash substitutions. The first replaces every -plus- with a plus, because a name can have several modifiers. The second replaces only the first -at-, and on purpose: a name has one at sign, no system name contains -at-, but the instance name after it may.

Details and sources

Details

  • SYSTEM="${SPREAD_SYSTEM//-plus-/+}" then SYSTEM="${SYSTEM/-at-/@}" (spread.yaml:45-46, README.md:727-728).
  • The demo lists ubuntu-cloud-24.04-at-mc and ubuntu-core-24-plus-dangerous-plus-tpm (spread-demo/spread.yaml:116, spread-demo/spread.yaml:156).
  • //-plus-/ replaces every occurrence, /-at-/ only the first. The README explains why: "Every -plus- is replaced, but only the first -at-: a name has one @, system names have no -at-, and the instance name after it may" (README.md:731-732).
  • look-at-me on the slide is an example instance name, not one from image-garden.

03 The architecture comes last

THE ARCHITECTURE COMES LAST ARCH="${ARCH:-$(uname -m)}" exec image-garden allocate --spread "$SYSTEM"."$ARCH" one spread.yaml, one system: ubuntu-cloud-24.04 an x86 laptop ubuntu-cloud-24.04.x86_64 · KVM an Arm CI runner ubuntu-cloud-24.04.aarch64 · KVM architecture in spread.yaml: a list for every kind of host on the wrong host: emulated, many times slower
The hook sets ARCH from uname -m unless ARCH is set and allocates SYSTEM.ARCH; one spread.yaml naming ubuntu-cloud-24.04 gives ubuntu-cloud-24.04.x86_64 with KVM on an x86 laptop and ubuntu-cloud-24.04.aarch64 with KVM on an Arm runner; putting the architecture in spread.yaml needs a list per host, and on the wrong host every machine is emulated

ARCH="${ARCH:-$(uname -m)}", then "$SYSTEM"."$ARCH": one spread.yaml serves x86_64 and aarch64 runners, each at full speed.

spread names carry no architecture, and that's a good thing. The hook adds it last: a dot, and the output of uname -m, unless ARCH says otherwise. The same spread.yaml then works on an x86 laptop and on an Arm CI runner, and each of them boots machines of its own architecture, with KVM. Put the architecture in the system list instead, and you'd need a list for every kind of host. On the wrong host, every machine would be emulated, many times slower.

Details and sources

Details

  • ARCH="${ARCH:-$(uname -m)}", then "$SYSTEM"."$ARCH" (spread.yaml:43-47).
  • Without /dev/kvm, "QEMU emulates the CPU (TCG), many times slower" (README.md:780-781).
  • On an x86_64 host uname -m prints x86_64, on a 64-bit Arm host aarch64.

04 What the name selects

WHAT THE NAME SELECTS ubuntu-core-24+tpm TPM rules: Secure Boot and swtpm same download as ubuntu-core-24 modifiers in alphabetical order: +dangerous+tpm ubuntu-cloud-24.04@mc UBUNTU_24.04@mc_CLOUD_INIT_USER_DATA_TEMPLATE packages: - mc systems: - ubuntu-cloud-24.04-at-mc execute: | mc --version mc is in the image before spread logs in
ubuntu-core-24+tpm selects the TPM rules, Secure Boot and swtpm, from the same download as ubuntu-core-24, with modifiers in alphabetical order; ubuntu-cloud-24.04@mc selects the UBUNTU_24.04@mc cloud-init template that installs mc; a task lists ubuntu-cloud-24.04-at-mc and runs mc --version; mc is in the image before spread logs in

+tpm selects the TPM rules. @mc selects UBUNTU_24.04@mc_CLOUD_INIT_USER_DATA_TEMPLATE, which installs mc while the image is made.

The special characters aren't decoration: they choose what image-garden builds. A modifier picks other rules. Ubuntu Core 24 +tpm boots with Secure Boot and a TPM, from the same download as plain Ubuntu Core 24, and modifiers go in alphabetical order, dangerous before tpm. An instance picks a cloud-init template. image-garden's demo defines an mc instance of Ubuntu 24.04, whose template installs Midnight Commander. A task that needs it lists that instance as its only system, and the package is in the image before spread ever logs in.

Details and sources

Details

05 Good habits

GOOD HABITS No architecture in spread.yaml: the hook adds it A username and password for every system Instances for machines with a role, software installed once Short, lowercase instance names: they end up in file and template names One make target per system, turning + back into -plus- spread … garden:$(subst +,-plus-,$*): spread-demo/Makefile
Five habits: no architecture in spread.yaml, a user and password for every system, instances for machines with a role, short lowercase instance names, and a make target per system that turns + back into -plus-

No architecture in spread.yaml, credentials for every system, instances for roles, short lowercase instance names, one make target per system.

A few habits keep this tidy. Keep the architecture out of spread.yaml and let the hook add it. List the user and password for every system, even when they look obvious. Use instances for machines with a role, such as a server with its software already installed, instead of installing it in every task. Keep instance names short and lowercase, since they end up in file names and template names. And to run one system at a time, image-garden's demo has a make target per system that turns the plus back into -plus- for spread.

Details and sources

Details

  • The demo's Makefile lists systems with spread -list, turns -plus- into + for target names, and back into -plus- for spread (spread-demo/Makefile:4-8).
  • The demo lists credentials for every system (spread-demo/spread.yaml:41-172).
  • Instance names become part of file names (SYSTEM@NAME.ARCH.qcow2) and template names (GROUP_REL@NAME_CLOUD_INIT_USER_DATA_TEMPLATE) (mk/020-instances.mk:1-19); lowercase is a convention of this map, not a rule in the code.

06 Where to go from here

ROADS Names in spread System names every part of a name Profiles what a template can build in Named instances define-instance in full Secure Boot and TPM what +tpm selects Picking a template the lookup order
Five roads from this deck: system names, profiles, named instances, Secure Boot and TPM, and how templates are picked

Next: system names, profiles, instances, Secure Boot and TPM, and how templates are picked.

So: -plus- and -at- in spread.yaml, turned back in the allocate hook, with the architecture added last. From here, the system names deck explains every part of an image-garden name. The profiles deck shows what an instance's template can put in an image, and the instances deck covers define-instance in full. The TPM deck shows what the tpm modifier selects, and the templates deck the order in which templates are picked.

Details and sources

Read more

Basis of the statements on this page

Read in image-garden at the commit this map describes ("code"): the allocate hook in spread.yaml (lines 43-47), mk/020-instances.mk, the template picker in mk/010-qemu.mk (lines 285-298) and the Ubuntu Core rules in mk/050-ubuntu-core.mk. The rows are worked out from them ("derived") on an x86_64 host; nothing was run. webserver and db are example instances that a project would define in its .image-garden.mk.

From spread name to template

In spread.yamlAllocated as (x86_64 host)Templates tried, first defined wins
ubuntu-cloud-24.04ubuntu-cloud-24.04.x86_64UBUNTU_24.04_…, UBUNTU_…, CLOUD_INIT_USER_DATA_TEMPLATE
ubuntu-cloud-24.04-at-mcubuntu-cloud-24.04@mc.x86_64UBUNTU_24.04@mc_…, UBUNTU@mc_…, UBUNTU_24.04_…, UBUNTU_…, CLOUD_INIT_USER_DATA_TEMPLATE
debian-cloud-13-at-webserverdebian-cloud-13@webserver.x86_64DEBIAN_13@webserver_…, DEBIAN@webserver_…, DEBIAN_13_…, DEBIAN_…, CLOUD_INIT_USER_DATA_TEMPLATE
fedora-cloud-43-at-dbfedora-cloud-43@db.x86_64FEDORA_43@db_…, FEDORA@db_…, FEDORA_43_…, FEDORA_…, CLOUD_INIT_USER_DATA_TEMPLATE
ubuntu-core-24-plus-tpmubuntu-core-24+tpm.x86_64the Ubuntu Core template; the +tpm rules add Secure Boot and swtpm
ubuntu-core-24-plus-dangerous-plus-tpmubuntu-core-24+dangerous+tpm.x86_64as above, from the +dangerous image

Every … stands for _CLOUD_INIT_USER_DATA_TEMPLATE. An instance exists only when the project's .image-garden.mk defines it with $(eval $(call define-instance,BASE,NAME)). With no template for it, an instance gets its base system's template.

The two substitutions

LineReplacesWhy
SYSTEM="${SPREAD_SYSTEM//-plus-/+}"every -plus-a name can carry several modifiers, as in +dangerous+tpm
SYSTEM="${SYSTEM/-at-/@}"the first -at-a name has one @ and no system name contains -at-, but an instance name may

Habits

  • No architecture in spread.yaml: the hook adds .$(uname -m), or $ARCH.
  • A username and password for every system; ubuntu on Ubuntu Core.
  • Modifiers in alphabetical order: +dangerous+tpm, never +tpm+dangerous.
  • Instances for machines with a role, with their software in the template; Ubuntu Core has none.
  • Short, lowercase instance names: they become part of file and template names.
  • One make target per system, as in image-garden's spread-demo/Makefile.

Roads from here

START HERE

UBUNTU CORE · all snaps

RUNTIME · make rules and the CLI

FIRST BOOT · cloud-init changes