Kit Builders Guide
A step by step guide to developing prepackaged software kits
for IBM Platform Cluster Manager, IBM Platform HPC,
and Kusu clusters
Date: August 2013
Table of Contents
Table of Contents ..............................................................................................................................2
About Platform Cluster Manager Kits ..............................................................................................3
Kits from a Cluster Administrator’s Perspective.......................................................................4
A Look inside Kits ....................................................................................................................7
Building Kits .....................................................................................................................................8
Using kusu-buildkit to Create a Simple Kit ..............................................................................9
A real example – Building an NCBI BLAST kit.............................................................................11
Defining the Kit Properties in build.kit...................................................................................15
Building the NIBC BLAST Kit ISO file .................................................................................20
Verifying the Kit ISO File .......................................................................................................22
Writing your ISO image to a CD or DVD...............................................................................23
Testing the BLAST Kit ...........................................................................................................24
Provisioning the new BLAST Kit ...................................................................................................27
The Kit Build Process in More Detail.............................................................................................28
Kit documentation...................................................................................................................28
Kit Properties ..........................................................................................................................29
Kit Plugins ..............................................................................................................................29
Kit Post-installation Scripts.....................................................................................................32
Kit Components ......................................................................................................................32
About Software Packages .......................................................................................................34
Querying the PCM Database...........................................................................................................36
Summary .........................................................................................................................................39
Notices ............................................................................................................................................40
Trademarks..............................................................................................................................42
Contacting IBM........................................................................................................................43
IBM Platform Cluster Manager Kit Builder’s Guide
Page 2
About Platform Cluster Manager Kits
Kits can be thought of as “smart software packages”. Kits are the unit of software distribution for
IBM Platform Cluster Manager (PCM) and other cluster managers built on the open source Project
Kusu. Kits are typically provided on CD or DVD media, or as ISO images. They consist of
components containing the required software packages. Kits may also contain plugins for key
Kusu tools, documentation, and scripts that can intelligently install and uninstall the kits
themselves, or components contained in kits. Kits also contain metadata describing the kit and its
associated components.
From a cluster administrator’s perspective, some advantages of kits are:




They provide a high-level way of packaging complex software
They dramatically simplify the installation, removal, and configuration of software
They reduce the opportunity for error, making environments more reliable
They understand their own dependencies; Kits can depend on other kits, or on specific
RPMs

Through the use of plugins, Kits can be made “smart”, allowing software to reconfigure
itself automatically as the topology of the cluster changes.
From the perspective of software developers and ISVs, kits also have several advantages:



They simplify the deployment of software
They reduce end-user support requirements
They allow software developers to intelligently direct the types of nodes that components
should be installed on

They allow developers to build in dependencies on operating system versions and
components

