There are no docs for how to incorporate Ignition in a distro

[ajeddeloh]

Bug

Operating System Version

Any

Ignition Version

Any

Environment

Any

Expected Behavior

Requirements for Ignition to run in the initramfs are documented

Actual Behavior

There are no docs outlining how to include Ignition in the initramfs.

Reproduction Steps

1. Be a distro maintainer
2. See this snazzy thing called Ignition
3. Be lost at what needs to happen to include it in the initramfs

Other Information

cc @thkukuk since they might have some insight on what things would be helpful in that kind of document.

[thkukuk]

On Tue, Oct 16, Andrew Jeddeloh wrote: cc @thkukuk since they might have some insight on what things would be helpful in that kind of document.

For me, a little diagram how ignition works together with the rest of the system would be very helpfull. Else: - which requirements does ignition have? kernel modules and tools - from where does it get it's information? - what needs to be available in the initramfs at which point? - network - hard disk/partitions - which configurations files will be read in which order? - in which stages does it run? e.g. disk/files - what will be modified in which stage? As first ideas, I'm pretty sure more will come up.

…

-- Thorsten Kukuk, Distinguished Engineer, Senior Architect SLES & MicroOS SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nuernberg, Germany GF: Felix Imendoerffer, Jane Smithard, Graham Norton, HRB 21284 (AG Nuernberg)

[bgilbert]

Some notes:

Requirements from the distro include:

• Pass the correct platform ID for the current platform on the Ignition command line
  • For security reasons, we strongly recommend hardcoding the platform ID into the OS image rather than trying to detect it at runtime
• Ensure the ignition.firstboot kernel argument is set only on first boot
• Start networking in the initramfs if the fetch-offline stage indicates that it needs network
• Provide a kernel-arguments helper script, if the kernelArguments section is to be supported
• Properly configure networking on DigitalOcean and private networking on Packet
• If desired, copy an injected user config (e.g. from /boot/ignition/config.ign, or from /config.ign in an appended initrd) to /usr/lib/ignition/user.ign in the initrd. Consider deleting a persistent injected config (e.g. /boot/ignition) after Ignition completes successfully.
• If the distro supports running Ignition from a live OS image that isn't installed to disk, provide an is-live-image command in the initrd that exits 0 in the live image case.

[rfairley]

In #751, to document use of a build flag useAuthorizedKeysFile, I was initially looking for a file somewhere in https://github.com/coreos/ignition/tree/master/doc that could contain info on requirements pertaining to the distro. Adding another doc like distribution-integration.md or distribution-requirements.md would stand out I think.

[bgilbert]

We're trying to make ignition-dracut distro-independent, so we should reference that too.

coreos/ignition-dracut#56 requires the ignition binary to be installed into the dracut module directory. More generally, ignition should never be installed in the PATH.

[purpleidea]

Looks like this is similar to #763 and @dustymabe gave some great tips over there.

[arithx]

In #960 we added LUKS support and are now writing entries to /etc/crypttab when creating LUKS devices expecting that something (e.x.: systemd-cryptsetup-generator / clevis-luks-askpass) will create hooks to unlock the devices in the real root.

[bgilbert]

In #1250 / #1254 / #1267 we added a report in /etc/.ignition-result.json that the OS can use to get information about how the Ignition run went.

[bgilbert]

See also discussion in coreos/fedora-coreos-tracker#1311.