Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Gyrex/Administrator Guide/Cloud
Cloud
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>
The 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
... gyrex.zookeeper.connectString=<zookeeper-connect-string>
Node Management
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.
Console Commands
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>