They simplify QA and testing activities
This document focuses on kits from the software developer’s perspective. It assumes a basic
knowledge of how Platform Cluster Manager works, and a reasonable understanding of concepts
like repositories, node groups and components. Throughout the document, there are references to
Kusu, which is the open-source cluster management solution on which PCM is based.
To follow the examples in this guide, you should have access to a PCM installer node either
running standalone or in a virtual machine. You can follow these examples and build kits using
either PCM or the open source Kusu software available from http://hpccommunity.org . You
should also have some knowledge of how RPMs are structured to build kits, and if you are
planning to build your own kit, you should have access to the RPMs, tar files, or source code that
you want to include in your kit.
IBM Platform Cluster Manager Kit Builder’s Guide
Page 3
Kits from a Cluster Administrator’s Perspective
For a cluster administrator, kits just make things simple. For most PCM administrators, the
process of adding kits is entirely managed through the PCM Web interface as shown in Figure 1.
To add a software kit, a select a directory or ISO file visible to the installer node via the web
interface, and click Add. PCM looks after the rest.
Figure 1: Managing kits through the PCM Web interface
IBM Platform Cluster Manager Kit Builder’s Guide
Page 4
For example, in order to deploy Platform-hpc (an open-source tool) onto a particular type of
compute node (in this example,a Red Hat Linux 5.5 compute host) the administrator associates the
required Platform-hpc component with the desired node group through the Web interface .
This is illustrated in Figure 2.
Figure 2- Associating components with Node Groups
PCM looks after everything else. A well designed kit can even preconfigure Platform-hpc so
that it is immediately ready to use on the cluster and using plug-ins (covered later in this
document). The kit can adjust its own configuration automatically when changes are made to the
cluster.
IBM Platform Cluster Manager Kit Builder’s Guide
Page 5
Behind the scenes, kits are managed using the Kusu kit management tool kusu-kitops. The
kusu-kitops command allows users to add kits, remove or list kits.
Figure 3 - kusu-kitops - the Kit Management Tool
On the PCM installer node, kits reside in the directory /depot/kits once they are installed.
There is a directory for each kit, and subdirectories for each kit version and architecture.
For example, the path on disk to the files that comprise the OFED kit is:
/depot/kits/9/
9 is the OFED kit ID.
PCM employs a central PostgreSQL database1 to store information about the cluster including
information about various cluster nodes, node group definitions, and kits. The kusu-kitops
command does more than just manipulate files on disk – it also updates the SQL database so that
PCM maintains a central view of the various software kits available, repositories they are
associated with, and the types of compute hosts (node groups) on which the software components
contained in kits are to be installed.
1
Versions prior to OCS 5.3 / PCM 1.2 used a MySQL database
IBM Platform Cluster Manager Kit Builder’s Guide
Page 6
A Look inside Kits
Kits are collections of files provided in a particular format. It is instructive to look at the PCM
media itself to see how kits are packaged since PCM contains multiple kits. After mounting the
PCM installation DVD on a Linux system, the component files in one of the provided kits can be
examined. For example, Figure 4 shows the contents of the kit pcm:
Figure 4 - Files that comprise the PCM kit
The kit package has the naming format
kit-{kit_name}-{kit_version}-{kit_release}.{kit_arch}.rpm
and component packages follow the naming convention
component-{component_name}-{component_version}-{component_release}.
{component_arch}.rpm.
In the PCM kit above, there is one RPM for the kit itself, and there are two components; a pcm
base-node component and installer component. Additionally, there are RPMs that contain the
actual PCM software.
Use the Linux RPM utility (with the -qpl options) to look at the contents of the RPMs that the
kit contains.
ISF-AC is a more sophisticated kit. Figure 5 shows an example of the contents of the kit RPM.
The kit RPM contains documentation about ISF-AC designed to be accessible through a web
browser. It also contains plugin scripts (written in python) for the ISF-AC addhost utility which
enables the ISF-AC configuration files to be updated and ISF-AC related services restarted
automatically when a host is added or node characteristics are changed.
IBM Platform Cluster Manager Kit Builder’s Guide
Page 7
Figure 5 - Viewing the contents of the ISF-AC kit RPM
Use rpm –qpl kit_name.rpm to look through the other RPMs. The component files
themselves will be empty since they will depend on other packages. The contents of other
packages can also be inspected using RPM as shown above.
Building Kits
For building simple kits, the kusu-buildkit is included with PCM. The kusu-buildkit
tool simplified creating RPMs and the overall process of building kits.
For more complex kit, kusu-buildkit may not be sufficient. It is also possible to build kits
without the tool.
IBM Platform Cluster Manager Kit Builder’s Guide
Page 8
Using kusu-buildkit to Create a Simple Kit
The kusu-buildkit utility included in the PCM distribution is located in /opt/kusu/bin.
Like other PCM utilities, the tool itself is written in Python, a popular high-level language that can
be interpreted or compiled.
1. To build the skeleton of a new kit, run kusu-buildkit as shown below. This example
builds a kit called mytestkit
Figure 6 - An example of creating a kit directory structure
2. After running kusu-buildkit, use the tree command to see that the template directory
structure for the kit has been created.
Figure 7- Using the "tree" command to show the directory structure
The artifacts directory will contain packages and other files generated by kusu-buildkit
when the kit is actually built. Any documentation to be installed with the main kit package should
go into the docs directory. Documentation placed here will automatically become visible through
a Web browser pointed at the installer node when a kit is installed.
IBM Platform Cluster Manager Kit Builder’s Guide
Page 9
If you’ve written any plugins for PCM applications (addhost, genconfig or ngedit), you
need to put these plugins into the plugins directory. The sources directory contains any
packages or source code to be included. The tmp directory is used internally by the
kusu-buildkit facility.
3. Validate that kusu-buildkit is working properly by making a new kit (in the form of a
ready to install ISO file) from the skeleton kit above. The kusu-buildkit utility won’t
care that this kit doesn’t actually do anything. The process of creating the ISO file from the kit
is shown in Figure 8.
Figure 8 - Creating an ISO file using kusu-buildkit
4. Run kusu-buildkit with the make argument to get the ISO file shown above. This ISO
file is a kit that is ready to install on any PCM or Kusu managed cluster.
IBM Platform Cluster Manager Kit Builder’s Guide
Page 10
A real example – Building an NCBI BLAST
kit
This section describes how to build a more complex kit for NCBI BLAST.
BLAST stands for Basic Local Alignment Search Tool. It is available from NCBI – the National
Center for Biotechnology Information. BLAST is widely used to search genomic databases and
find regions of similarity. It compares nucleotide or protein sequences to sequence databases, and
calculates the statistical significance of matches. More importantly for our purposes, it is a great
example of a tool widely deployed in HPC computing environments that would be useful to have
packaged as kit.
Various RPMs for BLAST are provided courtesy of Scalable Informatics, and are readily
downloadable at the address below.
http://blast.ncbi.nlm.nih.gov/Blast.cgi?CMD=Web&PAGE_TYPE=BlastDocs&DOC_TYPE=Do
wnload
The following steps create a kit that will automate the deployment of the BLAST software to
compute nodes on a PCM or Kusu managed cluster. These steps assume that users will only use
BLAST on x86_64 architectures.
1. Start by downloading the BLAST RPM from the site above, placing it in the /tmp director
Figure 9 - Obtaining the NCBI Blast software
IBM Platform Cluster Manager Kit Builder’s Guide
Page 11
2. Use the rpm -qpl command to check the RPM. As shown in Figure 10, it is a binary RPM
package and that the packages are precompiled.
Figure 10 - Viewing the contents of the BLAST RPM file
BLAST has a dependency on specific openmotif libraries so, you need to make sure that
openmotif library libXm.so.3 is installed before BLAST. This library is included in the
openmotif22-2.2.3-18.x86_64.rpm package on the operating system media2.
3. On the PCM installed node, mount the RHEL 5.5media, and navigate to the Server
subdirectory of the DVD as shown in Figure 11, to see the various openmotif RPM packages.
Since this package is a dependency for BLAST to install, you need to include the run time
libraries for the x86_64 architecture.
Figure 11 - Finding Open Motif on our OS media
2
You could create a symbolic link in /usr/lib64 from libXm.so.3 to point to the newer libXm.so.4
that may already be present in a RHEL 5.5 installation, but for this example, it’s better to get the correct library
version to show the concept of having a Kusu component depend on OS distribution package.
IBM Platform Cluster Manager Kit Builder’s Guide
Page 12
4. Use rpm –i to install the required openmotif22-2.2.3 runtime for the x64_86 architecture and
use rpm –qa to make sure it is present, as shown in Figure 12.
Figure 12 - Showing the Motif packages installed
5. With the library prerequisites resolved, make sure that you can install and run BLAST on your
RHEL 5.5 operating system before building the kit. As shown in Figure 13, the blastn
command runs correctly after installing the required Motif package.
Figure 13 - Making sure that BLAST runs
6. Build a required PCM Kit that contains NCBI BLAST. Create the kit directory structure using
the kusu-buildkit command as before:
Figure 14 - Creating the empty BLAST directory structure for kusu-buildkit
IBM Platform Cluster Manager Kit Builder’s Guide
Page 13
7. Move the required RPMs for the kit (BLAST itself and the required Openmotif RPM) into the
sources subdirectory in the newly created kit directory.
Figure 15- Placing the required components in the sources directory
8. Edit the file build.kit to configure how the kit is to be built.
When you initially use kusu-buildkit to create the kit template, a sample build.kit
file is created automatically. You need to edit this file to reflect the unique characteristics of
your kit.
IBM Platform Cluster Manager Kit Builder’s Guide
Page 14
Defining the Kit Properties in build.kit
You must change the default build.kit file to create the NCBI BLAST kit. The line numbers
in the build.kit file in these steps will not necessarily match the original line numbers in the
template file. (If you use vi to edit the file, use the :set nu command to make the edits below
easier to follow. Use whatever option exists in your text editor to show line numbers.)
Lines 26 through 36 in Figure 16 describe the default component in the kit.
Figure 16 - Editing the build.kit file to describe our BLAST kit
1. Provide a name for the overall kit structure. The example name is blast_comp, shown on
line 29. If you create the kit structure on RHEL 5, you will see that the default component will
initially be created using a call to ‘RHEL5Component()’. You could also changed this to
‘DefaultComponent()’ when you don’t want your KIT to be specifically tied to the just RHEL
operating systems since you know it will run across RHEL or CentOS.
2. Continue defining the component properties such as the name of our component as shown on
line 31. The component is called ncbi-blast. The architecture is important since the
binary RPM is precompiled specifically for x86 64-bit architecture so you set this accordingly.
If there were no such dependencies for the software component you could use noarch
instead of the default.
3. Define the version and release numbers for our component as shown on lines 32 and 33. You
will see later that these are reflected in the names of the component RPM files that will be
created by the build kit utility. The numbers can reflect your own numbering conventions, but
for simplicity you can set these version numbers to reflect the version of BLAST contained n
IBM Platform Cluster Manager Kit Builder’s Guide
Page 15
the kit (2.2.10).
4. Provide a human readable description of the component, as shown on line 34. This description
is shown in commands like kitops –l and when retrieving components to associate with
node group using the PCM Web interface. Although this component technically runs on
multiple distributions, this example supports RHEL 5 so this is reflected in the description.
5. Create a default association between this component and node group types/OS types, as
shown on lines 35 and 36. Line 35 says that by default the blast component will be associated
with compute nodes. You could optionally associate the blast component with multiple node
group types.
Note:
In a later section dealing with querying the PCM database, you’ll see how to find
out what the names of node groups are on the PCM cluster. You can query the
database directly from the command line to learn the structure and the names of
node groups. Although this example uses compute, as the node group type, you
could use our own node group definition name and then use the ngedit or
sqlrunner commands (included with PCM) in your post-installation script to
make sure that a definition for your own custom node group type exists.
6. Define the kit itself. Define the component first, because the kit needs to reference the
blast_comp component you just created.
7. Define your new default kit. As shown on line 46, the default name in this example is k
8. Provide properties for the kit including the name, description, and the architecture the kit is
intended for. Just as you provided a version and release number for the components above,
you can define version and release numbers for your kit as well, as shown in lines 51 and 52.
Figure 17 - Defining the kit properties in build.kit
IBM Platform Cluster Manager Kit Builder’s Guide
Page 16
9. Associate the component (blast_comp) that you defined above, with the kit k using the
addComponent method as shown on line 75 above. This indicates that the ncbi-blast
kit will contain the ncbi-blast component. Although this example has only one
component in the kit, kits can contain multiple components.
10. Define the actual software packages that make up the ncbi-blast kit. The BLAST file is a
binary RPM distribution that’s been compiled for an x86_64 machine. Recall that this version
of BLAST has a dependency on a particular Motif library (libXm.so.3), which is why you
also need the openmotif22 package from the operating system distros. (RHEL 5.5 in this
example).
11. Tell kusu-buildkit about the NCBI BLAST RPM as shown in Figure 18.
Figure 18 - describing the packages that comprise the BLAST kit
This RPM package name is NCBI. The blast_node_pkg is declared to be of type
RPMPackage(), which is a convenience method that returns a package with the scrtype
set to rpm.
The version is 2.2.24 and the minor release is 1. These package names matter. Installing the
NCBI blast package with the command rpm –qa | grep –i ncbi would show the package
name as ‘NCBI-2.2.24+-1’. Similarly, when Openmotif is installed, the RPM package name
will reflect this same convention of the package name, followed by the version and release
separated by hyphens.
IBM Platform Cluster Manager Kit Builder’s Guide
Page 17
For example, on RHEL 5.5 only Openmotif 2.3.0 is installed by default. Recall that you
additionally installed openmotif22 from the OS media in the course of installing BLAST to
make sure it runs properly before building the kit.
Figure 19 - Showing the name of the openmotif package
12. Use the rpm-qa command as shown above to give the proper name of the required package,
so that you know how to describe the package. This is shown in lines 16 through 18 below in
Figure 19.
Figure 20 - Describing the required openmotif distro package
For the openmotif22 package that comes from the operating system media, this example uses
the DistroPackage() method to create its own package. Like RPMPackage(), this is a
convenience function that returns a package with the srctype set to distro, saving you
the need to specifically declare it.
You can leave the ostype blank if you want (this is the default). Or you can enter the word
generic so that when the packages are built, an administrator studying the packages will
know that the package is not tied to a particular Linux distro. Values for ostype specifically
recognized in this release (HPC 3.0) include rhel, centos and sles. This example uses
the word rhelfamily specifically.
13. Set the install root directory to the path that the RPM installs from, as shown on line 19. The
openmotif22 package installs from the root directory.
14. Specify the actual name for the RPM, as shown on line 20. This file is assumed to exist under
the sources directory created by kusu-buildkit when you created the new kit directory
structure.
IBM Platform Cluster Manager Kit Builder’s Guide
Page 18
15. After adding the two RPM packages (NCBI and openmotif22), tell kusu-buildkit that
the default component (blast_comp) depends on these packages.
Figure 21- Specifying that the component depends on the BLAST and Motif packages
Line 40 above shows how to express these dependencies to kusu-buildkit. The BLAST
component depends on the two packages: blast_node_pkg and motif_node_pkg. By
default, a package will be deemed acceptable if its version is greater than or equal to the
package versions defined in the package definitions. If an exact match is required, you can
optionally add the dependency as blast_comp.addDep(motif_node_pkg,
True)setting the absolute version to True as opposed to the default which is False.
16. Complete the definition of the kit as shown below in Figure 22 by specifying script files that
will run following installation or following uninstallation.
This is shown on lines 58 and 62 where these scripts are associated with the kit definition
using addScript(). These template scripts are created by default when kusu-buildkit
initially creates the kit directory structure.
As an example of what might be done with an installation script, if your application relies on
the existence of a particular node group definition, you could invoke ngedit (in command
line mode) in the script to copy or add node groups. Similarly, you could manipulate the PCM
database using the sqlrunner command included in the PCM distribution, or set up rc.d
files to automate services like startup or shutdown etc.
IBM Platform Cluster Manager Kit Builder’s Guide
Page 19
Figure 22 - Adding kit post-install and post-uninstall scripts
Building the NIBC BLAST Kit ISO file
Kits are distributed as ISO files typically installed on DVD or CD. With the required files in the
sources directory and a build.kit file, you’re ready to build your kit. Create the kit ISO file by
running the command below from the directory containing the ncbi-blast directory:
# kusu-buildkit make kit=ncbi-blast
The dialog from this command is shown in Figure 23. If there are errors in the build.kit file in
the ncbi-blast directory, the kusu-buildkit script provides error messages to help
troubleshoot the problem.
If the kit builds successfully as shown below, the kit ISO file will be placed in the kit directory
itself (in this example, the ncbi-blast directory)
Figure 23 - Building the kit ISO based on the build.kit definition file
The packages in the kit are contained in the created ISO image and are stored in the packages
directory.
IBM Platform Cluster Manager Kit Builder’s Guide
Page 20
Figure 24 – Contents of the packages directory
The kit itself is defined in the kit-ncbi-blast-2.2.24-1.x86_64.rpm file.
This kit is simple in that it only has one component, which will be associated with nodes in the
node group compute on installation. In a more complex kit, different components that install on
different node types could be identified – installer nodes or database server nodes for example.
The kit RPM (kit-ncbi-blast-2.2.24-1.x86_64.rpm) contains a generated kitinfo
file to be installed in the /depot/kits directory on the installer node. This example does not
include documentation.
The component RPMs typically will not contain any files. This is because the files themselves are
contained in the provided RPM packages that the component depends on. Recall how addDep()
was used to express these dependencies in the build.kit file.
The figure below shows the specific RPM commands to see the contents of the RPM packages
created by kusu-buildkit as described above.
Figure 25 - Showing the contents of the BLAST kits and component files
Why is a component RPM file needed at all if it is empty? The reason is that PCM relies on RPM
to make sure that the needed software prerequisites are satisfied. Recall that the component
IBM Platform Cluster Manager Kit Builder’s Guide
Page 21
depends on openmotif 2.2.3 and NCBI (blast) 2.2.24. Querying the component RPM shows that
these dependencies are properly reflected in the RPM. If the dependency had been created with the
second argument in addDep() set to True, exact version matches would have been required as
dependencies.
Figure 26 - Showing RPM dependencies for the BLAST component
Verifying the Kit ISO File
You should make sure the ISO file has the needed packages before attempting to install it.
Remember that as far as Linux is concerned, an ISO file is just another CD or DVD.
Mount this kit ISO as a file system using the mount command with the -o loop option. Use
regular shell commands to navigate through the ISO directory structure as shown below. Recall
that the TRANS.TBL file is created by mkisofs to deal with the legacy issue of 8.3 style short
file names. It can be ignored.
Figure 27 - Mounting a newly created kit and showing its contents
IBM Platform Cluster Manager Kit Builder’s Guide
Page 22
Writing your ISO image to a CD or DVD
Copy the new ISO file to recordable CD or DVD media. Remember that copying the ISO media to
a rewritable CD or DVD using a Linux tool like dd will not suffice. There are a variety of ways to
write DVDs or CDs from Linux.
If you are running RHEL, and have access to the graphical desktop, you can follow these steps:
1.
2.
3.
4.
Insert blank media into the writer.
Launch K3b (Menu > Sound & Video > K3b).
From the Tools menu, select Burn CD Image or Burn DVD ISO Image as applicable.
An Open dialog appears. Click the Folder icon, then select the ISO Image file and click
Open.
5. Click Start to burn the image.
From the command line, you can use either cdrecord or growisofs commands. Some
command line examples are shown below:
# cdrecord -v dev=ATA:1,0,0 driveropts=burnfree -dao filename.iso
or:
# growisofs -dvd-compat -Z /dev/hdc=filename.iso
IBM Platform Cluster Manager Kit Builder’s Guide
Page 23
Testing the BLAST Kit
Before testing the newly created kit, you need to load the kit into PCM. When a kit is loaded, the
files in the kit are loaded into the directory /depot/kits, and information about the kit is
loaded into the SQL database on the PCM installer node.
1. Use the kusu-kitops command to load kits as shown below. The -a switch indicates that
a kit is to be added, and the media for the kit is specified with the -m switch. The name of the
kit is ncbi-blast. Figure 28 below shows the kit being successfully added to the installer
node.
Figure 28 - Using kusu-kitops to add our new Kit to the installer node.
2. You may want to inspect the /depot/kits/ncbi-blast subdirectory created after the
kit is installed on the installer node to make sure that the files were all created properly.
IBM Platform Cluster Manager Kit Builder’s Guide
Page 24
3. You should also inspect the kitinfo file created on installation by the kusu-kitops
command. This is a human readable file shown below in Figure 28 that defines the kit and
reflects the parameters you specified when the kit was built describing dependencies, OS and
architecture requirements, post installation and un-installation scripts etc.
Figure 29 - The kitinfo file after installation
As soon as you add a kit, it becomes visible through the PCM Web interface . You will notice
below that the CentOS kit and the new NCBI Blast kit are a different color than other kits listed in
the system. This is because the kits are not yet associated with a repository and therefore cannot be
selected. In the right hand column, you see any node groups that the software kits are associated
with. Since the kit is not yet in the repository, it is not associated with any node groups.
Figure 30 - Show kits and their associations with repositories and node groups
IBM Platform Cluster Manager Kit Builder’s Guide
Page 25
Before you can include the BLAST kit in a node group definition, you need to include it in your
repository. As shown in figure 31, used the Add/Remove Kits function in the GUI Repository
configuration . This is how we associate the NCBI Blast kit with a repository. After we perform
this step and click Apply, it will need to rebuild the repository.
Figure 31 - Adding NCBI-BLAST to the RHEL 5.5 repository
NCBI Blast is now listed as one of the available kits in our RHEL 5.5 repository.
Figure 32 - Showing the ncbi-blast kit is now listed in our RHEL repository.
If you have other repositories, you can add the NCBI Blast kit to those other repositories as well.
IBM Platform Cluster Manager Kit Builder’s Guide
Page 26
Provisioning the new BLAST Kit
With the kit now added to the repository, you can now associate the ncbi-blast component
with a node group definition. This will result in the new kit being automatically installed on all
compute hosts that are members of this node group the next time the hosts are reinstalled.
To add BLAST to the Red Hat compute hosts, select the node group definition (in this case the
default node for packaged-based installs of Red Hat 5.5) and click the Components tab. Open the
ncbi-blast kit as shown, and select the ncbi-blast component to be installed on the
compute host as shown below.
Figure 33- Associating the BLAST component with the RHEL 5.5 compute hosts
Note that NCBI Blast can be installed on compute nodes in this manner without having to reinstall
the compute hosts themselves. PCM runs cfmsync automatically forcing nodes to retrieve new
packages.
Run blastn on your compute nodes in the RHEL 5.5 compute node group to make sure the
automated installation was successful.
IBM Platform Cluster Manager Kit Builder’s Guide
Page 27
The Kit Build Process in More Detail
The BLAST example did not cover all the details of the build kit process. This section revisits
some of these steps.
Kit documentation
PCM kits should always have kit-level documentation. When documentation is provided in HTML
format in the docs directory of the kusu-buildkit directory structure, a link to the
documentation will be provided automatically from the main PCM web page on the installer node
served on port 80. During the kusu-buildkit process, adding documentation to the docs
directory in HTML format will cause the files in this directory to be pulled into the kit as
documentation (subdirectories are ignored).
Hostname:
hosta.example.com
PCM Version: “Platform HPC” 3.0 (build 4949)
OS Version: Red Hat Enterprise Linux Server release 5.6 (Tikanga)
Figure 34 - Documentation provided in the docs directory will automatically become
accessible
IBM Platform Cluster Manager Kit Builder’s Guide
Page 28
Kit Properties
Some additional kit properties are shown in Figure 35.
Figure 35 - Kit properties
Property
Description
Default
api
license
version
release
arch
name
description
Kit API version
License statement
Kit version number
Kit release number
Kit applicable arch structure
Kit name
Kit description
‘0.4’
‘LGPL’
‘0’
‘1’
‘noarch’
‘’
‘’
Kit Plugins
Three types of plugins are supported in the kusu-buildkit tool:
addhost
Plugins called by addhost, allowing actions to be specified when hosts are
added or removed or moved to other node groups.
genconfig
Generates configuration files in the unique format required for various software
utilities based on the contents of the central PCM SQL database. If your
application required a hosts file in a particular format, a genconfig plugin might
be written so that this configuration file could be created automatically based on
the cluster configuration.
ngedit
Used to generate configuration files when a component is selected, or to prompt
users for other information.
The kusu-buildkit tool does not explicitly support plugins for cfmsync or cfmclient
although it is possible to supply these as well. A directory for each of the above plugins is
provided in the directory structure when kusu-buildkit is initially run to build a new kit.
Plugins are specific to each application. The NCBI-Blast example was sufficiently simple that it
did not require any plugins.
IBM Platform Cluster Manager Kit Builder’s Guide
Page 29
When writing plugins, you should look in the directory /opt/kusu/lib/plugins for
examples. This is where the plugins from kits are ultimately installed. When a command like
addhost is run, PCM will invoke all of the plugins contained in the addhost subdirectory.
Many of the plugins have to do with core system services such as DNS, DHCP, SSH etc. Others
are written specifically for add-on applications.
As a simple example of an addhost plugin, the code below updates the /etc/hosts file after a
new host is added to the cluster.
import os
from kusu.addhost import *
class AddHostPlugin(AddHostPluginBase):
def updated(self):
os.system("/opt/kusu/bin/genconfig hosts > /etc/hosts")
def finished(self, nodelist, prePopulateMode):
os.system("/opt/kusu/bin/genconfig hosts > /etc/hosts")
Another facility that relies on plugins to work is genconfig itself. In the example above there is
actually a similar plugin to genconfig that knows exactly how to build a formatted
/etc/hosts file based on the contents of the PCM database. This long example is not included
here. Anyone developing kits that require that configuration files be generated based on the
database will want to review and understand these examples.
IBM Platform Cluster Manager Kit Builder’s Guide
Page 30
A more complex example is shown in Figure 36. When a host is added to the cluster, PCM will
also automatically update the Platform cfm (or Platform LSF if it is installed) configuration files
to save the administrator from having to perform these steps manually. Platform cfm or LSF
services will be restarted automatically following the reconfiguration of the cluster. A sample of
the code for addhost is shown below showing how the cfm cluster is automatically updated and
finished:
Figure 36 - an example addhost plug-ins to run, updated and finished cfm services
Tools like cfm are well integrated with PCM. The addhost, ngedit and genconfig tools
themselves are written in Python as well, enabling a determined developer to understand exactly
how the plugins are called.
IBM Platform Cluster Manager Kit Builder’s Guide
Page 31
Kit Post-installation Scripts
Post-installation scripts are generally run after the first boot, or after a new kit is added using the
kusu-kitops command. Template post-installation scripts are included in the source
directory in the build kit directory structure.
These scripts are typically used to:



