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

▶ Watch this deck — 10 scenes, ~8 min

01 One word is not enough

ONE WORD IS NOT ENOUGH the log says: “Ubuntu” which one? cloud image Ubuntu Core desktop server in many releases x86_64 · aarch64 · riscv64 · s390x · ppc64 · … ubuntu-cloud-24.04.x86_64 $ image-garden make ubuntu-cloud-24.04.x86_64.run ubuntu-cloud-24.04.x86_64.qcow2 .run .seed.iso .user-data .meta-data
A failing test whose log says only Ubuntu raises the question which one; Ubuntu comes as a cloud image, Ubuntu Core, a desktop and a server install, on several architectures; image-garden's name ubuntu-cloud-24.04.x86_64 settles it, and is both the make target and the prefix of every file made for the system

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, with Arch=x86_64, Boot=efi and Release=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.

02 The parts of a name

THE PARTS OF A NAME GROUP - VARIANT - RELEASE . ARCH ubuntu cloud 24.04 x86_64 ubuntu-cloud-24.04.x86_64 the running example fedora-cloud-42.riscv64 Fedora 42 on RISC-V archlinux-cloud.x86_64 rolling: no release +MODIFIER optional ubuntu-core-24+dangerous+tpm.x86_64 modifiers, in alphabetical order @INSTANCE optional ubuntu-cloud-24.04@webserver.x86_64 your own copy of a base system
The pattern GROUP-VARIANT-RELEASE+MODIFIER@INSTANCE.ARCH, with ubuntu, cloud, 24.04 and x86_64 under the four parts every Ubuntu cloud system has; examples ubuntu-cloud-24.04.x86_64, fedora-cloud-42.riscv64, archlinux-cloud.x86_64 with no release, ubuntu-core-24+dangerous+tpm.x86_64 with two modifiers in alphabetical order, and ubuntu-cloud-24.04@webserver.x86_64, an instance

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.$ARCH is 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 the Arch value, 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.ppc64el with Arch=ppc64: ppc64el contains ppc64 (ubuntu.ini:24-27).
  • The group and the variant are the [META] keys Group and Variant of each INI file, here Group=ubuntu, Variant=cloud (ubuntu.ini:4-6).
  • [fedora-cloud-42.riscv64] (fedora.ini:80-85); [archlinux-cloud.x86_64] has no Release key (archlinux.ini:8-12). Gentoo is the other system without a release.
  • Modifiers exist only on Ubuntu Core: +dangerous and +tpm. Make stops on +tpm+dangerous with "system modifiers go in alphabetical order: use … +dangerous+tpm …", and on +tpm for an architecture other than x86_64 (050-ubuntu-core.mk:15-21).
  • define-instance makes BASE@NAME.ARCH from a base system and an instance name, for example ubuntu-cloud-24.04@webserver.x86_64 (020-instances.mk:1-19).
  • Note on words: the README calls the +dangerous and +tpm systems "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

03 What each part chooses

