Version: 1.2

Customize Elemental Install

Elemental Teal images can be customized in different ways. One option is to provide additional resources within the installation media so that during installation, or eventually at boot time, additional binaries such as drivers can be included.

Another option would be to remaster the Elemental Teal by simply using a docker build. Elemental Teal is a regular container image, so it is absolutely possible to create a new image using a Dockerfile based on Elemental Teal image.

Customize installation ISO and installation process

In order to adapt the installation ISO a simple approach is to append extra configuration files into the ISO root in an analog way the registration yaml configuration file is added.

Common customization pattern

Elemental Teal installation can be customized in three different non-exclusive ways. First, including some custom Elemental client configuration file, second, by including additional cloud-init files to execute at boot time, and finally, by including cloud-init files such as installation hooks or boot stages evaluated during the live system boot itself.

A common pattern is to combine the three ways described above. This pattern will allow you to add custom steps during the installation and add cloud-init files to be evaluated at boot time.

To apply this pattern, the ISO needs to include:

A configuration file for the elemental client, describing at least the installation hooks location. This file is usually added to the ISO with path and name /elemental/config.yaml.
The additional cloud-init files to be included into the installed system. They allow to perform custom operations at boot time.
The installation hooks are evalutated at install time. They allow to perform custom operations during the installation process (include extra software, set additional disks...). The same way cloud-init files can be included to perform custom operations during the live installation media boot time.

Custom Elemental client configuration file

Elemental client install, upgrade and reset commands can be configured with a custom configuration file located by default in /elemental/config.yaml or, if you have multiple yaml files, the /elemental/config.d directory will be loaded too.

A simple example to set hooks location could be:

extra-partitions:
  - size: 10240
    fs: ext4
    label: EXTRA_PARTITION

The above example sets an additional extra partition during the installation.

Adding additional cloud-init files within the installed OS

In order to include additional cloud-init files during the installation they need to be added to the installation data into the MachineRegistration resource. More specific the config-urls field is used for this exact purpose. See MachineRegistration reference page.

config-urls is a list of string literals where each item is an HTTP URL or a local path pointing to a cloud-init file. The local path is evaluated during the installation, hence it must exists within the installation media, commonly an ISO image.

By default, Elemental Teal live systems mount the ISO root at /run/initramfs/live and this should be the path set for config-url in MachineRegistrations: See the example below:

apiVersion: elemental.cattle.io/v1beta1
kind: MachineRegistration
metadata:
  name: my-nodes
  namespace: fleet-default
spec:
  ...
  config:
    ...
    elemental:
      ...
      install:
        ...
        config-urls:
        - "/run/initramfs/live/oem/custom_config.yaml"

Elemental Teal live ISOs, when booted, have the ISO root mounted at /run/initramfs/live. According to that, the example above is expected to include the /oem/custom_config.yaml file.

Adding installation hooks or boot stages for the live system

Elemental client install, upgrade and reset procedures include four different hooks:

before-install: executed after all partition mountpoints are set.
after-install-chroot: executed after deploying the OS image and before unmounting the associated loop filesystem image. Runs chrooted to the OS image.
after-install: executed just after the after-install-chroot hook. It is not chrooted.
post-install: executed as the very last step before ending the installation, partitions are still mounted, the loop devices for the image is not.

Hooks are provided as cloud-init stages. Equivalent hooks exist for reset and upgrade procedures. They are loaded from the /iso-config folder in ISO filesystem root. In fact, hooks are regular cloud-init stages with the only difference that Elemental client parses them during install, upgrade or reset actions, rather than boot time. Note any boot stage included this way will be executed during the live installation media boot.

Hooks are evaluated during install,reset and upgrade action from /oem, /system/oem and /usr/local/cloud-config paths, however for the live ISOs there is an additional the path /run/initramfs/live/iso-config included. Note the /run/initramfs/live prefix is the mount point of the ISO filesystem of the Elemental Live ISO once booted.

Adding extra driver binaries into the ISO example

