Configuring the cluster membership of an IBM Watson IoT Platform - Message Gateway server

You can configure IBM® Watson IoT Platform - Message Gateway servers in clusters to increase the maximum messaging throughput or the maximum number of concurrent connections beyond the capacity of a single IBM Watson IoT Platform - Message Gateway server. All IBM Watson IoT Platform - Message Gateway servers in a cluster share a common topic tree.

A cluster is a collection of 2 or more IBM Watson IoT Platform - Message Gateway servers that are connected together over a local high-speed LAN. Clusters allow a greater maximum number of concurrent connections and a greater messaging throughput than can be achieved on a single server.

The task of cluster configuration includes establishing how the servers within the cluster find each other, and the control channel and messaging channel that are to be used between the servers.

A server finds other servers in the cluster by using multicast discovery, or by specifying a known subset of the other servers in the cluster. Each server is a peer of all other servers in the cluster. The control channel sends subscription information and other related information to all servers in the cluster; the same control information is sent to all the members in the cluster. In addition, a messaging channel is created from each server to each member in the cluster. Only messages that might be needed on the remote server are sent on the messaging channel.
Note: The IBM Watson IoT Platform - Message Gateway Web UI refers to the control channel as the control interface and the messaging channel as the messaging interface.

It is good practice that all servers in a cluster have the same configuration of messaging objects (messaging hubs, policies, and certificates) but not the same configuration of endpoints. To make monitoring of the cluster easier, it is good practice to assign a unique server name to each member of the cluster.

Ensure that all port numbers that you use are unique.

When a server joins a cluster, you must restart the server.

Changes to cluster membership configuration do not take effect until the server is restarted.

When you configure the cluster membership of an IBM Watson IoT Platform - Message Gateway server so that it joins a cluster, you must specify the following components:
  • Enable Cluster Membership
    Specifies whether clustering is enabled.
    If the server is to join a cluster, Enable Cluster Membership must be set to true.
    After the server is configured to join or leave a cluster, the server must be restarted for the cluster configuration to take effect.
  • Cluster Name
    Specifies the name of the cluster.
    The cluster name must be unique within the local area network.
    The name must not have leading or trailing spaces and cannot contain control characters, commas, double quotation marks, backslashes, or equal signs. The first character must not be a number or any of the following special characters: ! # $ % & ' ( ) * + - . / : ; < > ? @
    The cluster name cannot be changed while Enable Cluster Membership is true.
  • Control Address
    Specifies the local IP address of the network interface for the control channel.
You can also specify the following components:
  • Use Multicast Discovery
    Specifies whether cluster members are in a list or discovered by multicast.
    If multicast discovery is specified, multicast is used to locate other members of the cluster.
    If multicast discovery is not to be used, you must specify a discovery server list.
    The resulting set of servers consists of the set that is located by multicast discovery or by using the discovery server list or both. The set also includes any servers that are known to any of the servers that are found by multicast discovery or by using the discovery server list.
    The default behavior is to use multicast discovery.
  • Multicast Discovery TTL
    Applies only when multicast discovery is being used.
    Specifies the number of routers, or hops, that multicast traffic is allowed to pass through.
    The value must be in the range 1-256.
    The default value is 1.
  • Discovery Server List
    Required when multicast discovery is not selected.
    Comma-separated list of servers in the cluster that the server is to join.
    The format that represents each server in the list is ControlAddress:ControlPort
    It is good practice to specify the same two or three servers in the Discovery Server List on each server that is to join the cluster. New members of the cluster can then find one of the servers and receive all the information about the rest of the cluster. The resulting set of servers is the known set of all cluster members
  • Control Port
    The local port number to use for the control channel.
    Ensure that the port number for the control channel is unique amongst all ports that are used in the server.
    The value must be in the range 1-65535.
    The default value is 9104.
  • Control External Address
    The host name or IP address of the control channel as it is known to other servers. The Control External Address can be different from the Control Address because it allows a resolvable name. The Control External Address can also be used when address mapping is used, or when a firewall is used to route connections.
  • Control External Port
    The external port number to use for the control channel as it is known to other servers. The external port is needed when the ports have been mapped and the port, as known locally, is not the same as the port known externally.
  • Messaging Address
    Specifies the local IP address of the network interface for the messaging channel.
  • Messaging Port
    The local port number to use for the messaging channel.
    Ensure that the port number for the messaging channel is unique amongst all ports that are used in the server.
    The value must be in the range 1-65535.
    The default value is 9105.
  • Messaging External Address
    The host name or IP address of the messaging channel as it is known to other servers. The Messaging External Address can be different from the Messaging Address because it allows a resolvable name. The Messaging External Address can also be used when address mapping is used, or when a firewall is used to route connections.
  • Messaging External Port
    The external port number to use for the messaging channel as it is known to other servers. The external port is needed when the ports have been mapped and the port, as known locally, is not the same as the port known externally.
    The value must be in the range 1-65535.
  • Messaging Use TLS
    Specifies whether the messaging channel is to use use Transport Layer Security (TLS).
    The default behavior is that the messaging channel does not use TLS.
  • Discovery Port
    Applies only when multicast discovery is being used.
    The port number to be used for multicast discovery.
    The port number must be the same for all members of the cluster.
    Specify a value in the range 1-65535.
    The default value is 9106.
  • Discovery Time
    The time, in seconds, that the cluster spends during server start up to discover other servers in the cluster and get updated information from them.
    Specify a value in the range 1-2147483647.
    The default value is 10.

For more information about configuring cluster membership by using the IBM Watson IoT Platform - Message Gateway Web UI, see Configuring cluster membership by using the IBM Watson IoT Platform - Message Gateway Web UI.

For more information about configuring cluster membership by using REST Administration APIs, see Configuring cluster membership by using REST Administration APIs.