Using Kickstart

The Node Images and Boot Configurations section discusses the creation and modification of compute node images and how to add locally installed nodes to the system. ClusterWare provides support for an additional method of dynamically provisioning compute nodes: Kickstart.

Create Local Repo

ISO images of the installation DVDs for RHEL-family (see Supported Distributions and Features) systems can be downloaded from their respective websites and imported into ClusterWare as repos using the scyld-clusterctl repos command. For example:

scyld-clusterctl repos create name=Rocky8repo iso=@Rocky-8.7-x86_64-dvd1.iso

Once the upload completes, the ISO will be automatically forwarded to all head nodes and will be locally mounted on each. Below are the repository details immediately after the upload completes:

[cwadmin@virthead]$ scyld-clusterctl repos -i Rocky8repo ls -l
Repos
  Rocky8repo
    iso
      chksum: e47d5ca236a3152d63814b32081a1a3261dd1cf4
      filename: 4aceb9db1aef4670be82bf49855b514a
      mtime: 2023-01-31 23:07:36 UTC (0:08:31 ago)
      size: 11.3 GiB (12129927168 bytes)
    isolabel: Rocky-8-7-x86_64-dvd
    keys: []
    name: Rocky8repo
    urls
      <BASE_URL>/isomount/Rocky8repo/BaseOS/
      <BASE_URL>/isomount/Rocky8repo/AppStream/

ClusterWare will display URLs for the repositories identified on the ISO. For example, there is a repository in the root of the uploaded Rocky-8 ISO, accessible at <BASE_URL>/isomount/Rocky8repo/BaseOS/. The <BASE_URL> tag is used as a placeholder to signify that any head node can provide access. When using such a URL, replace the <BASE_URL> with the actual head node's base URL, e.g., http://10.20.30.30/api/v1/isomount/Rocky8repo/BaseOS/<target-file>

The ISO can also be downloaded using the scyld-clusterctl command:

scyld-clusterctl repos -i Rocky8repo download iso

Just like URL defined repos, repos created using ISOs can be referenced in distros. See Creating PXEboot Images in Node Images and Boot Configurations in this guide for details about using repos and distros to create compute node images.

Create Boot Configuration

In addition to providing content for distros, repos based on RHEL-family ISO images can also be used to kickstart locally installed compute nodes. To prepare a kickstart configuration, create a boot configuration that references the repo directly:

scyld-bootctl create name=Rocky8boot repo=Rocky8repo kickstart=basic.ks

The resulting boot configuration will automatically locate the kernel and initramfs on the ISO and default to using no image:

[cwadmin@virthead]$ scyld-bootctl -i Rocky8boot ls -l
Boot Configurations
  Rocky8boot
    image: none
    initramfs: repo:images/pxeboot/initrd.img
    kernel: repo:images/pxeboot/vmlinuz
    kickstart: basic.ks
    last_modified: 2023-01-31 23:27:08 UTC (0:00:13 ago)
    name: Rocky8boot
    release: 4.18.0-425.3.1.el8.x86_64
    repo: Rocky8repo

Initially this boot configuration can be used to boot a disked node with the live boot style assigned either by the boot configuration boot_style field or a _boot_style node attribute. When live booting a node, the cluster administrator will need to access the node's console to proceed through the operating system installation steps. To use the serial-over-lan BMC feature, the administrator may need to provide an appropriate console= cmdline, e.g.:

scyld-bootctl -i Rocky8boot update cmdline=console=ttyS0,115200

The specific details of the console and other command line arguments depend on the target hardware and are beyond the scope of this document. Once the installation process is complete, the compute node should use a next boot style in order to skip the PXE boot process and instead boot from the next boot device. Cluster administrators are encouraged to configure the BIOS of locally installed compute nodes to attempt PXE boot first and then boot from the local disk so that the next boot style works as intended.

Kickstart Files

A kickstart file configures how a kickstarted node is initialized at boot time. The files are stored on the head node in the /opt/scyld/clusterware/kickstarts/ folder. In a multihead configuration this folder must currently be manually synced between head nodes. These kickstart files typically contain a limited set of variables that will be substituted at download time.

For example, the ClusterWare package includes the basic.ks kickstart file that begins with the following contents:

# Node fields, attributes, status, and hardware are available in
#   dictionaries referenced by name or initial. Some examples:
#
# <node[ip]>
# <a[_boot_config]>
# <hardware[mac]>

# Perform a SOL friendly text-based install.
text

# Pull some basics from the head node.
url --url <root_url()>
lang <head[lang]>
keyboard <head[keymap]>
timezone <head[timezone]>

Two different types of tags are supported, and both provide simple text substitution. The first, exemplified by the <repo_url()> tag, is a function call that accepts as an optional argument the name of a ClusterWare repo. That tag will be replaced by an appropriate URL for the named repo. Similarly, certain values are represented as more of a dictionary-like reference, e.g., <head[timezone]>. These tags provide a simple variable lookup for information such as the head node timezone. The snippet above shows all the currently supported tags except for the <include(partial.ks)> tag. The include tag allows a cluster administrator to break the kickstart files into manageable hunks that can then be included into a top-level kickstart file, much like a C or C++ "#include <filename>".

The simple basic.ks performs a boot time install of both the base distribution core packages (e.g., from Rocky8repo) and the associated ClusterWare clusterware-node package which is appropriate for that particular base distribution.

Associate the boot configuration with a kickstart file:

scyld-bootctl -i Rocky8boot update kickstart=basic.ks

and associate a compute node to boot this boot configuration:

scyld-nodectl -i n0 set _boot_config=Rocky8boot

Finally, reboot node n0 to initiate the kickstart, which will take a few minutes to complete.

Once the freshly installed node has booted, there will be a /root/anaconda-ks.cfg file that can be used as a starting point for creating a more generalized kickstart file. If the cluster administrator would like to reinstall the node the exact same way, the simplest thing to do is copy that anaconda-ks.cfg file to the head node's kickstart directory and assign it to be used in the boot configuration:

# Copy the compute node's /root/anaconda-ks.cfg to the head node,
#  and then copy to the head node's kickstart files folder.
cp anaconda-ks.cfg /opt/scyld/clusterware/kickstarts
# And update the boot configuration to use the file.
scyld-bootctl -i Rocky8boot update kickstart=anaconda-ks.cfg

After that file is in place, any compute node booted from that boot configuration without the next or live boot style will boot using the kernel and initramfs from the ISO, and a URL to the kickstart file will be added to the kernel command line. Keep in mind that once a node starts the kickstart process, it is a good idea to change its boot style to next so that it does not reboot at the end of the install process and immediately reinstall. Configuring the kickstart process to end with a shutdown command (see your operating system documentation) is the current best practice.

If a cluster administrator wants to use a different kernel and/or initramfs for kickstarting instead of the ones found on the ISO, those can be replaced just like in any other boot configuration through the update action. Updating them with an empty string will reset them back to the detected paths:

scyld-bootctl -i Rocky8boot update kernel= initramfs=