This example is covering the case in which extra driver binaries are included into the ISO and during the installation they are installed over the OS image.

For that use case the following files are required:

additional binaries to install (they could be in the form of RPMs)
additional hooks file to copy binaries into the persistent storage and to install them

Let's create an overlay directory to create the directory tree that needs to be added into the ISO root. In that case the overlay directory could contain:

overlay/
  data/
    extra_drivers/
      some_driver.rpm
  iso-config/
    install_hooks.yaml

The overlay/iso-config/install_hooks.yaml could be as:

name: "Install extra drivers"
stages:
  before-install:
    # Preload data to the persistent storage
    # During installation persistent partition is mounted at /run/cos/persistent
    - commands:
        - rsync -a /run/initramfs/live/data/ /run/cos/persistent
  after-install-chroot:
    # extra_drivers folder is at `/usr/local/extra_drivers` from the OS image chroot
    - commands:
      - rpm -iv /usr/local/extra_drivers/some_driver.rpm

Note the installation hooks only cover installation procedures, for upgrades equivalent before-upgrade and/or after-upgrade-chroot should be defined.

Adding extra LVM volume group disks during the installation

This example is covering the setup of an host with multiple disks and some of them used as part of an LVM setup.

As an example, we have an host with three disks (/dev/sda, /dev/sdb and /dev/sdc).

The first disk is used for a regular Elemental Teal installation and the other remaining two are used as part of a LVM group where arbitrary logical volumes are created, formatted and mounted at boot time via an extended fstab file.

For this example, the following files are required:

additional clout-init files included in the installed system
additional installation hooks to prepare the LVM volumes during the installation

Let's create an overlay directory to create the directory tree that needs to be added into the ISO root. In that case the overlay directory could contain:

overlay/
  oem/
    lvm_volumes_in_fstab.yaml
  iso-config/
    lvm_volumes_hook.yaml

The installation hook overlay/iso-config/lvm_volumes_hook.yaml:

name: "Create LVM logic volumes over some physical disks"
stages:
  post-install:
    - name: "Create physical volume, volume group and logical volumes"
      if: '[ -e "/dev/sdb" ] && [ -e "/dev/sdc" ]'
      commands:
      - | 
        # Create the physical volume, volume group and logical volumes
        pvcreate /dev/sdb /dev/sdc
        vgcreate elementalLVM /dev/sdb /dev/sdc
        lvcreate -L 8G -n elementalVol1 elementalLVM
        lvcreate -l 100%FREE -n elementalVol2 elementalLVM

        # Trigger udev detection
        if [ ! -e "/dev/elementalLVM/elementalVol1" ] || [ ! -e "/dev/elementalLVM/elementalVol2" ]; then
          sleep 10
          udevadm settle
        fi

        # Ensure devices are already available
        [ -e "/dev/elementalLVM/elementalVol1" ] || exit 1
        [ -e "/dev/elementalLVM/elementalVol2" ] || exit 1

        # Format logical volumes with a known label for later use in fstab
        mkfs.xfs -L eVol1 /dev/elementalLVM/elementalVol1
        mkfs.xfs -L eVol2 /dev/elementalLVM/elementalVol2

The LVM devices are created and formatted as desired. This is a good example of an installation hook, as this setup is only needed once, at installation time. As an alternative, the same action could be done on first boot, however it would require a more sophisticated logic to ensure it's only applied once at first boot.

Finally, the boot time cloud-init files contain the mount points settings and trigger the action of mounting those mountpoints. The Elemental OS fstab file is ephemeral and it's dynamically created at boot time. That's why it doesn't exist during the installation and can't be used in an installation hook.

Here's an example of overlay/oem/lvm_volumes_in_fstab.yaml:

name: "Mount LVM volumes"
stages:
  initramfs:
    - name: "Extend fstab to mount LVM logical volumes at boot"
      commands:
      - |
        echo "LABEL=eVol1 /usr/local/eVol1  xfs defaults  0 0" >> /etc/fstab
        echo "LABEL=eVol2 /usr/local/eVol2  xfs defaults  0 0" >> /etc/fstab

