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

01 One template, three exceptions

QUIRKS the common template Ubuntu 24.04, Fedora, Debian, Alpine … nothing extra mk/050-amazonlinux-2.mk Amazon Linux 2: power off by hand mk/050.gentoo.mk Gentoo: switch SSH on mk/050-ubuntu.mk Ubuntu past end of life: the old mirror mk/050-ubuntu-core.mk Ubuntu Core: a whole template, its own deck and what they mean for templates you write
The common template serves Ubuntu 24.04, Fedora, Debian, Alpine and most others unchanged; three small make files adjust it: mk/050-amazonlinux-2.mk powers Amazon Linux 2 off by hand, mk/050.gentoo.mk switches Gentoo's SSH on, mk/050-ubuntu.mk points end-of-life Ubuntu at the old mirror; Ubuntu Core has a whole template of its own

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.mk defines AMAZONLINUX_2_CLOUD_INIT_USER_DATA_TEMPLATE (050-amazonlinux-2.mk:4-8); mk/050.gentoo.mk defines GENTOO_CLOUD_INIT_USER_DATA_TEMPLATE (050.gentoo.mk:4-8); mk/050-ubuntu.mk defines EXTRA_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.mk is built from data/000-systems.mk, then every mk/*.mk in 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

AMAZON LINUX 2 power_state: poweroff not supported: the boot would never end define AMAZONLINUX_2_CLOUD_INIT_USER_DATA_TEMPLATE $(BASE_CLOUD_INIT_USER_DATA_TEMPLATE) - shutdown --poweroff now endef the end of runcmd: - touch …/cloud-init.disabled - shutdown --poweroff now Amazon Linux 2023: the common template same file, for QEMU: -cpu neoverse-n1 on aarch64, both releases
Amazon Linux 2 ignores power_state, so its provisioning boot would never end; AMAZONLINUX_2_CLOUD_INIT_USER_DATA_TEMPLATE is the common template plus shutdown --poweroff now, which runs after the touch of cloud-init.disabled; Amazon Linux 2023 uses the common template; the same file sets -cpu neoverse-n1 for both releases on aarch64

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) before AMAZONLINUX_… 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 runcmd list with touch /etc/cloud/cloud-init.disabled (010-qemu.mk:246), so the added line comes after it.
  • QEMU_CPU_AARCH64=neoverse-n1 is set for the .qcow2 and .run of amazonlinux-cloud-2.aarch64 and amazonlinux-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.

03 Gentoo switches SSH on

GENTOO sshd: disabled in the image define GENTOO_CLOUD_INIT_USER_DATA_TEMPLATE $(BASE_CLOUD_INIT_USER_DATA_TEMPLATE) endef - systemctl enable --now sshd.service enabled and started, now no release number: the group is the only level gentoo-cloud.x86_64, gentoo-cloud.aarch64 mk/050.gentoo.mk a dot, not a dash read anyway: the build takes every mk/*.mk
Gentoo's cloud image has sshd disabled; GENTOO_CLOUD_INIT_USER_DATA_TEMPLATE is the common template plus systemctl enable --now sshd.service, which enables and starts it in the same boot; Gentoo has no release, so the group is the only level; the file mk/050.gentoo.mk has a dot instead of a dash, and the build includes every mk/*.mk

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.ini have no Release= (gentoo.ini:8-22), so the systems are gentoo-cloud.x86_64 and gentoo-cloud.aarch64, and their host name is gentoo.
  • image-garden.mk includes $(sort $(filter mk/%.mk,$^)) from $(wildcard mk/*.mk) (Makefile:48-49), so mk/050.gentoo.mk is included like the others, after mk/050-ubuntu.mk in 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).

04 Old Ubuntu releases get the old mirror

OLD UBUNTU past end of life: old-releases.ubuntu.com UBUNTU_OLD_RELEASES_VERSIONS, thirteen interim releases 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 apt: preserve_sources_list: false primary: - arches: [default] uri: http://old-releases.ubuntu.com/ubuntu security: (the same) 24.04 and the rest: nothing 25.04, 25.10: not on it yet still in the usual archive
UBUNTU_OLD_RELEASES_VERSIONS lists thirteen interim releases from 16.10 to 24.10; for those the apt hook adds an apt section with preserve_sources_list false and primary and security at http://old-releases.ubuntu.com/ubuntu; Ubuntu 24.04 and other releases get nothing; 25.04 and 25.10 are end of life but not yet on the list

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_CONFIG emits the apt: block only when the group is ubuntu and the release is on the list: preserve_sources_list: false, and primary and security with arches: [default] and uri: http://old-releases.ubuntu.com/ubuntu (050-ubuntu.mk:14-24). EXTRA_CLOUD_INIT_APT_CONFIG calls 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: false makes cloud-init write the sources itself from primary and security.

05 Your template replaces these

YOURS REPLACES THEIRS .image-garden.mk is read last: the same name replaces your GENTOO_…_TEMPLATE replaces image-garden's keep: - systemctl enable --now sshd.service your AMAZONLINUX_…_TEMPLATE AMAZONLINUX_2_…: more specific never reaches Amazon Linux 2 your AMAZONLINUX_2_…_TEMPLATE keep: - shutdown --poweroff now the apt hook: the same, see changing what cloud-init does
A project's GENTOO template replaces image-garden's, so it must keep systemctl enable --now sshd.service; a project's AMAZONLINUX group template loses to image-garden's AMAZONLINUX_2 release template, so to change Amazon Linux 2 define AMAZONLINUX_2 and keep shutdown --poweroff now; the apt hook is replaced the same way

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.mk includes $(GARDEN_PROJECT_DIR)/.image-garden.mk (999-local.mk:4-5), after every other mk/*.mk, so a define there 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-2 the group-release name AMAZONLINUX_2_CLOUD_INIT_USER_DATA_TEMPLATE is always defined by image-garden (050-amazonlinux-2.mk:5-8), so a project's AMAZONLINUX_CLOUD_INIT_USER_DATA_TEMPLATE applies 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 redefines CLOUD_INIT_USER_DATA_TEMPLATE to 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.

06 Where to go from here

ROADS The quirks Picking a template which one wins The hooks keeping the old mirror Provisioning runs once the power-off Ubuntu Core a whole template Ubuntu releases which are past end of life
Roads from this deck: how a user-data template is chosen, changing what cloud-init does, provisioning runs once, Ubuntu Core images, and Ubuntu cloud images

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

FileDefinesApplies toChange
mk/050-amazonlinux-2.mkAMAZONLINUX_2_CLOUD_INIT_USER_DATA_TEMPLATEamazonlinux-cloud-2.*- shutdown --poweroff now after the common runcmd (050-amazonlinux-2.mk:4-8)
mk/050-amazonlinux-2.mkQEMU_CPU_AARCH64=neoverse-n1amazonlinux-cloud-2.aarch64, amazonlinux-cloud-2023.aarch64QEMU's CPU model, not cloud-init (050-amazonlinux-2.mk:10-11)
mk/050.gentoo.mkGENTOO_CLOUD_INIT_USER_DATA_TEMPLATEgentoo-cloud.*- systemctl enable --now sshd.service after the common runcmd (050.gentoo.mk:4-8)
mk/050-ubuntu.mkEXTRA_CLOUD_INIT_APT_CONFIGUbuntu 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.10an apt: block for http://old-releases.ubuntu.com/ubuntu (050-ubuntu.mk:4-28)
mk/050-ubuntu-core.mkUBUNTU_CORE_CLOUD_INIT_USER_DATA_TEMPLATEubuntu-core-*a template of its own; see Ubuntu Core images

Writing a template for these systems

You define in .image-garden.mkEffect on Amazon Linux 2Effect on Gentoo
CLOUD_INIT_USER_DATA_TEMPLATEnone: its template starts from BASE_…none: its template starts from BASE_…
AMAZONLINUX_CLOUD_INIT_USER_DATA_TEMPLATEnone: AMAZONLINUX_2_… is more specific; Amazon Linux 2023 uses yours–
AMAZONLINUX_2_CLOUD_INIT_USER_DATA_TEMPLATEreplaces 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 CORE · all snaps

FIRST BOOT · cloud-init changes