What differs per distribution
AL2, Gentoo, old Ubuntu for contributors
Three small make files adjust the common user-data. Amazon Linux 2, which ignores power_state, gets a release template that runs shutdown itself; Gentoo gets a group template that enables sshd; end-of-life Ubuntu interim releases get an apt block for old-releases.ubuntu.com through the apt hook. A project template with the same or a less specific name must keep those lines.
On the map: first boot
▶ Watch this deck — 6 scenes, ~4 min
Worth seeing first
- How a user-data template is chosen — how the five template names are looked up
01 One template, three exceptions
mk/050-amazonlinux-2.mk, mk/050.gentoo.mk and mk/050-ubuntu.mk adjust the common user-data. Ubuntu Core has its own template.
One template fits almost every system. ubuntu-cloud-24.04.x86_64 needs nothing extra, and neither do Fedora, Debian or Alpine. But three distributions need a nudge, and image-garden keeps each nudge in a small make file of its own. Amazon Linux 2 can't power itself off from cloud-init. Gentoo comes with its SSH server switched off. And Ubuntu releases past their end of life have moved to another mirror. Ubuntu Core goes further, with a whole template of its own, and its own deck covers that. This deck shows the three small ones, and what they mean for templates you write.
Details and sources
Details
mk/050-amazonlinux-2.mkdefinesAMAZONLINUX_2_CLOUD_INIT_USER_DATA_TEMPLATE(050-amazonlinux-2.mk:4-8);mk/050.gentoo.mkdefinesGENTOO_CLOUD_INIT_USER_DATA_TEMPLATE(050.gentoo.mk:4-8);mk/050-ubuntu.mkdefinesEXTRA_CLOUD_INIT_APT_CONFIG(050-ubuntu.mk:4-28).- The Ubuntu Core template is
BASE_UBUNTU_CORE_CLOUD_INIT_USER_DATA_TEMPLATE(050-ubuntu-core.mk:131-179); see Ubuntu Core images. image-garden.mkis built fromdata/000-systems.mk, then everymk/*.mkin sorted order, then the generated rules (Makefile:48-49).- No other file under
mk/defines a template or a hook for a distribution: the remaining files are QEMU per architecture, the instance macro and the project hook.
02 Amazon Linux 2 powers off by hand
AMAZONLINUX_2_CLOUD_INIT_USER_DATA_TEMPLATE is the common template plus - shutdown --poweroff now. Amazon Linux 2023 uses the common one.
Amazon Linux 2 doesn't support cloud-init's power state module, so its provisioning boot would never end. The fix is a template for one group and one release: Amazon Linux, release 2. It's the common template plus one more runcmd line, shutdown --poweroff now, which lands after the touch that disables cloud-init, at the very end. Because it names the release, Amazon Linux 2023 doesn't get it and uses the common template. The same file also picks a CPU model, neoverse-n1, for both releases on 64-bit Arm, but that's QEMU's business, not cloud-init's.
Details and sources
Details
- The file's comment: "Amazon Linux 2 does not support the power_state module so power off by hand." The template is
$(BASE_CLOUD_INIT_USER_DATA_TEMPLATE)followed by- shutdown --poweroff now(050-amazonlinux-2.mk:4-8). - The picker tries
AMAZONLINUX_2_CLOUD_INIT_USER_DATA_TEMPLATE(group and release) beforeAMAZONLINUX_…and the common one (010-qemu.mk:293-298); for release 2023 no such name is defined, so the common template is used. - The common template ends its
runcmdlist withtouch /etc/cloud/cloud-init.disabled(010-qemu.mk:246), so the added line comes after it. QEMU_CPU_AARCH64=neoverse-n1is set for the.qcow2and.runofamazonlinux-cloud-2.aarch64andamazonlinux-cloud-2023.aarch64(050-amazonlinux-2.mk:10-11); the README notes it too (README.md:621-625).- Amazon Linux 2 on x86_64 boots with BIOS, on aarch64 with EFI (amazonlinux.ini:8-24); the template is the same for both.
Read more
03 Gentoo switches SSH on
GENTOO_CLOUD_INIT_USER_DATA_TEMPLATE is the common template plus - systemctl enable --now sshd.service, in mk/050.gentoo.mk.
Gentoo's cloud image ships with its SSH server disabled. image-garden's Gentoo template, for the whole group, is again the common template plus one line, which enables the SSH service and starts it at once, in the same boot. Gentoo is a rolling release with no release number, so the group is the only level there is to name. One oddity: the file's name has a dot where the others have a dash. That doesn't matter, because the build takes every make file in that directory, whatever comes before the ending.
Details and sources
Details
- The file's comment: "Gentoo ships ssh disabled out of the box, so enable it." The template is
$(BASE_CLOUD_INIT_USER_DATA_TEMPLATE)followed by- systemctl enable --now sshd.service(050.gentoo.mk:4-8). - The Gentoo sections in
data/gentoo.inihave noRelease=(gentoo.ini:8-22), so the systems aregentoo-cloud.x86_64andgentoo-cloud.aarch64, and their host name isgentoo. image-garden.mkincludes$(sort $(filter mk/%.mk,$^))from$(wildcard mk/*.mk)(Makefile:48-49), somk/050.gentoo.mkis included like the others, aftermk/050-ubuntu.mkin sort order. Nothing in it depends on that order (derived): the template is a recursive variable, expanded only when a rule uses it.- The README says Gentoo is "not compatible with upstream Spread (SSH crypto algorithm mismatch)" (README.md:651-655).
Read more
04 Old Ubuntu releases get the old mirror
UBUNTU_OLD_RELEASES_VERSIONS lists 16.10 to 24.10. For those, EXTRA_CLOUD_INIT_APT_CONFIG adds apt: with preserve_sources_list: false and old-releases for primary and security.
Ubuntu moves releases past their end of life to an archive server, old-releases.ubuntu.com, and apt on those systems would look in the wrong place. image-garden keeps a list of thirteen such releases, the interim ones from 16.10 to 24.10. For those, the apt hook adds an apt section that replaces the sources list and points both the main archive and security updates at old-releases, over http. Every other Ubuntu, our 24.04 included, gets nothing. 25.04 and 25.10 are past their end of life too, but they were still in the usual archive when the list was last checked, so they aren't on it yet.
Details and sources
Details
UBUNTU_OLD_RELEASES_VERSIONS = 16.10 17.04 17.10 18.10 19.04 19.10 20.10 21.04 21.10 22.10 23.04 23.10 24.10, with the rule "if the release codename does not appear in https://archive.ubuntu.com/ubuntu/dists/ then apt must use old-releases" and the note that 25.04 and 25.10 were end of life but still in archive.ubuntu.com when the list was checked (050-ubuntu.mk:4-12).UBUNTU_OLD_RELEASES_APT_CONFIGemits theapt:block only when the group isubuntuand the release is on the list:preserve_sources_list: false, andprimaryandsecuritywitharches: [default]anduri: http://old-releases.ubuntu.com/ubuntu(050-ubuntu.mk:14-24).EXTRA_CLOUD_INIT_APT_CONFIGcalls it with the group and release (050-ubuntu.mk:26-28), and the common template calls the hook (010-qemu.mk:198).- The README: "EOL APT Source Rewrite: currently applied to Ubuntu 16.10 through 24.10 (EOL non-LTS releases)", and 25.04 and 25.10 "join the EOL APT source rewrite" once Ubuntu moves them (README.md:686-691).
- These releases are x86_64 only in
data/ubuntu.ini; see Ubuntu cloud images. - Derived, from cloud-init's behaviour:
preserve_sources_list: falsemakes cloud-init write the sources itself fromprimaryandsecurity.
Read more
05 Your template replaces these
A project's GENTOO_… template replaces image-garden's; an AMAZONLINUX_… group template loses to AMAZONLINUX_2_…. Keep the systemctl and shutdown lines.
These quirks are templates and hooks like any other, so yours can replace them. Define a Gentoo template in your project, and it replaces image-garden's, including the line that starts SSH. Keep that line. Amazon Linux is subtler. A template for the whole Amazon Linux group never reaches release 2, because image-garden's release template is more specific and wins. To change Amazon Linux 2, define its release template yourself, and keep the shutdown line at the end. The apt hook works the same way, and the hooks deck shows how to keep the old mirror.
Details and sources
Details
mk/999-local.mkincludes$(GARDEN_PROJECT_DIR)/.image-garden.mk(999-local.mk:4-5), after every othermk/*.mk, so adefinethere of an existing name replaces it.- The picker returns the first defined of group-release-instance, group-instance, group-release, group and the common name (010-qemu.mk:293-298). For
amazonlinux-cloud-2the group-release nameAMAZONLINUX_2_CLOUD_INIT_USER_DATA_TEMPLATEis always defined by image-garden (050-amazonlinux-2.mk:5-8), so a project'sAMAZONLINUX_CLOUD_INIT_USER_DATA_TEMPLATEapplies only to Amazon Linux 2023. - Both quirk templates start from
$(BASE_CLOUD_INIT_USER_DATA_TEMPLATE), not from$(CLOUD_INIT_USER_DATA_TEMPLATE)(050-amazonlinux-2.mk:6, 050.gentoo.mk:6). Derived: a project that redefinesCLOUD_INIT_USER_DATA_TEMPLATEto change every system does not change Amazon Linux 2 or Gentoo, which keep image-garden's base. - The apt hook: see a hook you define replaces image-garden's.
Read more
06 Where to go from here
Next: the template lookup, the hooks, provisioning, Ubuntu Core, and the Ubuntu releases.
Three small files: a shutdown for Amazon Linux 2, SSH for Gentoo, and the old mirror for Ubuntu past its end of life. The template deck has the lookup that decides which template wins, and the hooks deck shows how to redefine the apt hook without losing the old mirror. The provisioning deck explains the power-off Amazon Linux 2 has to do by hand. Ubuntu Core, with its whole template, has its own deck. And the Ubuntu deck lists which releases are past their end of life.
Details and sources
Read more
Basis of the statements on this page
Read in mk/050-amazonlinux-2.mk, mk/050.gentoo.mk, mk/050-ubuntu.mk, mk/010-qemu.mk, mk/999-local.mk and the Makefile of image-garden v0.8.0 ("code"). What a project template does to these is worked out from the picker ("derived").
The quirks
| File | Defines | Applies to | Change |
|---|---|---|---|
mk/050-amazonlinux-2.mk | AMAZONLINUX_2_CLOUD_INIT_USER_DATA_TEMPLATE | amazonlinux-cloud-2.* | - shutdown --poweroff now after the common runcmd (050-amazonlinux-2.mk:4-8) |
mk/050-amazonlinux-2.mk | QEMU_CPU_AARCH64=neoverse-n1 | amazonlinux-cloud-2.aarch64, amazonlinux-cloud-2023.aarch64 | QEMU's CPU model, not cloud-init (050-amazonlinux-2.mk:10-11) |
mk/050.gentoo.mk | GENTOO_CLOUD_INIT_USER_DATA_TEMPLATE | gentoo-cloud.* | - systemctl enable --now sshd.service after the common runcmd (050.gentoo.mk:4-8) |
mk/050-ubuntu.mk | EXTRA_CLOUD_INIT_APT_CONFIG | Ubuntu 16.10, 17.04, 17.10, 18.10, 19.04, 19.10, 20.10, 21.04, 21.10, 22.10, 23.04, 23.10, 24.10 | an apt: block for http://old-releases.ubuntu.com/ubuntu (050-ubuntu.mk:4-28) |
mk/050-ubuntu-core.mk | UBUNTU_CORE_CLOUD_INIT_USER_DATA_TEMPLATE | ubuntu-core-* | a template of its own; see Ubuntu Core images |
Writing a template for these systems
You define in .image-garden.mk | Effect on Amazon Linux 2 | Effect on Gentoo |
|---|---|---|
CLOUD_INIT_USER_DATA_TEMPLATE | none: its template starts from BASE_… | none: its template starts from BASE_… |
AMAZONLINUX_CLOUD_INIT_USER_DATA_TEMPLATE | none: AMAZONLINUX_2_… is more specific; Amazon Linux 2023 uses yours | – |
AMAZONLINUX_2_CLOUD_INIT_USER_DATA_TEMPLATE | replaces image-garden's: keep - shutdown --poweroff now last | – |
GENTOO_CLOUD_INIT_USER_DATA_TEMPLATE | – | replaces image-garden's: keep - systemctl enable --now sshd.service |
EXTRA_CLOUD_INIT_APT_CONFIG | – | – (replaces the old-releases block for Ubuntu: see changing what cloud-init does) |
The project file is included last (999-local.mk:4-5); the picker takes the first defined name (010-qemu.mk:293-298).
Roads from here
SYSTEMS · distributions
- Ubuntu cloud images — the Ubuntu releases and which of them are past their end of life
UBUNTU CORE · all snaps
- Ubuntu Core images — Ubuntu Core, which has a whole template of its own
FIRST BOOT · cloud-init changes
- How a user-data template is chosen — the lookup that decides which template a system gets
- Changing what cloud-init does — the apt hook and how to redefine it without losing old-releases
- Provisioning runs once — the power-off that Amazon Linux 2 has to do by hand
- SSH logins and apt sources — the SSH changes every other system gets