ISO-embedded Ignition configuration

CoreOS ISO images are typically used for live-booting machines directly from a read-only storage device (e.g. a CD-ROM or USB stick) on non-cloud platforms.

First-boot provisioning via Ignition in such environments is difficult, as there are no well-defined metadata endpoints, there may not be any hypervisor back-channels or writable disks, and manual entry of an Ignition URL on the kernel command line is not ergonomic.

For such reasons coreos-installer supports a special mode for ISO images, where an Ignition configuration file can be embedded as a user customization into a pristine image. The resulting image can be then used to boot a live system which is provisioned with the given Ignition configuration.

Technical details

The ISO-embedding mechanism works by modifying some raw data directly on the image. The technical specifications are described below to help third-party logic.

CoreOS ISO images come with some reserved empty space, the “embed area”, which can be used to inject the Ignition configuration. The embed area is a block of padding stored at /images/ignition.img in the ISO image. The bootloader is configured to load this file as an additional initrd image. The embed area is zeroed by default, meaning that the image is a pristine one without any user customization.

User customization is performed by parsing the ISO9660 filesystem to determine the offset and length of the embed area file, and writing an xz-compressed newc cpio archive (i.e. the equivalent of a .cpio.xz file) directly into it. Such an archive may contain a regular file named config.ign, which can hold any custom Ignition configuration.

This archive is then detected and unpacked in the initrd for Ignition consumption.