Create additional node groups
Setup CFM files for default node groups
Tweak database entries by using the provided sqlrunner utility that can be called
from shell scripts
In the build.kit configuration file in the BLAST example, a line to add a post-installation
script to the kit definition was added:
k.addScript('00-post-script.sh',mode='post')
Kits can also have uninstallation scripts. These scripts are run on removal of the kit. They are used
to clean up the configuration on the installer node. Some uses of uninstall scripts are to:



Remove additional node groups
Remove CFM files for default node groups
Restore database entries to the way they were before the kit was added
Setting the mode to postun in the build.kit file tells kusu-buildkit that an uninstall
script is being specified:
k.addScript('00-postun-script.sh',mode='postun')
Kit Components
The BLAST example had only a single component in the kit. Kits must have at least one
component, but many kits will have multiple components. The Platform-supplied HPC kit is an
example of a kit that has multiple components.
Components are:



Almost empty packages
They require the real packages be installed (expressed as component dependencies)
Packages that finish the installation of an application or service for use on the cluster
IBM Platform Cluster Manager Kit Builder’s Guide
Page 32
Components are created in the build.kit file using syntax similar to that shown below:
blast_comp = RHEL5Component()
blast_comp.name = 'ncbi-blast'
blast_comp.arch = 'x86_64'
blast_comp.compversion = '2.2.24'
blast_comp.comprelease = '1'
blast_comp.description = 'NCBI BLAST Component for RHEL5.'
There are other constructors for components besides DefaultComponent() including:
RHEL5Component() – which will result in the ‘ostype’ being set to ‘rhel’ and the ‘osversion’
being set to ‘5’
Centos5Component() – which will result in the ostype being set to centos and the
osversion being set to 5.
Component properties and their defaults if not specified are:
Property
Description
Default
arch
compversion
comprelease
ngtypes
Component applicable architecture
Component version number
Component release number
Associated node group types
description
srctype
name
pkgname
ostype
osversion
Component description
Component src type
Component name
Package name
Operate system type
Operate system version
‘noarch’
‘0.1’
‘0’
[‘installer’, ‘compute’,
‘compute-imaged’,
‘compute-diskless’]
‘’
‘component’
‘’
‘’
‘’
‘’
To add multiple components to a kit define multiple components in the build.kit file. An
example showing how multiple components can be associated with a kit is provided below.
comp1 = RHEL5Component()
comp1.name = 'component1'
comp1.arch = 'x86_64'
comp1.compversion = '1'
comp1.comprelease = '0'
comp1.description = 'My First Kit Component'
comp1.addDep(package1)
comp1.addDep(package2)
comp2 = RHEL5Component()
IBM Platform Cluster Manager Kit Builder’s Guide
Page 33
comp2.name = 'component2'
comp2.arch = 'x86_64'
comp2.compversion = '1'
comp2.comprelease = '0'
comp2.description = 'My Second Kit Component'
comp2.addDep(package3)
comp2.addDep(package3)
k.addComponent(comp1)
k.addComponent(comp2)
Remember, the components don’t actually contain any software. They depend in turn on packages
described elsewhere in the build.kit configuration file.
About Software Packages
There are multiple ways to distribute software. Software is sometimes deployed as precompiled
binaries in RPM format (as was the case in the BLAST example). Other times, software may be
distributed in compressed tar file format and in other cases software may be installed in source
code form requiring you to build or compile the supplied code on your own.
In the build.kit configuration file, you indicate the type of package you are including in your
kits by choosing a correct packageprofile class. Choices are:
SourcePackage() – this type of package assumes a GNU Autotools package (srctype set
to autotools). Most developers will be familiar with these types of source packages. They
assume that they can run a configure script, followed by make to build the software.
RPMPackage() – these types of packages refer to binaries available in RPM format. This type
of package was used in the BLAST example.
pkg2 = RPMPackage()
pkg2.name = ‘aalib’
pkg2.version = ‘1.4‘
pkg2.release = '4_rc5.0.el5‘
pkg2.ostype = 'rhel‘
pkg2.filename = ‘aalib-1.4-4_rc5.0.el5.x86_64.rpm '
After the definition of comp in the build.kit file, add:
comp.addDep(pkg2)
IBM Platform Cluster Manager Kit Builder’s Guide
Page 34
The aalib package is assumed to reside in the sources directory.
SRPMPackage() – refers to a source RPM package. With these types of packages, the RPM will
be built from the source RPM during the kusu-buildkit process. This is similar to other
packages except that you specify a source RPM.
pkg3 = SRPMPackage()
pkg3.name = ‘mycode’
pkg3.version = ‘0.0.8‘
pkg3.release = 'l‘
pkg3.ostype = 'rhel‘
pkg3.filename = ‘mycode-0.0.8-1.src.rpm'
After the definition of comp in the build.kit file, add:
comp.addDep(pkg3)
When including this type of package, you will see the RPM being built as part of the build kit
process:
# kusu-buildkit make kit=mykit
Verifying the Kit Source directory found in /home/gord/ mykit..
Setting up BuildProfile for this kit..
Setting up a proper .rpmmacros for building this kit
Looking for the kitscript build.kit..
Found kitscript. Loading it..
Building kit for x86_64 architecture..
Building the package(s)..
..
Failures in building source RPM kits can tricky to debug if the package RPM fails to build for any
reason because there is no logging. The kusu-buildkit tool builds packages in the
artifacts directory. If building the package from the source RPM fails, you can manually
attempt to build the RPM using a command like:
# rpmbuild --define "_topdir mykit/artifacts/packages" \
-bb mykit/artifacts/packages/SPECS/mycode.spec
This should result in the error that caused the package to build being visible so that the problem
can be addressed.
DistroPackage() – these refer to Binary RPM packages included as a part of the operating
system distribution. The BLAST example used this to reference the required Motif libraries.
IBM Platform Cluster Manager Kit Builder’s Guide
Page 35
The example below specifies that the component comp relies on the operating system package
zsh version 4.1 or greater. The zsh package is assumed to be in the sources directory in the
kusu-buildkit directory structure.
pkg1 = DistroPackage()
pkg1.name = 'zsh’
pkg1.version = '4.1‘
pkg1.ostype = 'rhel'
After the definition of comp, add the line below to indicate that the component requires the zsh
package:
comp.addDep(pkg1)
Querying the PCM Database
As of PCM 3.0, PostgreSQL is used as the SQL database in PCM. You may need to understand the
schema to perform some activities like checking available node groups, writing post-installation
scripts and writing post-uninstall scripts. This section provides a few useful tips about working
with the PCM database.
To view the available tables in the PostgreSQL database and understand their schema, use the
PostgreSQL sqlrunner command to list available tables (from the shell in this example):
# sqlrunner –q ‘select * from pg_tables;’
The sqlrunner command is a python script provided with PCM that looks after the details of
connecting to the database and authenticating you so that you can easily run SQL commands
embedded in shell scripts or python scripts.
IBM Platform Cluster Manager Kit Builder’s Guide
Page 36
An example of describing the structure of the kits table is shown below. You know that kid is a
valid table because it is returned by the pg_tables query above.
Figure 37 - Determining the schema of a PostreSQL table
Tip:
If you’re doing this a lot you may want to create a script called describe to emulate the
same capability from MySQL.
To query information about your kits, you can use a query like the one show in Figure 38 below.
This query returns summary information about all the kits that the installer node knows about.
Figure 38 - Showing Kits know8 to the installer node
Note that kit ID 18 in Figure 38 is the NCBI Blast kit just built and added to the database.
IBM Platform Cluster Manager Kit Builder’s Guide
Page 37
Using the sqlrunner facility makes it relatively easy to script applications that can perform
different activities depending on the kits and versions of kits installed, available node group
definitions and so on.
A query to show the name of the various columns in the node groups table is shown below:
SELECT COLUMN_NAME,
DATA_TYPE,
CHARACTER_MAXIMUM_LENGTH,
NUMERIC_PRECISION,
NUMERIC_SCALE,
IS_NULLABLE,
SUBSTR(COALESCE(COLUMN_DEFAULT, ''), 1, 8) = 'nextval(' AS
IS_AUTOINCREMENT,
COLUMN_DEFAULT
FROM INFORMATION_SCHEMA.COLUMNS
WHERE TABLE_NAME = 'nodegroups'
ORDER BY ORDINAL_POSITION
Once you know the structure of the node groups table, you can query the table to see a list of
available node group definitions as shown in Figure 39 below.
Figure 39 - Showing node group definitions
IBM Platform Cluster Manager Kit Builder’s Guide
Page 38
Summary
Building complex kits with multiple software components and plugins essentially becomes a
software development activity where the software approach and required scripts depend on the
nature of the application and how it deploys on the cluster.
The kusu-buildkit tool provided with PCM simplifies the creation of simple kits. Developers
writing more complex kits should study some of the provided Python scripts and scripts included
with other kits as examples.
IBM Platform Cluster Manager Kit Builder’s Guide
Page 39
Notices
This information was developed for products and services offered in the U.S.A.
IBM may not offer the products, services, or features discussed in this document in other
countries. Consult your local IBM representative for information on the products and services
currently available in your area. Any reference to an IBM product, program, or service is not
intended to state or imply that only that IBM product, program, or service may be used. Any
functionally equivalent product, program, or service that does not infringe any IBM intellectual
property right may be used instead. However, it is the user's responsibility to evaluate and verify
the operation of any non-IBM product, program, or service.
IBM may have patents or pending patent applications covering subject matter described in this
document. The furnishing of this document does not grant you any license to these patents. You
can send license inquiries, in writing, to:
IBM Director of Licensing
IBM Corporation
North Castle Drive
Armonk, NY 10504-1785
U.S.A.
The following paragraph does not apply to the United Kingdom or any other country where
such provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES
CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY
KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS
FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied
warranties in certain transactions, therefore, this statement may not apply to you.
Without limiting the above disclaimers, IBM provides no representations or warranties regarding
the accuracy, reliability or serviceability of any information or recommendations provided in this
publication, or with respect to any results that may be obtained by the use of the information or
observance of any recommendations provided herein. The information contained in this
document has not been submitted to any formal IBM test and is distributed AS IS. The use of
this information or the implementation of any recommendations or techniques herein is a customer
responsibility and depends on the customer’s ability to evaluate and integrate them into the
customer’s operational environment. While each item may have been reviewed by IBM for
accuracy in a specific situation, there is no guarantee that the same or similar results will be
IBM Platform Cluster Manager Kit Builder’s Guide
Page 40
obtained elsewhere. Anyone attempting to adapt these techniques to their own environment does
so at their own risk.
This document and the information contained herein may be used solely in connection with the
IBM products discussed in this document.
This information could include technical inaccuracies or typographical errors. Changes are
periodically made to the information herein; these changes will be incorporated in new editions of
the publication. IBM may make improvements and/or changes in the product(s) and/or the
program(s) described in this publication at any time without notice.
Any references in this information to non-IBM websites are provided for convenience only and do
not in any manner serve as an endorsement of those websites. The materials at those websites are
not part of the materials for this IBM product and use of those websites is at your own risk.
IBM may use or distribute any of the information you supply in any way it believes appropriate
without incurring any obligation to you.
Any performance data contained herein was determined in a controlled environment. Therefore,
the results obtained in other operating environments may vary significantly. Some measurements
may have been made on development-level systems and there is no guarantee that these
measurements will be the same on generally available systems. Furthermore, some measurements
may have been estimated through extrapolation. Actual results may vary. Users of this document
should verify the applicable data for their specific environment.
Information concerning non-IBM products was obtained from the suppliers of those products,
their published announcements or other publicly available sources. IBM has not tested those
products and cannot confirm the accuracy of performance, compatibility or any other claims
related to non-IBM products. Questions on the capabilities of non-IBM products should be
addressed to the suppliers of those products.
All statements regarding IBM's future direction or intent are subject to change or withdrawal
without notice, and represent goals and objectives only.
This information contains examples of data and reports used in daily business operations. To
illustrate them as completely as possible, the examples include the names of individuals,
companies, brands, and products. All of these names are fictitious and any similarity to the names
and addresses used by an actual business enterprise is entirely coincidental.
COPYRIGHT LICENSE: © Copyright IBM Corporation 2013. All Rights Reserved.
This information contains sample application programs in source language, which illustrate
programming techniques on various operating platforms. You may copy, modify, and distribute
these sample programs in any form without payment to IBM, for the purposes of developing,
IBM Platform Cluster Manager Kit Builder’s Guide
Page 41
using, marketing or distributing application programs conforming to the application programming
interface for the operating platform for which the sample programs are written. These examples
have not been thoroughly tested under all conditions. IBM, therefore, cannot guarantee or imply
reliability, serviceability, or function of these programs.
Trademarks
IBM, the IBM logo, and ibm.com are trademarks or registered trademarks of International
Business Machines Corporation in the United States, other countries, or both. If these and other
IBM trademarked terms are marked on their first occurrence in this information with a trademark
symbol (® or ™), these symbols indicate U.S. registered or common law trademarks owned by
IBM at the time this information was published. Such trademarks may also be registered or
common law trademarks in other countries. A current list of IBM trademarks is available on the
Web at “Copyright and trademark information” at www.ibm.com/legal/copytrade.shtml
Windows is a trademark of Microsoft Corporation in the United States, other countries, or both.
UNIX is a registered trademark of The Open Group in the United States and other countries.
Linux is a registered trademark of Linus Torvalds in the United States, other countries, or both.
Other company, product, or service names may be trademarks or service marks of others.
IBM Platform Cluster Manager Kit Builder’s Guide
Page 42
Contacting IBM
To provide feedback about this guide, write to [email protected]
To contact IBM in your country or region, check the IBM Directory of Worldwide Contacts at
http://www.ibm.com/planetwide
To learn more about IBM Platform HPC, go to
http://www-03.ibm.com/systems/technicalcomputing/platformcomputing/products/hpc/
To learn more about IBM Platform Cluster Manager, go to
http://www-03.ibm.com/systems/technicalcomputing/platformcomputing/products/clustermanager
/index.html
IBM Platform Cluster Manager Kit Builder’s Guide
Page 43