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
- The adhoc backend: allocate and discard — the allocate hook these names pass through
Part of journeys
- Testing with spread, step 4 of 4 · previous: The adhoc backend: allocate and discard
01 Two ways to name one machine
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 exampleubuntu-cloud-24.04@webserver.x86_64(mk/020-instances.mk:1-19), from a system defined indata/*.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).
Read more
02 Writing plus and at in spread.yaml
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-/+}"thenSYSTEM="${SYSTEM/-at-/@}"(spread.yaml:45-46, README.md:727-728).- The demo lists
ubuntu-cloud-24.04-at-mcandubuntu-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-meon the slide is an example instance name, not one from image-garden.
Read more
03 The architecture comes last
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 -mprintsx86_64, on a 64-bit Arm hostaarch64.
Read more
04 What the name selects
+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
+tpmsystems:UBUNTU_CORE_TPM_RELEASES = 24+tpm 24+dangerous+tpm 26+tpm 26+dangerous+tpm, x86_64 only;+tpm+dangerousis refused with a message to use alphabetical order (mk/050-ubuntu-core.mk:15-21).- The demo's
mcinstance and its template (spread-demo/.image-garden.mk:16-23), and the task that needs it (spread-demo/tests/smoke/mc-package/task.yaml:3-7). - Template lookup:
GROUP_REL@INST,GROUP@INST,GROUP_REL,GROUP, then the default (mk/010-qemu.mk:293-298).
Read more
05 Good habits
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.
Read more
06 Where to go from here
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
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.yaml | Allocated as (x86_64 host) | Templates tried, first defined wins |
|---|---|---|
ubuntu-cloud-24.04 | ubuntu-cloud-24.04.x86_64 | UBUNTU_24.04_…, UBUNTU_…, CLOUD_INIT_USER_DATA_TEMPLATE |
ubuntu-cloud-24.04-at-mc | ubuntu-cloud-24.04@mc.x86_64 | UBUNTU_24.04@mc_…, UBUNTU@mc_…, UBUNTU_24.04_…, UBUNTU_…, CLOUD_INIT_USER_DATA_TEMPLATE |
debian-cloud-13-at-webserver | debian-cloud-13@webserver.x86_64 | DEBIAN_13@webserver_…, DEBIAN@webserver_…, DEBIAN_13_…, DEBIAN_…, CLOUD_INIT_USER_DATA_TEMPLATE |
fedora-cloud-43-at-db | fedora-cloud-43@db.x86_64 | FEDORA_43@db_…, FEDORA@db_…, FEDORA_43_…, FEDORA_…, CLOUD_INIT_USER_DATA_TEMPLATE |
ubuntu-core-24-plus-tpm | ubuntu-core-24+tpm.x86_64 | the Ubuntu Core template; the +tpm rules add Secure Boot and swtpm |
ubuntu-core-24-plus-dangerous-plus-tpm | ubuntu-core-24+dangerous+tpm.x86_64 | as 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
| Line | Replaces | Why |
|---|---|---|
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
usernameandpasswordfor every system;ubuntuon 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
- How systems are named — how image-garden names are put together
UBUNTU CORE · all snaps
- Ubuntu Core with Secure Boot and a TPM — what the +tpm modifier selects
RUNTIME · make rules and the CLI
- Named instances — define-instance in full
FIRST BOOT · cloud-init changes
- Several systems from one base image — what an instance's template can install
- How a user-data template is chosen — the order in which templates are picked