note

The initramfs stage is the last stage before switching to the actual root tree. At this stage, the /etc/fstab file already exists and can be adapted before switching root. Once running in the final root tree, SystemD will handle the rest of the initialization and apply it.

This cloud-init file should be included into the /oem directory on the installed system. /oem is a mount point for the OEM partition. In order to include extra files, they should be listed as config-urls within the Registration CRD at the management cluster.

Repacking the ISO image with extra files

Assuming an overlay folder was created in the current directory containing all additional files to be appended, the following xorriso command adds the extra files:

xorriso -indev elemental-teal.x86_64.iso -outdev elemental-teal.custom.x86_64.iso -map overlay / -boot_image any replay

For that a xorriso equal or higher than version 1.5 is required.

Remastering a custom docker image

Since Elemental Teal image is a Docker image it can also be used as a base image in a Dockerfile in order to create a new container image.

Imagine some additional package from an extra repository is required, the following example show case how this could be added:

# The version of Elemental to modify
FROM registry.suse.com/rancher/elemental-teal/5.3:latest

# Custom commands
RUN rpm --import <repo-signing-key-url> && \
    zypper addrepo --refresh <repo_url> extra_repo && \
    zypper install -y <extra_package>

# IMPORTANT: /etc/os-release is used for versioning/upgrade. The
# values here should reflect the tag of the image currently being built
ARG IMAGE_REPO=norepo
ARG IMAGE_TAG=latest
RUN \
    sed -i -e "s/^IMAGE_REPO=.*/IMAGE_REPO=\"${IMAGE_REPO}\"/g" /etc/os-release && \
    sed -i -e "s/^IMAGE_TAG=.*/IMAGE_TAG=\"${IMAGE_TAG}\"/g" /etc/os-release && \
    sed -i -e "s/^IMAGE=.*/IMAGE=\"${IMAGE_REPO}:${IMAGE_TAG}\"/g" /etc/os-release

Where latest is the base version we want to customize.

And then the following commands

docker build --build-arg IMAGE_REPO=myrepo/custom-build \
             --build-arg IMAGE_TAG=v1.1.1 \
             -t myrepo/custom-build:v1.1.1 .
docker push myrepo/custom-build:v1.1.1

The new customized OS is available as the Docker image myrepo/custom-build:v1.1.1 and it can be run and verified using docker with

docker run -it myrepo/custom-build:v1.1.1 bash

Create a custom bootable installation media

Elemental Teal leverages container images to build its root filesystems; therefore, it is possible to use it in a multi-stage environment to create custom bootable media that bundles a custom container image.

FROM registry.suse.com/rancher/elemental-teal/5.3:latest as os

# Check the section on remastering a custom docker image

FROM registry.suse.com/rancher/elemental-builder-image/5.3:latest AS builder

ARG TARGETARCH
WORKDIR /iso
COPY --from=os / rootfs

# work around buildah issue: https://github.com/containers/buildah/issues/4242
RUN rm rootfs/etc/resolv.conf

RUN --mount=type=bind,source=./,target=/output,rw \
      elemental build-iso \
        dir:rootfs \
        --bootloader-in-rootfs \
        --squash-no-compression \
        -o /output -n "elemental-teal-${TARGETARCH}"

Modify the container image template and afterwards run:

buildah build --tag myrepo/custom-build:v1.1.1 \
              --build-arg IMAGE_REPO=myrepo/custom-build \
              --build-arg IMAGE_TAG=v1.1.1 \
              .

The new customized installation media can be found in elemental-teal-amd64.iso.

important

You still need to prepare the installation image so it can be used to boot and provision the machine.

Customize installation ISO and installation process​

Common customization pattern​

Custom Elemental client configuration file​

Adding additional cloud-init files within the installed OS​

Adding installation hooks or boot stages for the live system​

Adding extra driver binaries into the ISO example​

Adding extra LVM volume group disks during the installation​

Repacking the ISO image with extra files​

Remastering a custom docker image​

Create a custom bootable installation media​