The Gyrex cloud functionality is implemented based on ZooKeeper. When running in development mode, an embedded ZooKeeper server is started automatically so you don't have to configure anything at all. For production environments we highly recommend running a standalone ZooKeeper ensemble. Please have a look at the ZooKeeper Administrator's Guide for details on how to setup your own ensemble.
Connect to ZooKeeper
The first step is to connect each node with the ZooKeeper cluster. This can be done using the OSGi console or the Gyrex Admin UI.
Connect a node to ZooKeeper:
osgi> cloud setConnectString <zookeeper-connect-string> ... osgi>
zookeeper-connect-string can be any valid ZooKeeper connection string. In its simplest it's just a hostname or IP address.
To provide an
zookeeper-connect-string without using the osgi console or the Gyrex Admin UI, add the following line to the configuration/config.ini
An essential part of a cloud is node membership. Node membership in Gyrex is implemented by explicit approval of nodes. Each node has a unique identifier. Upon first start a new one is generated. It's also possible to manually set node ids. However, you need to ensure that node ids are unique. No two nodes with the same identifier are allows to join the cloud.
After a new node joins a cloud it will be registered with a pending state. In this state the node is not allowed to participate in any cloud activity other than node registration. An administrator need to explicitly approve the node first. Once the node has been approved it will become online.
Tags may be assigned to nodes. They will play an important role when distributing functionality and responsibilities within your cloud.
Two commands are available in the Equinox OSGi console for managing and analyzing the cloud. They both come with a small syntax help
osgi> help [...] ---CloudConsoleCommands--- cloud <cmd> [args] approve <NODEID> - approves a node ls pending|approved|online - list nodes retire <NODEID> - retires a node setConnectString <CONNECTSTRING> - sets the connect string for the local node setOffline - sets the current node offline setOnline - sets the current node on-line setTags <nodeId> [-t <tag> [-t <tag>]] - set tags for a node ---ZooKeeperConsoleCommands--- zk <cmd> [args] create <PATH> - creates a path in ZK get <PATH> - prints the content of the node at the specified path as a string ls <PATH> [-r] - lists the specified path reconnect - reconnects the ZooKeeper gate rm <PATH> [-r] - removes the specified path set <PATH> - sets the content of the node at the specified path as a string stat <PATH> - prints ZK stats of the specified path sync <PATH> - performs ZK sync on the specified path [...] osgi>
List pending (unapproved) nodes:
osgi> cloud ls pending [nodeId] (hostname) ... osgi>
Approve a node:
osgi> cloud approve <nodeId>