Creating derivatives

A derivative is a standard container image which can be booted by cOS.

We can identify a build phase where we build the derivative, and a “runtime phase” where we consume it.

The image is described by a Dockerfile, composed of a base OS of choice (e.g. openSUSE, Ubuntu, etc. ) and the cOS toolkit itself in order to be consumed by cOS and allow to be upgraded from by other derivatives.

cOS-toolkit then converts the OCI artifact into a bootable medium (ISO, packer, ova, etc) and the image itself then can be used to bootstrap other derivatives, which can in turn upgrade to any derivative built with cOS.

A derivative can also be later re-used again as input as base-image for downstream derivatives.

All the documentation below imply that the container image generated will be the booting one, there are however several configuration entrypoint that you should keep in mind while building the image which are general across all the implementation:

• Custom persistent runtime configuration has to be provided in /system/oem for derivatives, see also the documentation section. Everything under /system/oem will be loaded during the various stages (boot, network, initramfs). You can check here for the cOS defaults. See 00_rootfs.yaml to customize the booting layout.
• /etc/cos/bootargs.cfg contains the booting options required to boot the image with GRUB, see grub customization
• /etc/cos-upgrade-image contains the default upgrade configuration for recovery and the booting system image, see customizing upgrades

Derivatives inherits cOS defaults, which you can override during the build process, however there are some defaults which are relevant and listed below: