Gold Allocation Manager

Methods of interacting with Gold

There are essentially six ways of programatically interacting with Gold.

Configuring an application that already has hooks for Gold

The easiest way to use Gold is to use a resource management system with built-in support for Gold. For example, the Maui Scheduler and Silver Grid Scheduler can be configured to directly interact with Gold to perform the quotes, reservations, and charges by setting the appropriate parameters in their config files.

Example 1. Configuring Maui to use Gold

Add an appropriate AMCFG line into maui.cfg to tell Maui how to talk to Gold

$ vi /usr/local/maui/maui.cfg


Add a CLIENTCFG line into maui-private.cfg to specify the shared secret key. This secret key will be the same secret key specified in the "make auth_key" step.

$ vi /usr/local/maui/maui-private.cfg


Gold will need to allow the the user id that Maui runs under to perform scheduler related commands (Job Charge, Reserve, Quote, etc).

$ gmkuser -d "Maui Scheduler" maui

Successfully created 1 User

$ goldsh RoleUser Create Role=Scheduler Name=maui

Role            Name
--------------- ------
Scheduler maui

Successfully created 1 RoleUser

Using the appropriate command-line client

From inside a script, or by invoking a system command, you can use a command line client (one of the "g" commands in gold's bin directory).

Example 2. To issue a charge at the completion of a job, you would use gcharge:

gcharge -J PBS.1234.0 -p chemistry -u amy -m colony -P 2 -t 1234

Using the Gold control program

The Gold control program, goldsh, will issue a charge for a job expressed in xml (SSS Job Object).

Example 3. To issue a charge you must invoke the Charge action on the Job object:

goldsh Data:="<Job><JobId>PBS.1234.0</JobId><ProjectId>chemistry</ProjectId>

Use the Perl API

If your resource management system is written in Perl or if it can invoke a Perl script, you can access the full Gold functionality via the Perl API.

Example 4. To make a charge via this interface you might do something like:

use Gold;

my $request = new Gold::Request(object => "Job", action => "Charge");
my $job = new Gold::Datum("Job");
$job->setValue("JobId", "PBS.1234.0");
$job->setValue("ProjectId", "chemistry");
$job->setValue("UserId", "amy");
$job->setValue("MachineName", "colony");
$job->setValue("Processors", "2");
$job->setValue("WallDuration", "1234");
my $response = $request->getResponse();
print $response->getStatus(), ": ", $response->getMessage(), "\n";

Communicating via the SSSRMAP Protocol

Finally, it is possible to interact with Gold by directly using the SSSRMAP Wire Protocol and Message Format over the network (see SSS Resource Management and Accounting Documentation). This will entail building the request body in XML, appending an XML digital signature, combining these in an XML envelope framed in an HTTP POST, sending it to the server, and parsing the similarly formed response. The Maui Scheduler communicates with Gold via this method.

Example 5. The message might look something like:

Content-Type: text/xml; charset="utf-8"
Transfer-Encoding: chunked

<?xml version="1.0" encoding="UTF-8"?>

  <Body actor="scottmo" chunking="True">
    <Request action="Charge" object="Job">
    <SecurityToken type="Symmetric"></SecurityToken>