WHAT EACH PART CHOOSES GROUP ubuntu cache dir dl/ubuntu/ · user ubuntu · prefix UBUNTU RELEASE 24.04 UBUNTU_24.04_CLOUD_INIT_USER_DATA_TEMPLATE, if defined +MODIFIER +dangerous +tpm another download channel · Secure Boot and swtpm @INSTANCE @webserver its own template, disk, seed and .run script ARCH x86_64 the QEMU for that architecture, and its machine VARIANT cloud no rule reads it: it names the kind of image
Each part of ubuntu-cloud-24.04.x86_64 and its optional parts, with what it selects: the group ubuntu picks the cache directory dl/ubuntu/, the user ubuntu and the template prefix UBUNTU; the release 24.04 a per-release cloud-init template if one is defined; the modifiers +dangerous and +tpm another download channel, and Secure Boot with swtpm; an @instance its own template, disk, seed and .run script; the architecture the QEMU; the variant cloud is read by no rule and names the kind of image

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 Group key 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 --query reports (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 default CLOUD_INIT_USER_DATA_TEMPLATE (010-qemu.mk:293-298). image-garden itself defines no UBUNTU_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/hosts and the meta-data's local-hostname (010-qemu.mk:94-104, 010-qemu.mk:196).
  • Modifiers. +dangerous downloads from the dangerous-stable channel instead of stable (050-ubuntu-core.mk:235-239); +tpm sets the machine to q35,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+tpm names itself ubuntu-core-24-tpm (010-qemu.mk:94-97, 050-ubuntu-core.mk:141).
  • Instance. define-instance gives BASE@NAME.ARCH its 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 Arch and Boot (rulegen.py:804-821); each architecture's QEMU command is in its own mk/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 core into theirs.

for contributors

In the code

  • rulegen.py reads Variant from [META] (rulegen.py:336-348) into Group.variant. Its only use is the Group.full property (rulegen.py:32-48), and nothing calls full. str(group) is the group's name alone, and that is what the rule templates and --systems-meta use (rulegen.py:824-833).

04 What exists today for contributors in place of the general version

WHAT EXISTS TODAY almalinux-cloud alpine-cloud amazonlinux-cloud archlinux-cloud centos-cloud debian-cloud fedora-cloud gentoo-cloud opencloudos-cloud opensuse-cloud oracle-cloud rocky-cloud ubuntu-cloud [META] Group=fedora Variant=cloud Variant=cloud in all thirteen ubuntu-core hand-written rules, not an INI file the variant is always in the name fedora-42 could have been fedora-cloud-42 is: room for a second kind
Thirteen families, almalinux-cloud to ubuntu-cloud, each from an INI file whose [META] section says Variant=cloud, and ubuntu-core from hand-written rules; the variant is always in the name, so Fedora 42 is fedora-cloud-42 where it could have been fedora-42, and the name has room for a second kind of image

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] has Group= the file's name and Variant=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_64 for releases 16 to 26 with their +dangerous forms, ubuntu-core-R.aarch64 from 22 on, and the four +tpm systems on x86_64. Its releases are written 24, 26, not 24.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).

05 What exists today general version

WHAT EXISTS TODAY almalinux-cloud alpine-cloud amazonlinux-cloud archlinux-cloud centos-cloud debian-cloud fedora-cloud gentoo-cloud opencloudos-cloud opensuse-cloud oracle-cloud rocky-cloud ubuntu-cloud variant cloud the distribution's own cloud image in all thirteen ubuntu-core from Ubuntu's all-snaps images the variant is always in the name fedora-42 could have been fedora-cloud-42 is: room for a second kind
Thirteen families, almalinux-cloud to ubuntu-cloud, each with the variant cloud, as each boots its distribution's cloud image, and ubuntu-core from Ubuntu's all-snaps images; the variant is always in the name, so Fedora 42 is fedora-cloud-42 where it could have been fedora-42, and the name has room for a second kind of image

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_64 for releases 16 to 26 with their +dangerous forms, ubuntu-core-R.aarch64 from 22 on, and the four +tpm systems on x86_64. Its releases are written 24, 26, not 24.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] has Group= the file's name and Variant=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_64 for releases 16 to 26 with their +dangerous forms, ubuntu-core-R.aarch64 from 22 on, and the four +tpm systems on x86_64. Its releases are written 24, 26, not 24.04.

06 Four planned Ubuntu siblings

PLANNED BY THE MAINTAINER Ubuntu, one release ubuntu-core-… today ubuntu-desktop-… planned ubuntu-server-… planned ubuntu-cloud-… today each followed by -RELEASE.ARCH told apart by the variant alone ubuntu-cloud-24.04.x86_64 stays as it is, and so does every ubuntu-core name desktop and server: a plan, not something you can build yet
Planned by the maintainer: one Ubuntu release as four sibling names, ubuntu-core, ubuntu-desktop, ubuntu-server and ubuntu-cloud, each followed by a release and an architecture and told apart by the variant; core and cloud exist today, desktop and server are planned and cannot be built yet; ubuntu-cloud-24.04.x86_64 and the ubuntu-core names stay as they are

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-RELEASE and ubuntu-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 the ubuntu-core-… systems of 050-ubuntu-core.mk:4-16.
  • Ubuntu Core's releases are written 24, 26 at the tag, Ubuntu's cloud releases 24.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 cloud or core ones.

