How a user-data template is chosen
group, release, instance for users for contributors
For each system image-garden uses one user-data template, the first defined of five names, from group, release and instance down to the common CLOUD_INIT_USER_DATA_TEMPLATE. A template starts from the common one, extends its runcmd list or adds sections such as packages, and replaces less specific templates rather than adding to them.
On the map: first boot
▶ Watch this deck — 6 scenes, ~4 min
Worth seeing first
- Changing what cloud-init does — where .image-garden.mk goes and when it is read
Part of journeys
- Your own systems with .image-garden.mk, step 2 of 4 · previous: Changing what cloud-init does · next: Named instances
01 A template decides the whole user-data
A template is the whole user-data of a system. image-garden picks one per system: the most specific one defined.
Hooks add a few lines. A template decides the whole user-data. Say all your Ubuntu systems need a build toolchain, your 24.04 system also needs one extra library, and one special instance of it needs something else again. image-garden lets you write a template at each of those levels, and for every system it picks exactly one: the most specific template you've defined. This deck shows the five names it looks for, how they're spelled, and how to write a template that keeps everything image-garden itself needs.
Details and sources
Details
PICK_CLOUD_INIT_USER_DATA_TEMPLATE_FORreturns the name of the first defined template, and the rule then calls that one (010-qemu.mk:280-298).- The README documents the template format, per-instance overrides and the lookup order (README.md:995-1051).
- The toolchain, library and instance are an example, not taken from image-garden.
Read more
- Changing what cloud-init does: the smaller hooks.
02 Five names, the first one defined wins
The order: group, release and instance; group and instance; group and release; group; then the common CLOUD_INIT_USER_DATA_TEMPLATE.
For a system, make looks for five variable names, in order, and takes the first one that's defined. First, group, release and instance together. Then group and instance, for that instance of any release. Then group and release. Then just the group. And last, the common template, which is always there. For our Ubuntu 24.04 system, which has no instance, that means the release template, then the group template, then the common one. The first two names only matter for named instances.
Details and sources
Details
- The picker is a make
$(or …)over the five names, each tested with$(value …), so the first defined one wins (010-qemu.mk:293-298). - For a system from
data/*.ini, the rule passes the group in capitals and the release, and no instance (rulegen.py:467); for a named instance it passes the instance too (020-instances.mk:75). - The common template is
CLOUD_INIT_USER_DATA_TEMPLATE, set toBASE_CLOUD_INIT_USER_DATA_TEMPLATE(010-qemu.mk:249). - The comment above the picker lists the same five names in the same order (010-qemu.mk:285-290), and so does the README (README.md:1046-1051).
Read more
03 How a template name is spelled
UBUNTU_24.04@webserver_CLOUD_INIT_USER_DATA_TEMPLATE: group in capitals, release with its dots, the instance after @. A misspelled name is never used, without a warning.
The names are built from the system's parts. The group is written in capitals, the release keeps its dots, and an instance comes after an at sign. Then comes the same ending every time, cloud init user data template. Dots and at signs look odd in a variable name, but make accepts them, and you write the template with define and endef like any other variable. One thing to watch: a misspelled name is simply never found, so the next one down the list wins, and nothing warns you.
Details and sources
Details
- The group's capitals come from
name.upper()(rulegen.py:47-48) and are passed to the picker with the release as written in the INI file (rulegen.py:467). The picker builds$1_$2@$(value 3)_CLOUD_INIT_USER_DATA_TEMPLATEand its shorter forms (010-qemu.mk:293-298). - The README's examples:
UBUNTU_24.04@webserver_CLOUD_INIT_USER_DATA_TEMPLATEandCENTOS@old-server_CLOUD_INIT_USER_DATA_TEMPLATE(README.md:1022-1044). - The README introduces them as "a variable named after the group in upper case, optionally the release, and the instance name after an
@, which is kept as it is" (README.md:1024-1026), as the picker builds them. - That a misspelled name goes unnoticed is derived: the picker tests each name with
$(value …)and moves on when it is empty.
Read more
04 Start from the common template
Begin with $(CLOUD_INIT_USER_DATA_TEMPLATE). Dash lines right after it extend runcmd; a key such as packages: starts a new section.
Inside a template, start with the common one: a reference to cloud init user data template on the first line. That's what creates the users, opens SSH and powers the machine off at the end, so leave it out and the provisioning boot never finishes. The common template ends with a runcmd list, so lines you add right after it, starting with a dash, become more commands. A new top-level key, such as packages, starts a new section, and its items are installed during the provisioning boot.
Details and sources
Details
- The common template sets
power_state, the users, SSH settings and files, and ends with aruncmd:list whose last command disables cloud-init (010-qemu.mk:187-247);CLOUD_INIT_USER_DATA_TEMPLATEis that template (010-qemu.mk:249). - The README's examples start with
$(CLOUD_INIT_USER_DATA_TEMPLATE), add a dash line after the comment "The template ends with runcmd:", thenpackages:(README.md:995-1020). Its notes: the default template "should always be included", and "You can assume the default template ends with aruncmdsection and append your commands as a YAML list" (README.md:1061-1070). - Derived: without
power_statecloud-init does not power the VM off, so the provisioning boot does not end and make waits for it. - A command appended to
runcmdruns aftertouch /etc/cloud/cloud-init.disabled; that file stops later boots, not the current one. - The
echoandbuild-essentiallines are an example.
Read more
05 Group or release: one replaces the other
Only one template is used. A release template can start from the group template to build on it, as image-garden's Debian template reuses its Ubuntu one.
A more specific template replaces the less specific one; nothing is merged. So once Ubuntu 24.04 has a template of its own, the Ubuntu group template no longer applies to it. To build on the group template instead, start the release template with the group template rather than the common one. image-garden's own file does something similar across families: its Debian template is simply its Ubuntu template. Put what every release needs in the group template, and keep release templates for real differences.
Details and sources
Details
- The picker returns one name, so one template is used per system (010-qemu.mk:293-298).
- image-garden's own
.image-garden.mkdefinesUBUNTU_CLOUD_INIT_USER_DATA_TEMPLATE, ending in apackages:list, and setsDEBIAN_CLOUD_INIT_USER_DATA_TEMPLATE=$(UBUNTU_CLOUD_INIT_USER_DATA_TEMPLATE)(.image-garden.mk:43-58). - Derived: a release template that starts with
$(UBUNTU_CLOUD_INIT_USER_DATA_TEMPLATE)expands the group template with the same arguments, as the Debian line does. What a following dash line extends depends on how that template ends: after the example group template, which ends inpackages:,- libextra-devis one more package. Illustrative, not run for this map. - The README's per-release example is
DEBIAN_13_CLOUD_INIT_USER_DATA_TEMPLATE(README.md:1000-1010).
Read more
06 Where to go from here
Next: named instances, several systems from one base image, and the hooks for smaller changes.
Five names, the first one defined wins, and every template starts from the common one or from a template that does. Named instances are where the first two names come in, and that deck shows how to make one. The profiles deck uses all of this for systems that boot differently or carry heavy software. And if you only need a file or an apt setting, the hooks are simpler. The table below the deck lists the names for a few examples.
Details and sources
Read more
Basis of the statements on this page
Read in mk/010-qemu.mk and the README of image-garden at the commit this map describes ("code").
The lookup order
For a system, the first template that is defined is used (010-qemu.mk:280-298):
| Order | Variable | Example for ubuntu-cloud-24.04@webserver.x86_64 |
|---|---|---|
| 1 | GROUP_RELEASE@INSTANCE_CLOUD_INIT_USER_DATA_TEMPLATE | UBUNTU_24.04@webserver_CLOUD_INIT_USER_DATA_TEMPLATE |
| 2 | GROUP@INSTANCE_CLOUD_INIT_USER_DATA_TEMPLATE | UBUNTU@webserver_CLOUD_INIT_USER_DATA_TEMPLATE |
| 3 | GROUP_RELEASE_CLOUD_INIT_USER_DATA_TEMPLATE | UBUNTU_24.04_CLOUD_INIT_USER_DATA_TEMPLATE |
| 4 | GROUP_CLOUD_INIT_USER_DATA_TEMPLATE | UBUNTU_CLOUD_INIT_USER_DATA_TEMPLATE |
| 5 | CLOUD_INIT_USER_DATA_TEMPLATE | the common template |
GROUP is the group in capitals; RELEASE keeps its dots. A template should start with $(CLOUD_INIT_USER_DATA_TEMPLATE), which ends with a runcmd: list you can append to (README "Local cloud-init Templates").
See several systems from one base image for worked examples.
Writing a template
| You want | Write |
|---|---|
| more commands | dash lines right after $(CLOUD_INIT_USER_DATA_TEMPLATE): they extend its runcmd: list |
| packages | a packages: key and a list |
| files | the EXTRA_CLOUD_INIT_FILES hook: a second write_files: key after the common template would, by the YAML rule that the last duplicate key wins, replace the common one (derived) |
| to build on the group template | start the release template with $(GROUP_CLOUD_INIT_USER_DATA_TEMPLATE) instead of the common one |
A template replaces every less specific one: nothing is merged. Every template must, directly or through another, start from $(CLOUD_INIT_USER_DATA_TEMPLATE), which creates the users, opens SSH and powers the machine off at the end of the provisioning boot. See changing what cloud-init does for the hooks.
Roads from here
START HERE
- How systems are named — where the parts of a name come from
RUNTIME · make rules and the CLI
- Named instances — named instances, where the first two names apply
FIRST BOOT · cloud-init changes
- Several systems from one base image — several systems from one base image, built once
- Changing what cloud-init does — hooks for smaller changes
- Provisioning runs once — why the common template powers the machine off