Image Objects

An Image object represents a file system that will be deployed onto a compute node. It is not intended to have absolutely all software that an end-user might want, but rather, a somewhat minimal set of drivers, configuration files, tools, and middleware to bring up the node. Network-mounted file systems may be used to provide additional software and libraries for end-users.

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 image

content
     Required: This is the content of the file system that will be used in this Image;
               since this requires a large file to be uploaded, the standard
               POST/PATCH endpoints will not work to update the content - additional
               endpoints are provided for handling it below

description
     Optional: A text string with descriptive information

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

parent
     Optional: A UID or name of a “parent” Image object that the current object was
               derived from; this field is for informational purposes only and is not
               used during any actions (for example, changes to a parent Image are not
               propagated into its children); ClusterWare stores this as a
               UID, but will accept a UID or name when creating or updating the Image

distro
     Optional: A UID of a distro (a Software Distribution object)

Additional Endpoints

As mentioned earlier, the content of an Image is a large file and thus must be uploaded separately – it cannot be “updated” with the standard POST/PATCH actions. To interact with the content file, use the following endpoints:

GET /image/<UID>/content
     Returns a file containing the file system image being used by this Image object.
     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 /image/<UID>/content
     Replaces the current content file with the uploaded file

DELETE /image/<UID>/content
     Deletes the content file associated with this Image; in multi-head configurations,
     the file will be deleted from all heads automatically

GET /image/<UID>/content/stat
     Returns a JSON object containing statistics on the image: the file’s size (“size”)
     and last modification time (“mtime”)

GET /image/<UID>/content/info
     Returns a JSON object containing more detailed statistics on the image: the file’s
     size (“size”), last modification time (“mtime”), checksum ("chksum"), a reference
     count (“refcnt”), and the file format (“fmt”, currently “cwsquash”)

There is one additional endpoint that is used when capturing an image from a running compute node. This is an advanced feature; please contact Penguin Solutions for more information.

GET /image/{uid}/capture
     Accepts a JSON object with “uid” key (required), and one or more optional keys:
     “exclude”, “credentials”, “compress”.

Example

Create an empty image:

curl -X POST https://head1.cluster.local/api/v1/images --data '{"name":"NewImage"}' \
    -H "Authorization: Bearer eyJhbGciOiJIUzI1Ni…"
{"success": true, "data": "d16d9eb8786c408ba32780ee6b722a50"}

Look at an existing Image (DefaultImage will be created at installation):

curl -X GET https://head1.cluster.local/api/v1/image/DefaultImage -H \
    "Authorization: Bearer eyJhbGciOiJIUzI1Ni…"
{"success": true, "data": {"name": "DefaultImage", "distro": "CentOS", "parent": null, \
    "description": "Default image generated by scyld-add-boot-config", "exports": \
    {"head23.cluster.local": {"targetcli": {"category": "iscsi", "location": \
    "iqn.1998-04.com.penguincomputing:cb2eeba6fe3748febbb15c7cc1cfb165"}, \
    "last_modified": 1721928167.775344, "last_modified_on": "head23.cluster.local"}}, \
    "content": {"cwsquash": {"size": 1222410240, "mtime": 1721919588.6732733, \
    "chksum": "sha1:7e24ac56d109394755302377c9226fa111aae45d", "filename": \
    "486c1857bd214d3fad56dea1399b6440", "uid": "486c1857bd214d3fad56dea1399b6440"}, \
    "last_modified": 1721919589.1442792, "last_modified_on": "head23.cluster.local", \
    "last_modified_by": "admin1"}, "last_modified": 1721919581.66072, \
    "last_modified_on": "head23.cluster.local", "last_modified_by": "admin1", \
    "uid": "cb2eeba6fe3748febbb15c7cc1cfb165"}}

Look into the details statistics for the image:

curl -X GET https://head1.cluster.local/api/v1/image/DefaultImage/content/info \
    -H "Authorization: Bearer eyJhbGciOiJIUzI1Ni…"
{"success": true, "data": {"size": 1222410240, "mtime": 1721919588.6732733, "chksum": \
    "sha1:7e24ac56d109394755302377c9226fa111aae45d", "refcnt": 1, "fmt": "cwsquash"}}