How systems are named
group-variant-release.arch for everyone
Every system is named group-variant-release.arch, such as ubuntu-cloud-24.04.x86_64, with +modifiers such as +tpm and an optional @instance before the architecture. The name is the make target and the file prefix; its group picks the download directory, user and templates, and its variant word leaves room for more kinds of image of one release.
On the map: start here
01 One word is not enough
A system name says which operating system, which kind of image, which release and which architecture: ubuntu-cloud-24.04.x86_64. It is the make target and the prefix of every file made for that system.
Say a test fails in CI, and all the log says is: Ubuntu. Which one? Ubuntu comes as a cloud image, as Ubuntu Core, as a desktop and as a server install, in many releases, and each runs on several architectures. A test that names only the distribution leaves you guessing, and you can't run it again on the same machine. So image-garden gives every system a name with enough parts to leave nothing to guess. The one this map follows is Ubuntu's cloud image, release 24.04, on x86. Written out, that's ubuntu-cloud-24.04.x86_64. It's what you pass to make, and every file made for the system starts with it.
Details and sources
Details
- The manual page: "Systems are identifiers for a particular operating system, variant, release and CPU architecture" (image-garden.1:211-214).
- The running example is the section
[ubuntu-cloud-24.04.x86_64]of data/ubuntu.ini, withArch=x86_64,Boot=efiandRelease=24.04(ubuntu.ini:237-242). - image-garden itself has two kinds of Ubuntu image: the cloud images of data/ubuntu.ini and the Ubuntu Core images of mk/050-ubuntu-core.mk:4-16. Desktop and server systems are not in this release; the maintainer's plan for them is the subject of the scene "Four planned Ubuntu siblings" in this deck.
- The generated rules name every file after the system:
NAME.meta-data,NAME.user-data,NAME.qcow2,NAME.run, and the cleanup removes them by the same name (rulegen.py:452-478). - The architectures on the slide are the ones Ubuntu's cloud images come in (ppc64 systems are named
.ppc64el); the full list is in the support matrix.
Read more
02 The parts of a name
GROUP-VARIANT-RELEASE+MODIFIER@INSTANCE.ARCH. The release, the modifiers and the instance are optional; the group, the variant and the architecture are always there.
Read it from left to right. First the group, ubuntu, a family of systems. Then the variant, cloud: what kind of image it is. Then the release, 24.04, and last, after a dot, the architecture. Fedora 42 on RISC-V follows the same pattern. Arch Linux is rolling and has no release, so its name is just archlinux-cloud and the architecture. Two optional parts can come before the dot. A modifier starts with a plus, as in +dangerous and +tpm on Ubuntu Core, always in alphabetical order. An instance starts with an at sign, as in at webserver: your own copy of a base system, set up your way.
Details and sources
Details
- In data/*.ini the system name is the section name, written in full by hand:
$GROUP-$VARIANT-$RELEASE.$ARCHis the comment on the field that holds it (rulegen.py:114-117). rulegen.py does not build the name from the parts; it checks only that the section name contains theArchvalue, and stops with "Suspicious image … for architecture …" otherwise (rulegen.py:395-405). - That is why Ubuntu's ppc64 systems may be named
ubuntu-cloud-24.04.ppc64elwithArch=ppc64:ppc64elcontainsppc64(ubuntu.ini:24-27). - The group and the variant are the
[META]keysGroupandVariantof each INI file, hereGroup=ubuntu,Variant=cloud(ubuntu.ini:4-6). [fedora-cloud-42.riscv64](fedora.ini:80-85);[archlinux-cloud.x86_64]has noReleasekey (archlinux.ini:8-12). Gentoo is the other system without a release.- Modifiers exist only on Ubuntu Core:
+dangerousand+tpm. Make stops on+tpm+dangerouswith "system modifiers go in alphabetical order: use … +dangerous+tpm …", and on+tpmfor an architecture other than x86_64 (050-ubuntu-core.mk:15-21). define-instancemakesBASE@NAME.ARCHfrom a base system and an instance name, for exampleubuntu-cloud-24.04@webserver.x86_64(020-instances.mk:1-19).- Note on words: the README calls the
+dangerousand+tpmsystems "variants" of Ubuntu Core (README.md:701-707). In the name they are modifiers; the variant is the word after the group (core).
Read more
- spread names: the same names without
+,@and the architecture. - Named instances, Ubuntu Core, the INI files.
03 What each part chooses
The group picks the cache directory, the user and the template prefix; the release a per-release template; a modifier extra rules; an instance its own template and disk; the architecture the QEMU. The variant names the kind of image.
Each part chooses something. The group picks the directory the download is cached in, and the everyday user, so on Ubuntu you log in as ubuntu. With the release, the group also names the cloud-init template image-garden looks for, say, one just for Ubuntu 24.04. A modifier picks extra rules: +dangerous downloads from another channel, and +tpm adds Secure Boot firmware and swtpm. An instance gets its own template, disk and seed. The architecture picks the QEMU that runs it. And the variant? Today no rule reads it. It's the word that tells you, and whoever reads your test next, what kind of image you asked for.
Details and sources
Details
- Group. The rules rulegen.py writes for a system use the
Groupkey for the download directory$(GARDEN_DL_DIR)/GROUP(rulegen.py:448-451, rulegen.py:480-483), the second user of the user-data and its upper-case template prefix (rulegen.py:467-467), and the user that--queryreports (rulegen.py:593-597, 010-qemu.mk:57-92). The template makes that user with the group's name as its password (010-qemu.mk:205-211). - Release. The picker tries
GROUP_RELEASE@INSTANCE,GROUP@INSTANCE,GROUP_RELEASE,GROUP, then the defaultCLOUD_INIT_USER_DATA_TEMPLATE(010-qemu.mk:293-298). image-garden itself defines noUBUNTU_24.04_…template; you may, in.image-garden.mk. The release also goes into the guest's host name,ubuntu-24-04, the same in user-data,/etc/hostsand the meta-data'slocal-hostname(010-qemu.mk:94-104, 010-qemu.mk:196). - Modifiers.
+dangerousdownloads from thedangerous-stablechannel instead ofstable(050-ubuntu-core.mk:235-239);+tpmsets the machine toq35,smm=on, uses Secure Boot firmware and starts swtpm (050-ubuntu-core.mk:55-68). In the host name a modifier's+becomes-, as a host name label allows no+:ubuntu-core-24+tpmnames itselfubuntu-core-24-tpm(010-qemu.mk:94-97, 050-ubuntu-core.mk:141). - Instance.
define-instancegivesBASE@NAME.ARCHits own disk image, seed ISO and run script, and inherits the base's boot type, architecture, group and release (020-instances.mk:16-19). Its host name adds the instance,ubuntu-24-04-webserver, in user-data and meta-data alike (020-instances.mk:67-68). - Architecture. rulegen.py picks the run and provisioning rules by
ArchandBoot(rulegen.py:804-821); each architecture's QEMU command is in its ownmk/010-qemu-ARCH.mk. - Variant. No rule reads it. It is in the name because the section names in data/*.ini are written with it, and the Ubuntu Core rules write
coreinto theirs.
Read more
for contributors
In the code
- rulegen.py reads
Variantfrom[META](rulegen.py:336-348) intoGroup.variant. Its only use is theGroup.fullproperty (rulegen.py:32-48), and nothing callsfull.str(group)is the group's name alone, and that is what the rule templates and--systems-metause (rulegen.py:824-833).
04 What exists today for contributors in place of the general version
Thirteen INI files, each with Variant=cloud, and the hand-written Ubuntu Core rules, whose names say core. The variant is always in the name, even where there is only one kind.
So what's there today? Thirteen INI files, one per family: AlmaLinux, Alpine, Amazon Linux, Arch, CentOS, Debian, Fedora, Gentoo, OpenCloudOS, openSUSE, Oracle, Rocky and Ubuntu. Every one of them says Variant=cloud, because each one boots its distribution's cloud image. Then there's Ubuntu Core, which isn't in an INI file at all. Its rules are written by hand, and its names say core where the others say cloud. Notice that the variant is always in the name, even for a family that has only one kind of image. Fedora 42 could have been called fedora-42. It's fedora-cloud-42, so the name already has room for a second kind.
Details and sources
Details
- The thirteen INI files are almalinux, alpine, amazonlinux, archlinux, centos, debian, fedora, gentoo, opencloudos, opensuse, oracle, rocky and ubuntu; each
[META]hasGroup=the file's name andVariant=cloud, for example fedora.ini:4-6, ubuntu.ini:4-6 and opencloudos.ini:9-11. - Every section name in them starts with
GROUP-cloud: 139 systems in all (counted from the section headers at the tag). - Ubuntu Core's names are made in 050-ubuntu-core.mk:4-16:
ubuntu-core-R.x86_64for releases 16 to 26 with their+dangerousforms,ubuntu-core-R.aarch64from 22 on, and the four+tpmsystems on x86_64. Its releases are written24,26, not24.04. - The manual page lists the families as
almalinux-cloud-{8,9,10},ubuntu-cloud-{14,16,18,20,22,24,26}.04,ubuntu-core-{16,18,…}and so on (image-garden.1:211-214 and the list after it).
Read more
05 What exists today general version
Thirteen families, each with the variant cloud, and Ubuntu Core, whose names say core. The variant is always in the name, even where there is only one kind.
So what's there today? Thirteen families: AlmaLinux, Alpine, Amazon Linux, Arch, CentOS, Debian, Fedora, Gentoo, OpenCloudOS, openSUSE, Oracle, Rocky and Ubuntu. Every one of them has cloud as its variant, because each one boots its distribution's cloud image. Then there's Ubuntu Core, built from Ubuntu's all-snaps images, and its names say core where the others say cloud. Notice that the variant is always in the name, even for a family that has only one kind of image. Fedora 42 could have been called fedora-42. It's fedora-cloud-42, so the name already has room for a second kind.
Details and sources
Details
- The thirteen families are almalinux, alpine, amazonlinux, archlinux, centos, debian, fedora, gentoo, opencloudos, opensuse, oracle, rocky and ubuntu, each with the variant
cloud: 139 systems in all. - Ubuntu Core's names:
ubuntu-core-R.x86_64for releases 16 to 26 with their+dangerousforms,ubuntu-core-R.aarch64from 22 on, and the four+tpmsystems on x86_64. Its releases are written24,26, not24.04. - The manual page lists the families as
almalinux-cloud-{8,9,10},ubuntu-cloud-{14,16,18,20,22,24,26}.04,ubuntu-core-{16,18,…}and so on (image-garden.1:211-214 and the list after it).
for contributors
In the data
- The thirteen INI files are almalinux, alpine, amazonlinux, archlinux, centos, debian, fedora, gentoo, opencloudos, opensuse, oracle, rocky and ubuntu; each
[META]hasGroup=the file's name andVariant=cloud, for example fedora.ini:4-6, ubuntu.ini:4-6 and opencloudos.ini:9-11. - Every section name in them starts with
GROUP-cloud: 139 systems in all (counted from the section headers at the tag). - Ubuntu Core's names are made in 050-ubuntu-core.mk:4-16:
ubuntu-core-R.x86_64for releases 16 to 26 with their+dangerousforms,ubuntu-core-R.aarch64from 22 on, and the four+tpmsystems on x86_64. Its releases are written24,26, not24.04.
Read more
06 Four planned Ubuntu siblings
Planned by the maintainer: ubuntu-core-, ubuntu-desktop-, ubuntu-server- and ubuntu-cloud- followed by a release and an architecture. Only the core and cloud names exist today.
Here's where that room pays off. Ubuntu isn't one image either: besides the cloud image image-garden boots today, and Ubuntu Core, there are desktop and server installs. The maintainer plans to name them side by side: ubuntu-core, ubuntu-desktop, ubuntu-server and ubuntu-cloud, each followed by its release and architecture. Four siblings, told apart by the variant alone. Adding a kind of image doesn't rename the ones you already use, so ubuntu-cloud-24.04 stays exactly what it is, and so do the Ubuntu Core names. Keep in mind that the desktop and server names are a plan. You can't build them yet.
Details and sources
Details
- Planned by the maintainer; not in v0.8.0. The maintainer plans to name Ubuntu systems
ubuntu-core-RELEASE,ubuntu-desktop-RELEASE,ubuntu-server-RELEASEandubuntu-cloud-RELEASE, side by side, each with an architecture after the dot. This comes from the maintainer, not from the source at the tag: there are no desktop or server systems, image sources or rules in v0.8.0, and no date has been given. - What exists at the tag: the
ubuntu-cloud-…systems of data/ubuntu.ini,Group=ubuntu,Variant=cloud(ubuntu.ini:4-6), and theubuntu-core-…systems of 050-ubuntu-core.mk:4-16. - Ubuntu Core's releases are written
24,26at the tag, Ubuntu's cloud releases24.04,26.04. The plan names the pattern, not how each variant writes its release, so the slide shows…where the release goes. - That the existing names keep working is derived: the plan adds names next to them and does not change the
cloudorcoreones.
Read more
07 Room for other editions for contributors in place of the general version
A distribution with several kinds of image could be named NAME-cloud-R, NAME-server-R and NAME-workstation-R, one INI file each. This is what the scheme allows, not a plan for any distribution.
The shape fits any operating system that ships more than one kind of image. Picture a distribution with a cloud image, a server install and a workstation edition. Under this scheme they'd be its name, then cloud, server or workstation, then the release and the architecture. Each kind would get an INI file of its own, with its own Variant line, and its rules would come from that file. Nothing like that exists yet, and none of it is promised. It's simply what the shape of the name allows: one more word in a slot that's already there, instead of a second naming scheme your tests would have to learn.
Details and sources
Details
- What the scheme allows; not a plan. No distribution other than Ubuntu has a second variant at the tag, and the maintainer's stated plan covers only Ubuntu's names (see the scene before). The distribution on the slide is an example, not a real one.
- Each INI file is turned into its own rule file,
data/050-NAME.gen.mk, by one run of rulegen.py (Makefile:48-58), and rulegen.py takesGroupandVariantfrom that file's[META]section (rulegen.py:336-348). So a second kind of image is a second INI file; the slide leavesGroupopen because the group decides more than the name (next scene, for contributors). - Today every family has one file with
Variant=cloud, for example fedora.ini:4-6.
Read more
08 Room for other editions general version
A distribution with several kinds of image could be named NAME-cloud-R, NAME-server-R and NAME-workstation-R, each built the way cloud images are today. This is what the scheme allows, not a plan for any distribution.
The shape fits any operating system that ships more than one kind of image. Picture a distribution with a cloud image, a server install and a workstation edition. Under this scheme they'd be its name, then cloud, server or workstation, then the release and the architecture. Each kind would be a set of systems of its own, built just the way the cloud images are today. Nothing like that exists yet, and none of it is promised. It's simply what the shape of the name allows: one more word in a slot that's already there, instead of a second naming scheme your tests would have to learn.
Details and sources
Details
- What the scheme allows; not a plan. No distribution other than Ubuntu has a second variant at the tag, and the maintainer's stated plan covers only Ubuntu's names (see the scene before). The distribution on the slide is an example, not a real one.
for contributors
In the data
- Each INI file is turned into its own rule file,
data/050-NAME.gen.mk, by one run of rulegen.py (Makefile:48-58), and rulegen.py takesGroupandVariantfrom that file's[META]section (rulegen.py:336-348). So a second kind of image is a second INI file; the slide leavesGroupopen because the group decides more than the name (next scene, for contributors). - Today every family has one file with
Variant=cloud, for example fedora.ini:4-6.
Read more
09 What a new variant has to watch for contributors
Directories, users and templates key on the group, not the variant. Two variants with one Group share them; Ubuntu Core uses ubuntu-core as its group and ubuntu as its user.
If you add a variant, know what keys on what. rulegen.py reads Variant, but no rule uses it. The download directory, the everyday user and the cloud-init template all follow the group, and the template picker looks up group and release, never the variant. So two INI files that both say Group=ubuntu, one for cloud and one for desktop, would share a download directory and pick the same per-release templates. The check for clashing file names wouldn't help either: it runs on one INI file at a time. Ubuntu Core shows the way out. Its hand-written rules use ubuntu-core as the group, and ubuntu only as the user.
Details and sources
Details
Variantis read from[META]intoGroup.variant(rulegen.py:336-348); only theGroup.fullproperty uses it, and nothing callsfull(rulegen.py:32-48).str(group)andname_upperare the group's name alone.- The group names the download directory and its rule,
$(GARDEN_DL_DIR)/GROUP:(rulegen.py:448-451), the meta-data, the user and the template prefix (rulegen.py:460-467) and the download paths (rulegen.py:474-483). - The picker is called with the upper-case group and the release, and looks up
GROUP_RELEASE@INSTANCE,GROUP@INSTANCE,GROUP_RELEASE,GROUPand the default (010-qemu.mk:293-298). The host name is group and release too,ubuntu-24-04, in user-data and meta-data (010-qemu.mk:94-104, 010-qemu.mk:196). - The per-group file-name clash check is built afresh for each file named on the command line (rulegen.py:753-775), and the Makefile runs rulegen.py once per INI file (Makefile:57-58).
- Derived, not tried: a second INI file with
Group=ubuntuand anotherVariantwould put its downloads indl/ubuntu/next to the cloud images, use the sameUBUNTU_R…templates and hostnames for equal releases, emit a second recipe for thedl/ubuntudirectory rule, and two images with the same local file name in the two files would not be reported. - Ubuntu Core's rules pass
ubuntu-coreas the download directory and the group,only:ubuntuandubuntuas the users (050-ubuntu-core.mk:25-25, 050-ubuntu-core.mk:111-127); its host names start withubuntu-coretoo, as inubuntu-core-24-tpm, and pick templates with the keyUBUNTU_CORE, whose base template isUBUNTU_CORE_CLOUD_INIT_USER_DATA_TEMPLATE(050-ubuntu-core.mk:179-179). - So a new variant has two ways in: an INI file with its own
Variantand, if it must not share with an existing family, its ownGroup; or hand-written rules inmk/050-*.mk, as Ubuntu Core does. Which of these the planned Ubuntu variants will use is not decided in the source.
Read more
10 Where to go from here
Next: spread names, the support matrix, the template order, named instances, Ubuntu Core and its modifiers, and, for contributors, adding a system.
That's a name, part by part: group, variant, release, modifiers, instance, architecture. If you write spread tests, the spread names deck shows how to write plus and at in spread.yaml, and why the architecture goes missing there. The support matrix lists every group, release and architecture there is. To see what the release and the instance pick, go to the template order and to named instances. The Ubuntu Core decks cover the core variant and both of its modifiers. And if you're a contributor adding a system, a build-time deck shows how one is described.
Details and sources
Details
- The pattern in one line:
GROUP-VARIANT[-RELEASE][+MODIFIER…][@INSTANCE].ARCH, as inubuntu-cloud-24.04.x86_64. - The Ubuntu desktop and server names are planned by the maintainer and not in v0.8.0.
Read more
Basis of the statements on this page
Read in rulegen.py, data/*.ini, mk/010-qemu.mk, mk/020-instances.mk, mk/050-ubuntu-core.mk, the Makefile, the README and the manual page of image-garden at the commit in garden.commit ("code"). The count of systems was made from the section headers of data/*.ini at the tag. What two variants of one group would share is reasoned from the code and not tried ("derived"). The planned Ubuntu names come from the maintainer and are not in v0.8.0 ("planned").
The parts of a name
GROUP-VARIANT[-RELEASE][+MODIFIER…][@INSTANCE].ARCH
| Part | Example | Where it comes from |
|---|---|---|
| GROUP | ubuntu, fedora, opensuse | Group in the INI file's [META] section (ubuntu.ini:4-6); ubuntu-core in the hand-written Ubuntu Core rules |
| VARIANT | cloud, or core for Ubuntu Core | Variant in [META], cloud in all thirteen files; core is written into the Ubuntu Core rules |
| RELEASE | 24.04, 42, tumbleweed, 24 for Ubuntu Core; none for Arch Linux and Gentoo | Release in the system's section |
| +MODIFIER | +dangerous, +tpm, in alphabetical order | Ubuntu Core rules (050-ubuntu-core.mk:15-21) |
| @INSTANCE | @webserver | define-instance in .image-garden.mk (020-instances.mk:1-19) |
| ARCH | x86_64, aarch64, riscv64, s390x, ppc64 (named ppc64el), loongarch64 | Arch (rulegen.py:23-29) |
In the INI files the whole name is the section name, written by hand; rulegen.py checks only that it contains the Arch value (rulegen.py:395-405).
What each part selects
| Part | Selects | Source |
|---|---|---|
| GROUP | the download directory dl/GROUP/, the second user and its password, the upper-case template prefix, the hostname's first part | rulegen.py:447-483, 010-qemu.mk:94-104, 010-qemu.mk:196-211 |
| VARIANT | nothing in the rules; it names the kind of image | rulegen.py:32-48, rulegen.py:336-348 |
| RELEASE | a GROUP_RELEASE_CLOUD_INIT_USER_DATA_TEMPLATE if one is defined; the hostname's second part | 010-qemu.mk:293-298 |
| +dangerous | the dangerous-stable image channel | 050-ubuntu-core.mk:235-239 |
| +tpm | q35,smm=on, Secure Boot firmware, swtpm and a NAME.tpm/ state directory | 050-ubuntu-core.mk:55-68 |
| @INSTANCE | GROUP_RELEASE@INSTANCE and GROUP@INSTANCE templates; its own disk, seed and run script | 020-instances.mk:16-19, 010-qemu.mk:293-298 |
| ARCH | the run and provisioning rules, and with them the QEMU and its machine | rulegen.py:804-821 |
Examples
| Name | What it is |
|---|---|
ubuntu-cloud-24.04.x86_64 | Ubuntu 24.04 LTS cloud image on x86_64 |
fedora-cloud-42.riscv64 | Fedora 42 on RISC-V |
archlinux-cloud.x86_64 | Arch Linux, rolling, no release |
ubuntu-core-24+dangerous+tpm.x86_64 | Ubuntu Core 24, dangerous model, Secure Boot and a TPM |
ubuntu-cloud-24.04@webserver.x86_64 | a named instance of Ubuntu 24.04 |
The guest's host name
The group, the release and the instance joined with dashes, with every . and + turned into -, as a host name label allows neither (010-qemu.mk:94-97). user-data, /etc/hosts and the meta-data's local-hostname and instance-id all use it.
| System | Host name |
|---|---|
ubuntu-cloud-24.04.x86_64 | ubuntu-24-04 |
ubuntu-cloud-24.04@webserver.x86_64 | ubuntu-24-04-webserver |
ubuntu-core-24+tpm.x86_64 | ubuntu-core-24-tpm |
archlinux-cloud.x86_64 | archlinux |
The files made for a name
NAME.run, NAME.qcow2, NAME.qcow2.log, NAME.user-data, NAME.meta-data, NAME.seed.iso, and on UEFI systems NAME.efi-code.qcow2 and NAME.efi-vars.qcow2; +tpm systems also NAME.tpm/.
Planned names (not in v0.8.0)
The maintainer plans to name Ubuntu systems by kind of image, side by side:
| Planned name | Kind | At v0.8.0 |
|---|---|---|
ubuntu-core-RELEASE | Ubuntu Core | exists, as ubuntu-core-24 and the others |
ubuntu-desktop-RELEASE | desktop | not in the source |
ubuntu-server-RELEASE | server | not in the source |
ubuntu-cloud-RELEASE | cloud image | exists, as ubuntu-cloud-24.04 and the others |
Each is followed by .ARCH. This is a plan, not a feature of v0.8.0: there are no desktop or server images, sources or rules at the tag, and no date. The same pattern could name other distributions' editions; nothing of the kind is planned in the source.
for contributors
Adding a variant
Derived from the code, not tried. Directories, the second user, hostnames and templates key on the group, never on the variant. Two INI files with the same Group and different Variant would share dl/GROUP/ and the GROUP_RELEASE templates, and rulegen.py's file-name clash check, which runs on one INI file at a time (rulegen.py:753-775, Makefile:57-58), would not compare them. Ubuntu Core avoids this with hand-written rules that use ubuntu-core as the group and ubuntu as the user (050-ubuntu-core.mk:111-127).
In spread
spread names have no architecture and no + or @: ubuntu-core-24-plus-tpm, ubuntu-cloud-24.04-at-webserver. See spread names.
Roads from here
SYSTEMS · distributions
- The support matrix — every group, release and architecture there is
UBUNTU CORE · all snaps
- Ubuntu Core images — the ubuntu-core systems and their modifiers
- Changing a +dangerous Ubuntu Core system — what +dangerous changes
RUNTIME · make rules and the CLI
- Named instances — what an @instance gets of its own
SPREAD · tests
- spread names and garden names — how these names are written in spread.yaml, with -plus- and -at-
FIRST BOOT · cloud-init changes
- How a user-data template is chosen — the order in which group, release and instance pick a template
BUILD TIME · data and rules
- The .ini files in data/ — for contributors, how a new system is described