Appendix: Deploying Images Using Ignition

To partition nodes during their boot process, ClusterWare leverages tools called Ignition and Butane. Both originate from the Red Hat CoreOS project, but are generally applicable for “first boot” actions such as provisioning local storage. The Ignition tool accepts a machine parsable JSON formatted configuration file while the Butane tool translates a human readable YAML format and produces the JSON file that ignition needs. Details of these projects can be found at:

Butane: https://coreos.github.io/butane/ Ignition: https://coreos.github.io/ignition/

The functionality provided by Ignition enables ClusterWare to partition and format local disks and deploy a root file system image to the newly prepared drives. This bypasses the previously used kickstart process to deploy locally-installed systems. The behavior of Ignition is controlled through a configuration file and node attributes. Another attribute triggers the installation of the GRUB2 bootloader, resulting in a fully provisioned and ready-to-boot system. By default these systems still use ClusterWare for DHCP and report status back to the head nodes, but post-install changes can reconfigure the networking or disable the ClusterWare and Telegraf agents.

To utilize Ignition during provisioning, create an image that contains the desired operating system and software tools. Note that older ClusterWare images may not contain all the tools, such as sgdisk or mkfs.xfs, necessary for Ignition to properly partition or format the drives. Ignition is also relatively new and may rely on versions of tools that are not available on older operating systems such as CentOS or RHEL 7.

Once the image exists, create a boot configuration using the image:

scyld-add-boot-config --image <IMAGENAME> --boot-config <BOOTNAME>

Several node attributes must also be set on the target node:

Attribute

Example

Notes

_boot_config

DeployBoot

Name of the boot configuration to deploy

_boot_style

disked

Must be "disked"

_disk_root

LABEL=root

Reference to the new root partition / file system

_ignition

config.butane

Name of the Butane configuration file ending in .butane

_bootloader

grub

Must be "grub"

Once these attributes are set, reboot the node. The node will boot using the kernel and initramfs from the specified boot configuration, and within the initramfs the system will execute the various Ignition stages during the normal image download and unpacking process as follows:

  • After networking is established and the node has downloaded its initial attributes.ini file, it will detect the _ignition attribute and download the ignition binary from the head node.

  • After downloading the root file system, the node will run the “fetch”, “kargs”, and “disks” stages to download the configuration, check the kernel arguments, and partition local disks.

  • Immediately before unpacking the file system, the node will run the “mount” stage and then proceed to unpack the image into the mounted partitions.

  • After unpacking the image, the node will run the “files” stage to manipulate the unpacked file system.

Once Ignition completes, the _bootloader attribute will trigger installation of the GRUB2 bootloader as a separate step. A successful installation of grub will also update _boot_style to ensure nodes do not continually loop through deployment. Finally, a reboot and relabel of the file system is triggered.

The Butane configuration needs to be copied to the /opt/scyld/clusterware/kickstarts directory on all head nodes. As long as the file name ends with “.butane” the file will be translated by the Butane command at download time. A file with any other extension must be a valid Ignition configuration file, as it will be passed directly to the Ignition command without translation.

Examples of Butane configuration files can be found in the Butane project documentation:

https://coreos.github.io/butane/examples/

The clusterware-tools package also includes a very simple Ignition example file at /opt/scyld/clusterware-tools/examples/partitions.butane. That example file will partition the local drive (/dev/vda on a VM) into two partitions, / and /boot where /boot is 1024 MB in size and / encompasses the rest of the drive.

Ignition provides functionality beyond simple disk partitioning and file system creation, including software RAID or LUKS configuration, and the creation of systemd unit files. However, these features are considered experimental within the ClusterWare system. Additional functionality will be confirmed in future releases.

An ignition.log file is produced during the deployment process and can be found in /opt/scyld/clusterware-node/atboot on the booted node. In the case of errors the node will likely not be able to boot. In that case, a cluster administrator can log into the initramfs shell during the 20 second “press any key” countdown and examine the log file located at /atboot/ignition.log.

One substantial difference between using Ignition directly and using it via ClusterWare is that Ignition is intended to either produce exactly the desired result or nothing at all. However, when triggered by the _ignition attribute, the tool will log failures and proceed. Future releases may change this behavior to more closely match the standard Ignition approach.