Registering nodes

Information about the nodes in your environment can be registered to Workbench's Node Manager tool. Node information includes basic host metadata:

• name: a symbolic name of the node
• description: description of the node's role or function
• hostname: administrative hostname. (eg, "strongbad.local") Can be the same as "name".
• os-arch: operating system architecture (eg, "i386")
• os-family: operating system family (eg, "unix" or "windows")
• os-name: operating system name (eg, "Linux", "Darwin", "SunOS")
• os-version: operating system version (eg, "2.6", "9.2.2", "4.3.1")

Node information is maintained within a Workbench project.

You may already have existing data about your nodes that you would like to import to Workbench. A successful method for importing this information is to dump and translate your data into either XML or tabular file format described below.

This document describes several methods to register node information to Workbench.

ControlTier supports an XML file format that lets you register various kinds of metadata, including information about nodes.

Create an XML file declare the "project.dtd" and define each node you wish to register using the node tag.

The example XML file shown below defines two nodes: strongbad and centos.

File listing: /tmp/node.xml

<!DOCTYPE project PUBLIC
        "-//ControlTier Software Inc.//DTD Project Document 1.0//EN" "project.dtd">
<project>

  <node name="strongbad" type="Node"
    description="a development host"
    hostname="strongbad.local"
    osArch="i386" osFamily="unix" osName="Darwin" osVersion="9.2.2"
    ctlBase="" ctlHome="" ctlUsername="" ctlPassword=""
    tags="mac,development"/>

  <node name="centos" type="Node"
    description="a centos host"
    hostname="centos.acme.com"
    osArch="i386" osFamily="unix" osName="Linux" osVersion="2.6.9-34.EL"
    ctlBase="" ctlHome="" ctlUsername="" ctlPassword=""
    tags="server,qa-env"/>

</project>
      

To load the data into Workbench, run ProjectBuilder's load-objects command and specify the XML file:

ctl -p default -m ProjectBuilder -c load-objects -- -filename /tmp/node.xml

processing file: /tmp/node.xml
...output omitted...
Batch request performed successfully.
      

Run ProjectBuilder's find-objects command to query Workbench for the registered nodes and you'll see the two node registrations:

ctl -p default -m ProjectBuilder -c find-objects -- -type Node
|--(Node) strongbad
|--(Node) centos

As an alternative to XML, the ProjectBuilder load-objects command also supports a simple tabular format. Each host registration is defined as a line in a text file, and each metadata field, is specified in a column separated by a delimiter.

The format of the tabular file for node information is described below:

type[delim]name[delim]hostname[delim]os-arch[delim]os-family[delim]os-name[delim]os-version[delim]comment

The default delimiter character is the ":" (colon).

Here's an example record for a node named "bento" using tabular formatted file using colons as delimiters:

File listing: /tmp/node.tab

Node:bento:bento.local:i386:unix:Linux:2.6:A bento host

Run ProjectBuilder's load-objects command and specify the data file along with the -format tabular option:

ctl -p default -m ProjectBuilder -c load-objects -- \
   -format tabular -filename /tmp/node.tab -type Node

processing file: /tmp/node.tab
Updating object: (Node) bento
Batch request performed successfully.
      

Run ProjectBuilder's find-objects command to query Workbench for the registered nodes and you'll see bento:

ctl  -p default -m ProjectBuilder -c find-objects -- -type Node

|--(Node) bento

Any time you setup a new project depot for a CTL client host, the node information about that client is registered to Workbench.

Project depot administration is done using CTL-DEPOT command. To create a new project run:

ctl-depot -p project -a create

This will create a new local project depot on that client host and register the client node to Workbench in the corresponding Workbench project.

You can create a utility command to register individual nodes by declaring a CTL command in a module. The example below uses several Ant tasks supporting metadata registration in Workbench. These tasks will be used to register a new node in a project:

• object-exists: checks if a node exists in a project.
• object-create: creates a node object.
• object-update: updates an existing node object

Use the ProjectBuilder create-type command to create a module or choose an existing one. Edit the module's type.xml file and then define the "node-register" command. This command will first check if the node already exists in the project and if it does, updates it with the information provided in the command line options. If it does not exist it creates a new object with the specified information.

Cut and paste the following XML data and place it inside the <commands></commands> tags in your type.xml.

<command name="node-register" description="register a new node." 
	 command-type="AntCommand" is-static="true">
  <implementation>
    <object-exists depot="${context.depot}"
	       resultproperty="result"
	       comment="Checking node registration">

      <node name="${opts.name}" type="Node"/>

    </object-exists>

    <switch value="${result}">
      <case value="0">
	<echo>Node "${opts.name}" is registered. Updating info...</echo>
	<object-maprefuri depot="${context.depot}" resultproperty="uri.result"
	   outputproperty="obj.uri" comment="Looking up maprefuri for ${opts.name}[Node]">
	      <resource name="${opts.name}" type="Node"/>
	</object-maprefuri>
        <object-update depot="${context.depot}"
	       resultproperty="result"
	       comment="Updated node object from node-register command">
          <node maprefUri="${obj.uri}"
	    name="${opts.name}"
	    type="Node"
	    description="${opts.description}"
	    hostname="${opts.hostname}"
	    osArch="${opts.osarch}"
	    osFamily="${opts.osfamily}"
	    osName="${opts.osname}"
	    osVersion="${opts.osversion}"/>
        </object-create>
      </case>

      <case value="1">
	<echo>Registering new Node "${opts.name}" ...</echo>

        <object-create depot="${context.depot}"
	       resultproperty="result"
	       comment="Created node object from command">
          <node
	    name="${opts.name}"
	    type="Node"
	    description="${opts.description}"
	    hostname="${opts.hostname}"
	    osArch="${opts.osarch}"
	    osFamily="${opts.osfamily}"
	    osName="${opts.osname}"
	    osVersion="${opts.osversion}"/>
        </object-create>
      </case>

      <default>
	<fail>unrecognized server result: ${result}</fail>
      </default>
   </switch>
  </implementation>
  <opts>
    <opt parameter="name" description="node name" required="true"
	 property="opts.name" type="string" />
    <opt parameter="description" description="node description" required="false"
	 property="opts.description" type="string" default=""/>
    <opt parameter="hostname" description="administrative hostname" required="true"
	 property="opts.hostname" type="string" />
    <opt parameter="osarch" description="node os architecture" required="true"
	 property="opts.osarch" type="string" />
    <opt parameter="osfamily" description="node os familiy" required="true"
	 property="opts.osfamily" type="string" />
    <opt parameter="osname" description="node os name" required="true"
	 property="opts.osname" type="string" />
    <opt parameter="osversion" description="node os version" required="true"
	 property="opts.osversion" type="string" />
  </opts>
</command>
      

After running build-type you can register new nodes like so:

ctl -m yourmodule -c node-register --\
      -name centos -hostname centos.local -osarch i386 -osfamily unix \
      -osname Darwin -osversion 9.2.2 -description "'this is a centos node'"