07 Room for other editions for contributors in place of the general version

ROOM FOR OTHER EDITIONS a distribution, hypothetical cloud image server install workstation edition NAME-cloud-R.ARCH NAME-server-R.ARCH NAME-workstation-R.ARCH [META] Group=… Variant=cloud [META] Group=… Variant=server [META] Group=… Variant=workstation one INI file per kind, rules from each file as today none of this exists yet, and none of it is promised one more word in a slot that is already there
A hypothetical distribution with a cloud image, a server install and a workstation edition would be named NAME-cloud-R.ARCH, NAME-server-R.ARCH and NAME-workstation-R.ARCH, each from its own INI file with its own Variant line; none of this exists or is promised, it is what one more word in the existing slot allows

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 takes Group and Variant from that file's [META] section (rulegen.py:336-348). So a second kind of image is a second INI file; the slide leaves Group open 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.

08 Room for other editions general version

ROOM FOR OTHER EDITIONS a distribution, hypothetical cloud image server install workstation edition NAME-cloud-R.ARCH NAME-server-R.ARCH NAME-workstation-R.ARCH $ image-garden make \ NAME-cloud-R.x86_64.run $ image-garden make \ NAME-server-R.x86_64.run $ image-garden make \ NAME-workstation-R.x86_64.run each kind its own systems, built the way cloud images are today none of this exists yet, and none of it is promised one more word in a slot that is already there
A hypothetical distribution with a cloud image, a server install and a workstation edition would be named NAME-cloud-R.ARCH, NAME-server-R.ARCH and NAME-workstation-R.ARCH, each kind its own set of systems, built the way cloud images are today; none of this exists or is promised, it is what one more word in the existing slot allows

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 takes Group and Variant from that file's [META] section (rulegen.py:336-348). So a second kind of image is a second INI file; the slide leaves Group open 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.

09 What a new variant has to watch for contributors

WHAT KEYS ON WHAT [META] Group=ubuntu Variant=desktop Variant: read, then used by no rule download dir dl/ubuntu/ · user ubuntu template UBUNTU_RELEASE_CLOUD_INIT_USER_DATA_TEMPLATE ubuntu.ini Group=ubuntu Variant=cloud a desktop INI file Group=ubuntu Variant=desktop one dl/ubuntu/, the same templates the file-name clash check sees one INI file at a time Ubuntu Core: group ubuntu-core (dl/ubuntu-core/, UBUNTU_CORE_…), user ubuntu
In an INI file's [META] section, Group decides the download directory, the user and the template prefix, while Variant is read and used by no rule; two INI files with Group=ubuntu, one cloud and one desktop, would share dl/ubuntu/ and the UBUNTU_RELEASE templates, and the file-name clash check runs on one file at a time; Ubuntu Core's hand-written rules use ubuntu-core as the group and ubuntu as the user

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

  • Variant is read from [META] into Group.variant (rulegen.py:336-348); only the Group.full property uses it, and nothing calls full (rulegen.py:32-48). str(group) and name_upper are 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, GROUP and 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=ubuntu and another Variant would put its downloads in dl/ubuntu/ next to the cloud images, use the same UBUNTU_R… templates and hostnames for equal releases, emit a second recipe for the dl/ubuntu directory rule, and two images with the same local file name in the two files would not be reported.
  • Ubuntu Core's rules pass ubuntu-core as the download directory and the group, only:ubuntu and ubuntu as the users (050-ubuntu-core.mk:25-25, 050-ubuntu-core.mk:111-127); its host names start with ubuntu-core too, as in ubuntu-core-24-tpm, and pick templates with the key UBUNTU_CORE, whose base template is UBUNTU_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 Variant and, if it must not share with an existing family, its own Group; or hand-written rules in mk/050-*.mk, as Ubuntu Core does. Which of these the planned Ubuntu variants will use is not decided in the source.

