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

Part of journeys

01 A template decides the whole user-data

TEMPLATES a hook: a few lines a template: the whole user-data every Ubuntu: a build toolchain Ubuntu 24.04: one extra library one instance of it: something else one template per system: the most specific five names · how they are spelled · what every template keeps
A hook adds a few lines, a template is the whole user-data; three levels of need: every Ubuntu needs a build toolchain, Ubuntu 24.04 an extra library, one instance something else; each system gets exactly one template, the most specific one defined

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_FOR returns 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

02 Five names, the first one defined wins

FIVE NAMES ubuntu-cloud-24.04: 1 GROUP_RELEASE@INSTANCE_… 2 GROUP@INSTANCE_… 3 GROUP_RELEASE_… 4 GROUP_… 5 CLOUD_INIT_USER_DATA_TEMPLATE, always there UBUNTU_24.04_… UBUNTU_… the common one instances only instances only each name ends in _CLOUD_INIT_USER_DATA_TEMPLATE
Five template names in order: GROUP_RELEASE@INSTANCE, GROUP@INSTANCE, GROUP_RELEASE, GROUP and the common CLOUD_INIT_USER_DATA_TEMPLATE; for ubuntu-cloud-24.04 the candidates are UBUNTU_24.04, UBUNTU and the common one, while the first two apply only to instances

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 to BASE_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

SPELLING UBUNTU_ group, capitals 24.04 release, dots kept @webserver instance _CLOUD_INIT_USER_DATA_TEMPLATE the same ending every time define UBUNTU_24.04@webserver_CLOUD_INIT_USER_DATA_TEMPLATE $(CLOUD_INIT_USER_DATA_TEMPLATE) endef UBUNTU_24.4_…: never found, the next name wins, no warning
A template name assembled from parts: UBUNTU, the group in capitals; 24.04, the release with its dots; @webserver, the instance; and the common ending _CLOUD_INIT_USER_DATA_TEMPLATE; it is defined with define and endef; a misspelled name is silently skipped

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_TEMPLATE and its shorter forms (010-qemu.mk:293-298).
  • The README's examples: UBUNTU_24.04@webserver_CLOUD_INIT_USER_DATA_TEMPLATE and CENTOS@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

START FROM THE COMMON ONE define UBUNTU_CLOUD_INIT_USER_DATA_TEMPLATE $(CLOUD_INIT_USER_DATA_TEMPLATE) endef users, SSH, power off at the end leave it out: no power-off, the provisioning boot never ends - echo hello from the template a dash line: one more runcmd command packages: - build-essential a new key: a new section, installed while provisioning
A template starts with $(CLOUD_INIT_USER_DATA_TEMPLATE), which brings the users, SSH and the power-off; a dash line after it adds a runcmd command; packages starts a new section installed while provisioning; without the common template the provisioning boot never powers off

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 a runcmd: list whose last command disables cloud-init (010-qemu.mk:187-247); CLOUD_INIT_USER_DATA_TEMPLATE is 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:", then packages: (README.md:995-1020). Its notes: the default template "should always be included", and "You can assume the default template ends with a runcmd section and append your commands as a YAML list" (README.md:1061-1070).
  • Derived: without power_state cloud-init does not power the VM off, so the provisioning boot does not end and make waits for it.
  • A command appended to runcmd runs after touch /etc/cloud/cloud-init.disabled; that file stops later boots, not the current one.
  • The echo and build-essential lines are an example.

05 Group or release: one replaces the other

GROUP OR RELEASE UBUNTU_…: the group template UBUNTU_24.04_…: the release template 24.04 uses only the release one define UBUNTU_24.04_CLOUD_INIT_USER_DATA_TEMPLATE $(UBUNTU_CLOUD_INIT_USER_DATA_TEMPLATE) - libextra-dev endef the group's, then more DEBIAN_CLOUD_INIT_USER_DATA_TEMPLATE=$(UBUNTU_CLOUD_INIT_USER_DATA_TEMPLATE) group: what every release needs · release: real differences
When UBUNTU_24.04 and UBUNTU templates both exist, 24.04 uses only the release template; a release template that starts with $(UBUNTU_CLOUD_INIT_USER_DATA_TEMPLATE) builds on the group one; image-garden's Debian template is its Ubuntu template

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.mk defines UBUNTU_CLOUD_INIT_USER_DATA_TEMPLATE, ending in a packages: list, and sets DEBIAN_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 in packages:, - libextra-dev is 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).

06 Where to go from here

ROADS Picking a template Named instances the first two names One base, many VMs profiles built once Your own changes hooks for files and apt System names where the parts come from
Roads from this deck: named instances, several systems from one base image, changing what cloud-init does with hooks, and system names

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):

OrderVariableExample for ubuntu-cloud-24.04@webserver.x86_64
1GROUP_RELEASE@INSTANCE_CLOUD_INIT_USER_DATA_TEMPLATEUBUNTU_24.04@webserver_CLOUD_INIT_USER_DATA_TEMPLATE
2GROUP@INSTANCE_CLOUD_INIT_USER_DATA_TEMPLATEUBUNTU@webserver_CLOUD_INIT_USER_DATA_TEMPLATE
3GROUP_RELEASE_CLOUD_INIT_USER_DATA_TEMPLATEUBUNTU_24.04_CLOUD_INIT_USER_DATA_TEMPLATE
4GROUP_CLOUD_INIT_USER_DATA_TEMPLATEUBUNTU_CLOUD_INIT_USER_DATA_TEMPLATE
5CLOUD_INIT_USER_DATA_TEMPLATEthe 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 wantWrite
more commandsdash lines right after $(CLOUD_INIT_USER_DATA_TEMPLATE): they extend its runcmd: list
packagesa packages: key and a list
filesthe 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 templatestart 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

RUNTIME · make rules and the CLI

FIRST BOOT · cloud-init changes