Boot Config Objects

A Boot Config object represents a set of information used to boot up a node from power-on to a running OS image on the node. It may include specific command-line parameters for the booting node, a “boot style” (for example, ram-based image or disked image), kickstart files, etc.

When issuing requests, the UID field in the URL can be either the actual UID of the object or the name of the object as given in the “name” field.

Data Fields

The Attribute Group fields are:

name
     Required: The name for the Boot Config

kernel
     Required: This is the kernel (file) being used by the Boot Config; note that since
     this requires a large file to be uploaded, the standard POST/PATCH endpoints will
     not work to update the kernel - additional endpoints are provided for handling
     these files

initramfs
     Required: This is the initramfs (file) being used during the early boot phases;
     note that since this requires a large file to be uploaded, the standard POST/PATCH
     endpoints will not work to update the initramfs - additional endpoints are provided
     for handling these filesdescription

     Optional: A text string with descriptive information

frozen
     Optional: A True/False indicator that allows admins to block changes to the boot
               config; note that is intended as a protection against accidents, not
               against malicious attacks, since one can simply set frozen=False and
               then make changes.

cmdline
     Optional: Command-line to be used when booting the operating system; this may
               include options for SELinux enforcement or power-control

image
     Optional: A UID or name for a ClusterWare Image object (see below); note that
               ClusterWare stores this as a UID, but will accept a UID or name when
               creating or updating the Boot Config

boot_style
     Optional: A string representation of the type of boot-up process being used, one
               of: ('rwram','roram','iscsi','next','disked','sanboot','live'); the
               default is “rwram” and indicates a node that will be booted into a
               ram-based image that readable and writable

repo
     Optional

kickstart
     Optional: Indicates the kickstart file to be used for disk-based installations
               that are using Kickstart; this should be a file that has been copied
               or created in the /opt/scyld/clusterware/kickstarts directory.

Additional Endpoints

Additional object-class endpoints are available:

GET /bootconfigs/errors
     Will check all Boot Config entries that they have valid data, that any referenced
     images or files are present, etc.; returns a JSON object with a “success” field;
     if an error occurs, a “reason” field will give more information on why it failed

GET /bootconfigs/mkiso
     Accepts a JSON object with “uid” and “image” keys, and will create and download a
     bootable ISO image. This is an advanced feature, please contact Penguin Solutions
     for more information.

As mentioned earlier, the kernel and initramfs may be large files and thus must be uploaded separately – they cannot be “updated” with the standard POST/PATCH actions. To interact with these files, use the following endpoints:

GET /bootconfig/<UID>/kernel
     Returns a file containing the kernel being used by this Boot Config. Note that
     the output format is different from other ClusterWare commands – there are no
     “success” or “data” keys, just the binary data of the file being requested.

PUT /bootconfig/<UID>/kernel
     Replaces the current kernel file with the uploaded file

DELETE /bootconfig/<UID>/kernel
     Deletes the kernel file associated with this Boot Config; in multi-head
     configurations, the file will be deleted from all heads automatically

GET /bootconfig/<UID>/initramfs
     Returns a file containing the initramfs being used by this Boot Config. Note that
     the output format is different from other ClusterWare commands – there are no
     “success” or “data” keys, just the binary data of the file being requested

PUT /bootconfig/<UID>/initramfs
     Replaces the current initramfs file with the uploaded file

DELETE /bootconfig/<UID>/initramfs
     Deletes the initramfs file associated with this Boot Config; in multi-head
     configurations, the file will be deleted from all head nodes automatically

For kickstart-based deployments, the kickstart file can be a template that uses “<variable>” syntax to substitute values from the node. To retrieve the parsed and substituted kickstart file, use the following endpoint. Unlike kernel and initramfs files, kickstart files are NOT automatically synchronized across head nodes – admins must manually copy the file from one head node to the others.

GET /bootconfig/<UID>/kickstart
     Returns the parsed and substituted kickstart file; the output format is
     different from other ClusterWare commands – there are no “success” or “data”
     keys, just the (text) data of the file being requested.

Since Boot Configs are critical to the operation of the cluster, an endpoint can be used to check that the required data is available and valid. For example, to check that the image file being used is actually present:

GET /bootconfig/<UID>/errors
     Checks that entries in the boot config are valid and return a JSON object
     with a “success” field; if an error occurs, a “reason” field will give more
     information on why it failed

An endpoint is provided to export a Boot Config for backup or sharing:

GET /bootconfig/<UID>/export
     This is an advanced feature, please contact Penguin Solutions for more
     information

Example

Create a new Boot Config, using an existing DefaultImage as the base image:

curl -X POST https://head1.cluster.local/api/v1/bootconfigs --data \
    '{"name":"NewBoot","image":"DefaultImage"}' -H \
    "Authorization: Bearer eyJhbGciOiJIUzI1Ni…"
{"success": true, "data": "ed31013d670745139681c46cf657ed40"}

Note that the image can be referenced by UID or, as shown here, by name. Verify the data:

curl -X GET https://head1.cluster.local/api/v1/bootconfig/NewBoot -H \
    "Authorization: Bearer eyJhbGciOiJIUzI1Ni…"
{"success": true, "data": {"name": "NewBoot", "image": "DefaultImage", \
    "last_modified": \1721921837.5399132, "last_modified_on": "head23.cluster.local", \
    "last_modified_by": "admin1", "uid": "ed31013d670745139681c46cf657ed40"}}

Set it to be "frozen" so that future changes cannot be made:

curl -X PATCH https://head1.cluster.local/api/v1/bootconfig/NewBoot --data \
    '{"frozen":true}' -H "Authorization: Bearer eyJhbGciOiJIUzI1Ni…"
{"success": true}

Now that it is frozen, attempt to modify the "description" field:

curl -X PATCH https://head1.cluster.local/api/v1/bootconfig/NewBoot --data
    '{"description":"new description"}' -H "Authorization: Bearer eyJhbGciOiJIUzI1Ni…"
{"success": false, "reason": "Cannot modify frozen boot configuration."}

This Boot Config does not yet have a kernel or initramfs and thus would not be able to actually boot any nodes yet. Using the existing DefaultBoot (created during installation), download its kernel and initramfs:

curl -X GET https://head1.cluster.local/api/v1/bootconfig/DefaultBoot/kernel -o \
    defaultboot_kernel -H "Authorization: Bearer eyJhbGciOiJIUzI1Ni…"

curl -X GET https://head1.cluster.local/api/v1/bootconfig/DefaultBoot/initramfs -o \
    defaultboot_initramfs -H "Authorization: Bearer eyJhbGciOiJIUzI1Ni…"