This documentation is for WSO2 API Manager 2.1.0. View documentation for the latest release.

All docs This doc

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Updated the note on Hazelcast version check at startup

...

Enabling Hazelcast clustering

Note
iconfalse
titleBefore you begin

By default, in newer versions of Hazelcast, namely Hazelcast version 3.5.5 and newer, the Hazelcast new version check on startup is enabled. Hazelcast version check is not mandatory for WSO2 functions. Therefore, if you need to analyze the Hazelcast version for a third-party requirement, we recommend that you whitelist the phone home URL at the network level, in order to disable the Hazelcast version check at startup, by following the instructions below:

Warning

Make sure to do the following in all the nodes of the cluster.

Localtab Group
Localtab
activetrue
idOnLinuxOrMac
titleOn Linux or Mac

On Linux or Mac, add following property to <PRODUCT_HOME>/bin/wso2server.sh , in the section starting from $JAVACMD, which is where the system properties are listed.

Code Block
-Dhazelcast.version.check.enabled=false
Localtab
idOnWindows
titleOn Windows

On Windows add the following property to <PRODUCT_HOME>/bin/wso2server.bat in the section starting from CMD_LINE_ARGS, which is where system properties are listed

Code Block
-Dhazelcast.version.check.enabled=false

Make sure to restart the servers after you make above changes in all the nodes.

Follow the instructions below to enable Hazelcast clustering when deploying WSO2 API-M:

...

  1. Open the <GATEWAY_WORKER_HOME>/repository/conf/axis2/axis2.xml file.
  2. Locate the clustering section and verify or configure the properties as follows (some of these properties are already set correctly by default):
    1. Enable clustering for this node: 

      Code Block
      <clustering class="org.wso2.carbon.core.clustering.hazelcast.HazelcastClusteringAgent" enable="true">
    2. Set the membership scheme to  wka  to enable the Well Known Address registration method (this node will send cluster initiation messages to WKA members that we will define later): 

      Code Block
      <parameter name="membershipScheme">wka</parameter>
    3. Specify the name of the cluster this node will join: 

      Code Block
      <parameter name="domain">wso2.am.domain</parameter>
    4. Specify the host used to communicate cluster messages. This is the IP address of the Gateway worker.

      Code Block
      <parameter name="localMemberHost">xxx.xxx.xxx.xx4</parameter>
    5. Specify the port used to communicate cluster messages (if this node is on the same server as the manager node, or another worker node, be sure to set this to a unique value, such as 4000 and 4001 for worker nodes 1 and 2). 

      Code Block
      <parameter name="localMemberPort">4200</parameter>
      Info

      This port number will not be affected by the port offset in carbon.xml. If this port number is already assigned to another server, the clustering framework will automatically increment this port number. However, if two servers are running on the same machine, you must ensure that a unique port is set for each server.

    6. Define the sub-domain as worker by adding the following property under the  <parameter name="properties">  element: 

      Code Block
      <property name="subDomain" value="worker"/>
    7. Define the manager and worker nodes as well-known members of the cluster by providing their host name and localMemberPort values. The manager node is defined here because it is required for the Deployment Synchronizer to function in an efficient manner. The deployment synchronizer uses this configuration to identify the manager and synchronize deployment artifacts across the nodes of a cluster.

      Code Block
      languagexml
      <members>
          <member>
              <hostName>xxx.xxx.xxx.xx3</hostName>
              <port>4500</port>
          </member>
          <member>
              <hostName>xxx.xxx.xxx.xx4</hostName>
              <port>4200</port>
          </member>
      </members>
      Note

      it is recommended to add at least two well-known members here. This is done to ensure that there is high availability for the cluster.

      You can also use IP address ranges for the hostName. For example,  192.168.1.2-10. This should ensure that the cluster eventually recovers after failures. One shortcoming of doing this is that you can define a range only for the last portion of the IP address. You should also keep in mind that the smaller the range, the faster the time it takes to discover members, since each node has to scan a lesser number of potential members.

    8. See the instructions on configuring hazelcast properties given below.
Note
iconfalse

By default, in newer versions of Hazelcast, namely Hazelcast version 3.5.5 and newer, the Hazelcast new version check on startup is enabled. Hazelcast version check is not mandatory for WSO2 functions. Therefore, if you need to analyze the Hazelcast version for a third-party requirement, we recommend that you whitelist the phone home URL at the network level, in order to disable the Hazelcast version check at startup, by following the instructions below:

Warning

Make sure to do the following in all the Gateway nodes of the cluster.

Localtab Group
Localtab
activetrue
idOnLinuxOrMac
titleOn Linux or Mac

On Linux or Mac, add following property to <PRODUCT_HOME>/bin/wso2server.sh , in the section starting from $JAVACMD, which is where the system properties are listed.

Code Block
-Dhazelcast.version.check.enabled=false
Localtab
idOnWindows
titleOn Windows

On Windows add the following property to <PRODUCT_HOME>/bin/wso2server.bat in the section starting from CMD_LINE_ARGS, which is where system properties are listed

Code Block
-Dhazelcast.version.check.enabled=false

Make sure to restart the servers after you make above changes in all the nodes.

Configuring Hazelcast properties

...