InteGrade: Object-Oriented Grid Middleware v0.5

IG-Deployer: Taktuk powered version v0.2

Deployment Manual

Last updated: June 18th 2009.

-----------------------------------------------------------------------------
INTRODUCTION

IG-Deployer is an automatic deployment tool for InteGrade. It is based on a tool for deploying parallel remote executions of commands to a large set of remote nodes called Taktuk (http://taktuk.gforge.inria.fr/). For further information about IG-Deployer see http://www.integrade.org.br/files/nascimento-wscad.pdf.

This document describes the procedures for the deployment of InteGrade, using IG-deployer. It's intended to be used by users not familiar with InteGrade, nor the technologies it leverages. Follow the Quick Install Notes to have InteGrade up and running in localhost quickly.

For information about this subject or any problems, questions, musings, or suggestions regarding InteGrade, please contact the InteGrade support team at integrade@googlegroups.com or consult the InteGrade portal (http://www.integrade.org.br).

-----------------------------------------------------------------------------
SETTING UP THE ENVIRONMENT

--------------- Quick Install Note ---------------
In a fresh Ubuntu 9.04 install, the following command is enough to install dependencies:

$ sudo aptitude install g++ libreadline5-dev default-jdk libssl-dev openssh-server

Now configure a passwordless ssh connection as explained in http://www.integrade.org.br/ssh-without-password . Then you can skip this section.
-------------------- End Note --------------------

InteGrade v0.5 has many dependencies, and currently only works in GNU/Linux platform. Some of the dependencies are included in this version of IG-Deployer, but others are required as pre-requisites of this tool. For ease of notation, we will split the machines that are part of the installation set into two groups, the spanning node, composed by the node where the ig-deployer will be installed, and the grid, that is the rest of the machines that will receive InteGrade. Frequently, the spanning node will also be part of the grid.

In order to begin a proper deployment of InteGrade, this set of packages must be available in all grid machines, with an special exception for PERL, the only dependency of the spanning node. This exception of dependencies allow the deployer to run hypothetically in any operational system with a perl implementation and ssh client. The pre-requisites are:

- PERL v5.8.8 or greather.

- GCC 4.0 or greater - The GNU C Compiler.
  Debian and Fedora packages: gcc-4.0, gcc-4.0-base

- G++ 4.0 or greater - The GNU C++ Compiler.
  Debian and Fedora package: g++-4.0
  Ubuntu 9.04 package: g++

- GNU Make - The popular UNIX-based build tool.
  Debian and Fedora package: make

- JDK 1.5 or greater - The Java Development Kit v1.5.0, including both the compiler and runtime environment for the Java Language.
  Ubuntu 9.04 package: default-jdk
  Available at http://java.sun.com/javase/downloads/index_jdk5.jsp

- Readline Library.
  Debian/Ubuntu package: libreadline5-dev

- SSL libraries.
  Ubuntu package: libssl-dev

If a secure application repository is necessary (this is recommended for jobs running on shared machines), the following packages are also required:

 - General purpose cryptographic C++ library.
   Debian package: libcrypto++-dev

 - Kerberos with all libraries and header files.
   Debian packages: libkrb5-dev, krb5-user, krb5-admin-server, krb5-kdc

The deployer also requires SecureShell (ssh) connection without password in all machines as explained in http://www.integrade.org.br/ssh-without-password

Deployer already contains the main InteGrade dependencies:

- Ant 1.5 or greater - A Java-based platform-independent build tool.

- JacORB 2.2.3 - A Java-based open-source CORBA ORB that runs on cluster manager machines. 

- OiLPack (incl. Lua-5.0-Plus, Compat-Lua-5.1-r5, LuaSocket-2.0, and OiL 0.3.1) - A software bundle containing the compiler and runtime for the Lua scripting language, a library for building Lua-based socket applications, and the OiL lightweight CORBA ORB, which runs on resource provider nodes.

-----------------------------------------------------------------------------

INSTALLATION

The easy way to install InteGrade, is to download the ig-with-deployer package. It is a pack containing three elements: the InteGrade, the deployer and this manual. Check http://www.integrade.org.br/software for the latest version.

Extract the package:

$ tar zxvf packageName.tar.gz
or
$ tar xvf packageName.tar.lzma --lzma

To see if everything worked well just type:

$ cd integrade/deployer
$ ./deployer check

You should see:

Reading default.yml
localhost(grm lrm), GRM localhost will install in /usr/local/integrade with java at /usr/lib/jvm/java-6-sun/
 and shared as Null.

-----------------------------------------------------------------------------
CONFIGURATION FILES (config/default.yml)

--------------- Quick Install Note ---------------
Check the 'path' in config/default.yml. This installation dir must exist (with proper permissions). Another suggestion: ~/integrade (if you haven't already extracted the package there).

If you've installed the default-jdk package (Ubuntu) change 'java' to '/usr/lib/jvm/default-java', otherwise check the correct java path, commonly found in /usr/lib/jvm:

$ ls /usr/lib/jvm

You may skip this section if you only want to install in localhost.
-------------------- End Note --------------------

The syntax of the configuration files are very simple. It is based on an human friendly data serialization standard called YAML (YAML Ain't Markup Language) available at (http://www.yaml.org/). These fields must be specified on the configuration file for each machine.

installgrm: True if the Global Resource Manager should be installed on this machine. The grm may be seen as the InteGrade server, and one special machine must be chosen to be GRM. False otherwise.

installlrm: True if the Local Resource Manager should be installed on this machine. The lrm may be seen as the InteGrade client. False otherwise.

grm: The name of the machine where the GRM will be installed.

path: The default path of installation. The directory must already exists.

shared: The path for the NFS installation. If omitted the dependencies will be installed in the machine, if a path is given, it will assume that this machine have access to the dependency folder.

java: The path where the java dependency is installed.

An example should be:

---
ubuntu:
   installgrm: true
   installlrm: true
   grm: ubuntu
   path: /usr/local/integrade
   shared: /global/integrade
   java: /usr/lib/jvm/java-6-sun/

suse:
   installgrm: false
   installlrm: true
   grm: ubuntu
   path: /usr/local/integrade
   shared: /global/integrade
   java: /usr/lib/jvm/java-6-sun/

fedora:
   installgrm: false
   installlrm: true
   grm: ubuntu
   path: /usr/local/integrade
   shared: /global/integrade
   java: /usr/lib/jvm/java-6-sun/

With this configuration, InteGrade will be installed in 3 machines, ubuntu, suse and fedora. All the machines will have InteGrade at /usr/local/integrade (the folder must exists before installation and must have write permissions for the user running ig-deployer). All the dependencies will be installed in ubuntu, at /global/integrade and it's assumed that all the other machines will have access to that folder. It will also assume that/usr/lib/jvm/java-6-sun/ contains the path for the Java Virtual Machine. Note that you don't need the shared information if you're going to replicate dependencies into all target nodes or if you want to install only into one machine.

All configuration files must be in the config directory.

-----------------------------------------------------------------------------
COMMANDS

--------------- Quick Install Note ---------------
To install using the default configuration (config/default.yml), run:
$ ./deployer all
-------------------- End Note --------------------

The syntax of ig-deployer is the following: 

deployer [YAML FILE] COMMAND [TOPOLOGY]

The YAML FILE is the configuration file located in config directory. If omitted, default.yml will be used.

Where COMMAND is mandatory and is one of the commands introduced later in this document, TOPOLOGY stands for the configuration file named TOPOLOGY.yml, notice that the topology name must be given without the .yml extension, and if you supply no topology name, the default.yml topology will be assumed.

"ALL" COMMAND
   The all command runs the sequence of commands CHECK, PING, CLEAN, PACK, DEPLOY, INSTALL, START.

"CHECK" COMMAND
   This command performs a test of syntax against the given YAML file, to guarantee that file represents a valid topology. A valid topology must include a GRM, at least one LRM, a path to install the files and a java path.

"PACK" COMMAND
   The command pack searches and packs two folders. The first one is InteGrade, that must be at ../integrade. The second one is the dependency package that is inside the folder packs/dependency. After this step two files will be generated in /pack folder, the deps.tar.gz and the deploy.tar.gz. If one of this files exists at the time of command invocation, the respective file is not created.

"DEPLOY" COMMAND
   Sends the files deploy.tar.gz and deps.tar.gz for remote hosts.

"INSTALL" COMMAND
   Unpack and build all the dependencies. The result of this command is a complete installation of InteGrade. It depends of previous executions of the commands PACK and DEPLOY.

"INSTALLPORTAL" COMMAND
   Installs the portal in the first GRM available. It depends of previous executions of the commands PACK and DEPLOY.

"START" COMMAND
   Stop all services, start the grid GRM and them all the clients.
 
"STOP" COMMAND
   Stop all services.

"PING" COMMAND
   Try to connect in all hosts in order to verify existence and functionality of them.

"CLEAN" COMMAND
   Erases local deployment files deps.tar.gz and deploy.tar.gz. It also removes remote files needed for installation.

"UNINSTALL" COMMAND
   Removes InteGrade from the entire grid.

-----------------------------------------------------------------------------
RUNNING INTEGRADE

After deployer successfully finish, you can leave this deployer/README and jump to the section "LAUNCHING INTEGRADE" in integrade/INSTALL.

-----------------------------------------------------------------------------
KNOWN ISSUES

If you are having any problem, it's a list of known bugs in deployer.

- If the deps folder has the same path as the users home directory, the installation fails.

- The target "start" blocks its execution, it starts the InteGrade but it never knows that the start processes finishes.

- Sometimes the main service, the GRM, starts after some LRM, this is a problem in a set of large nodes because some machines will not be able to register to their GRM, and will not be part of the grid. You should then manually starts the server first (run $IG_HOME/startservices.sh servers) and then all the LRM (run $IG_HOME/startservices.sh client).

- Openssl Dependency is not being compiled nor properly linked. We recommend you to install it from your distribution package.

-----------------------------------------------------------------------------
TROUBLESHOOTING

These are most common errors and their solutions. If your problem is not covered here, e-mail the error messages to integrade-support in googlegroups.


1. [hostname] ([pid number]): state > Connection failed

This error happens if the hostname provided in configuration file (defaults to localhost in config/default.yml) cannot be resolved.

To solve this problem, check if the hostname in the configuration file is correct. If it still can't be resolved (try "ping hostname"), you can add it to /etc/hosts. For instance, if hostname is "localhost", add "127.0.0.1 localhost" to /etc/hosts.

Then keep following the instructions, you need to have a passwordless ssh connection to that hostname, otherwise you get the next issue.


2. [hostname] ([pid number]): connector > Permission denied

It means you cannot "ssh hostname" without password. As written in section "SETTING UP THE ENVIRONMENT", follow the instructions in http://www.integrade.org.br/ssh-without-password
