Configuring cluster membership by using REST Administration APIs

System administrators can configure clusters by using a REST Administration API. The REST Administration API allows you to configure the cluster membership attributes of IBM® Watson IoT Platform - Message Gateway servers.

About this task

You can use the IBM Watson IoT Platform - Message Gateway REST API POST method to configure the cluster membership of IBM Watson IoT Platform - Message Gateway servers. If the cluster that is specified in the request does not exist in the IBM Watson IoT Platform - Message Gateway configuration table, then the cluster is created. Otherwise the cluster configuration is updated. Changes to cluster membership configuration do not take effect until the server is restarted.

For more information about the components you must specify to configure cluster membership, including naming restrictions, see Configuring the cluster membership of an IBM Watson IoT Platform - Message Gateway server.

Procedure

  1. To configure the cluster membership of an IBM Watson IoT Platform - Message Gateway server, use the IBM Watson IoT Platform - Message Gateway REST API POST method with the following configuration URI:

    http://<admin-endpoint-IP:Port>/ima/v1/configuration/

  2. Provide ClusterMembership object configuration data in the payload of the POST method by using the following schema. Content-type is set to application/json: 
    
{    
  "ClusterMembership": {
      "EnableClusterMembership": true|false,
      "ClusterName": "string",
      "UseMulticastDiscovery": true|false,
      "MulticastDiscoveryTTL": integer,
      "DiscoveryServerList": "string",
      "ControlAddress": "string",
      "ControlPort": integer,
      "ControlExternalAddress": "string",
      "ControlExternalPort": integer,
      "MessagingAddress": "string",
      "MessagingPort": integer,
      "MessagingExternalAddress":"string",
      "MessagingExternalPort": integer,
      "MessagingUseTLS": true|false,
      "DiscoveryPort": integer,
      "DiscoveryTime": integer 
   }
 }
    Where:
    EnableClusterMembership: true|false
    Specifies whether clustering is enabled.
    If the server is to join a cluster, EnableClusterMembership must be set to true.
    If the server is to leave a cluster, EnableClusterMembership must be set to false.
    After the server is configured to join or leave a cluster, the server must be restarted for the cluster configuration to take effect.
    The default value is false which means that clustering is not enabled.
    ClusterName
    Required.
    Specifies the name of the cluster.
    The cluster name must be unique within the local area network.
    UseMulticastDiscovery: true|false
    Optional.
    Specifies whether cluster members are in a list or discovered by multicast.
    If UseMulticastDiscovery is set to true, multicast is used to locate other members of the cluster.
    If UseMulticastDiscovery is set to false, DiscoveryServerList must be set.
    The set of servers that is located is the set located by multicast discovery or by using DiscoveryServerList. The set also includes any servers that are known to any of the servers found by either setting UseMulticastDiscovery to true or by specifying a value in DiscoveryServerList.
    The default value is true.
    MulticastDiscoveryTTL
    When UseMulticastDiscovery is true, MulticastDiscoveryTTL specifies the number of routers, or hops, that multicast traffic is allowed to pass through.
    MulticastDiscoveryTTL is not used if UseMulticastDiscovery is false.
    The value must be in the range 1-256.
    The default value is 1.
    DiscoveryServerList
    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 DiscoveryServerList 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
    ControlAddress
    Required if EnableClusterMembership is true.
    Specifies the local IP address of the network interface for the control channel.
    ControlPort
    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.
    ControlExternalAddress
    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.
    ControlExternalPort
    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.
    MessagingAddress
    Specifies the local IP address of the network interface for the messaging channel.
    MessagingPort
    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.
    MessagingExternalAddress
    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.
    MessagingExternalPort
    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.
    MessagingUseTLS: true|false
    Specifies whether the messaging channel is to use TLS.
    The default value is false which means that the messaging channel is not to use TLS.
    DiscoveryPort
    The port number to be used for multicast discovery.
    The port number must be the same for all members of the cluster.
    DiscoveryPort is not used if UseMulticastDiscovery is false.
    Specify a value in the range 1-65535.
    The default value is 9106.
    DiscoveryTime
    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.
  3. Restart the server.

    Use the IBM Watson IoT Platform - Message Gateway REST API POST method on each server with the following IBM Watson IoT Platform - Message Gateway configuration URI:

    http://<admin-endpoint-IP:port>/ima/v1/service/restart

    Provide object configuration data in the payload of the POST method by using the following schema. Content-type is set to application/json: 

    
{    
  "Service": "Server" 
}
  4. Verify that the status of the cluster is Active and the cluster is connected to other servers in the cluster.
    Use the IBM Watson IoT Platform - Message Gateway REST API GET method with the following URI:

    http://<admin-endpoint-IP:Port>/ima/v1/service/status/Cluster

    The following example shows an example response to the GET method and shows that the server is active in the cluster and is connected to the other cluster members:

    
{ 
  "Version":"v1", 
  "Cluster": { 
    "Status": "Active",    
    "Name": "MyCluster",    
    "Enabled": true,    
    "ConnectedServers": 2,
    "DisconnectedServers": 0
  }
}

Example

The following example shows a POST method in cURL to configure the cluster membership of a server that is to join a cluster called "MyCluster":


curl -X POST \
   -d  '{
      "ClusterMembership": {
          "EnableClusterMembership": true,
          "ControlAddress": "10.10.33.11",
          "DiscoveryServerList": "10.10.33.12:9104,10.10.33.10:9104",
          "UseMulticastDiscovery": true,
          "ClusterName": "MyCluster"
            }
       }
    ' \
 http://127.0.0.1:9089/ima/v1/configuration

The following example shows an example response to the POST method:


{        
  "Version": "v1",
  "Code": "CWLNA6011",
  "Message": "The requested configuration change has completed successfully."
}