Page History

Apache Geronimo v2.1 offers different alternatives for clustering such as Jetty or Tomcat native, WADI and Terracotta.

• Farming

A configuration can be deployed to a cluster of Geronimo servers via a single logical deployment step. Once deployed to a cluster, this configuration can then be transparently started, stopped or undeployed across all the cluster members.
These two features greatly streamline the maintenance of applications running on a cluster as Geronimo takes care of cluster-wide application distribution and management for you.

Configuration of Cluster Members

Cluster members are configured on a Geronimo server, which may but is not required to be a member of the cluster. This is achieved by adding a org.apache.geronimo.farm.config.BasicNodeInfo GBean for each cluster member to the farming configuration. This GBean looks like:

<gbean name="NodeInfo" class="org.apache.geronimo.farm.config.BasicNodeInfo">
    <attribute name="name">${PlanClusterNodeName}</attribute>
    <xml-attribute name="extendedJMXConnectorInfo">
        <ns:javabean xmlns:ns="http://geronimo.apache.org/xml/ns/deployment/javabean-1.0" class="org.apache.geronimo.farm.config.BasicExtendedJMXConnectorInfo">
            <ns:property name="username">system</ns:property>
            <ns:property name="password">manager</ns:property>
            <ns:property name="protocol">rmi</ns:property>
            <ns:property name="host">localhost</ns:property>
            <ns:property name="port">1099</ns:property>
            <ns:property name="urlPath">JMXConnector</ns:property>
            <ns:property name="local">true</ns:property>
        </ns:javabean>
    </xml-attribute>
</gbean>

It defines network address (host, port, urlPath) and credentials (username and password) to be used to connect to the cluster member via JMX. Such declarations are to be included within the config.xml file, farming module of your Geronimo server.
By default, the farming configuration defines the local server as a cluster member. To exclude it, you can prevent the GBean NodeInfo to start.

Farm Deployment

To deploy a configuration to configured members, you simply deploy it to the MasterConfigurationStore repository defined by the farming configuration. This configuration being stopped out-of-the-box, you may have to start it the first time via this GShell command:

deploy/start org.apache.geronimo.configs/farming//car

farming adds two new repositories to the server: MasterConfigurationStore and ClusterStore. MasterConfigurationStore is the repository you should use most of the time if not always. ClusterStore is a repository you may have to use in specific and infrequent scenarios.
To deploy to MasterConfigurationStore, you pass the --targets flag to the distribute or deploy commands like this:

deploy/distribute  --targets XXX,name=MasterConfigurationStore <your module>

Following this deployment

• MasterConfigurationStore contains a kind of virtual configuration, which has the same name than your deployment and defines GBeans controlling the remote start and stop of the actual configuration cluster-wide; and
• ClusterStore contains the actual configuration under an altered configuration name, a '_G_SLAVE' is appended to the configuration name.

Cluster-wide Management of Configurations

To start, stop or undeploy configurations across a cluster, you perform the relevant deployment task against the virtual configuration. All the cluster members configured at the time of the initial deployment must be running otherwise these operations are partially executed. For instance, if three members were configured and only two of them are running when the virtual configuration is undeployed, then the configuration is removed from the ClusterStore of the two running servers. The ClusterStore of the third server still contains the configuration and this latter will have to be manually undeployed on this server.

• WADI Clustering Support

Web-applications and Stateful SessionBeans (Geronimo 2.2+) can be clustered by WADI. In order to cluster these components, their Geronimo deployment descriptors are augmented with specific XML elements. These elements define various clustering parameters controlling how underlying WADI's components are wired and set-up upon application deployment.

Clustering Configurations

The two following configurations, shipped out-of-the-box with JEE5 assemblies, must be installed for clustering to work properly:

• org.apache.geronimo.configs/clustering//car: it defines the runtime dependencies that clustered Web applications or EJB modules must have. For instance, it imports the geronimo-clustering JAR into the classpath of such modules. Also, it defines a Node GBean defining the unique name of this Geronimo instance in the cluster.
  In order to give a specific name to your Geronimo instance, this module can be reconfigured by updating the clusterNodeName property defined within var/config/config-substitutions.properties:

  Code Block
  clusterNodeName=MyOwnNodeName

• org.apache.geronimo.configs/wadi-clustering//car: it defines WADI specific GBeans used to further configure the behaviour of clustered applications and the WADI group communication service shared by all clustered applications to communicate with each others.
  This is in this module, by overriding the DefaultBackingStrategyFactory GBean, that the default number of replicas, 2, to be maintained across the cluster for a given HTTP session or SFSB instance is configured.
  These configurations are automatically started when clustered applications are started. Hence, you should not start them explicitly.

Clustering of Web-applications

Updating your Deployment Descriptors

Standard and Geronimo specific deployment descriptors must be updated as follows:

• standard deployment descriptor, i.e. web.xml: the Web application must be marked as distributable. In other words, the optional "distributable" element must be defined:

  Code Block
  <web-app> ..... <distributable/> ..... </web-app>

• Geronimo deployment descriptor, i.e. geronimo-web.xml: if you are deploying the application to embedded Jetty, then the "clustering-wadi" substitution group must be defined. If you are deploying to embedded Tomcat, then you should use the "tomcat-clustering-wadi" substitution group. These substitution groups are defined by the XSDs geronimo-clustering-wadi-X.xsd and geronimo-tomcat-clustering-wadi-X.xsd respectively which are included in the schema folder of a Geronimo server installation.
  Both of these elements provide a Web application specific clustering configuration, which overrides the default clustering configuration. This default clustering configuration is defined by the GBean WADIJettyClusteringBuilder declared by org.apache.geronimo.configs/jetty6-clustering-builder-wadi//car.
  Here is an example Geronimo deployment descriptor targeted at Jetty embedded:

  Code Block
  <?xml version="1.0" encoding="UTF-8"?> <web-app xmlns="http://geronimo.apache.org/xml/ns/j2ee/web/jetty-1.2"> <environment> <moduleId> <groupId>yourGroupId</groupId> <artifactId>yourArtifactId</artifactId> <version>YourVersion</version> <type>war</type> </moduleId> </environment> <context-root>/yourPath</context-root> <clustering-wadi /> </web-app>

Jetty Web-application Clustering Configurations

The two following configurations, shipped out-of-the-box with the JEE5 Jetty assemblies, must be installed for clustering to work:

• org.apache.geronimo.configs/jetty6-clustering-wadi//car: it defines runtime dependencies and Jetty6 clustering contracts.
• org.apache.geronimo.configs/jetty6-clustering-builder-wadi//car: it defines deployment time dependencies along with a JettyClusteringBuilder GBean declaring the default clustering configuration.
  This configuration must be running when a clustered Web-application is started. If it is not, then the substitution group clustering-wadi is not properly recognized and the deployment fails.

Tomcat Web-application Clustering Configurations

...

• Tomcat Native Clustering