10 Where to go from here

ROADS System names spread names -plus-, -at-, no architecture What runs where every group and release Template order group, release, instance Named instances @NAME and its own disk Ubuntu Core the core variant +dangerous a modifier at work Adding a system for contributors
Seven roads from this deck: spread names, the support matrix, the template order, named instances, Ubuntu Core, plus dangerous, and, for contributors, adding a system

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 in ubuntu-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

PartExampleWhere it comes from
GROUPubuntu, fedora, opensuseGroup in the INI file's [META] section (ubuntu.ini:4-6); ubuntu-core in the hand-written Ubuntu Core rules
VARIANTcloud, or core for Ubuntu CoreVariant in [META], cloud in all thirteen files; core is written into the Ubuntu Core rules
RELEASE24.04, 42, tumbleweed, 24 for Ubuntu Core; none for Arch Linux and GentooRelease in the system's section
+MODIFIER+dangerous, +tpm, in alphabetical orderUbuntu Core rules (050-ubuntu-core.mk:15-21)
@INSTANCE@webserverdefine-instance in .image-garden.mk (020-instances.mk:1-19)
ARCHx86_64, aarch64, riscv64, s390x, ppc64 (named ppc64el), loongarch64Arch (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

PartSelectsSource
GROUPthe download directory dl/GROUP/, the second user and its password, the upper-case template prefix, the hostname's first partrulegen.py:447-483, 010-qemu.mk:94-104, 010-qemu.mk:196-211
VARIANTnothing in the rules; it names the kind of imagerulegen.py:32-48, rulegen.py:336-348
RELEASEa GROUP_RELEASE_CLOUD_INIT_USER_DATA_TEMPLATE if one is defined; the hostname's second part010-qemu.mk:293-298
+dangerousthe dangerous-stable image channel050-ubuntu-core.mk:235-239
+tpmq35,smm=on, Secure Boot firmware, swtpm and a NAME.tpm/ state directory050-ubuntu-core.mk:55-68
@INSTANCEGROUP_RELEASE@INSTANCE and GROUP@INSTANCE templates; its own disk, seed and run script020-instances.mk:16-19, 010-qemu.mk:293-298
ARCHthe run and provisioning rules, and with them the QEMU and its machinerulegen.py:804-821

Examples

NameWhat it is
ubuntu-cloud-24.04.x86_64Ubuntu 24.04 LTS cloud image on x86_64
fedora-cloud-42.riscv64Fedora 42 on RISC-V
archlinux-cloud.x86_64Arch Linux, rolling, no release
ubuntu-core-24+dangerous+tpm.x86_64Ubuntu Core 24, dangerous model, Secure Boot and a TPM
ubuntu-cloud-24.04@webserver.x86_64a 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.

SystemHost name
ubuntu-cloud-24.04.x86_64ubuntu-24-04
ubuntu-cloud-24.04@webserver.x86_64ubuntu-24-04-webserver
ubuntu-core-24+tpm.x86_64ubuntu-core-24-tpm
archlinux-cloud.x86_64archlinux

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 nameKindAt v0.8.0
ubuntu-core-RELEASEUbuntu Coreexists, as ubuntu-core-24 and the others
ubuntu-desktop-RELEASEdesktopnot in the source
ubuntu-server-RELEASEservernot in the source
ubuntu-cloud-RELEASEcloud imageexists, 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

UBUNTU CORE · all snaps

RUNTIME · make rules and the CLI

SPREAD · tests

FIRST BOOT · cloud-init changes

BUILD TIME · data and rules