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 Eclipse Amlen servers.

You can use the Eclipse Amlen REST API POST method to configure the cluster membership of Eclipse Amlen servers. If the cluster that is specified in the request does not exist in the Eclipse Amlen 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 Eclipse Amlen server.

Optional: Eclipse Amlen supports user provided TLS credentials for Clustering. Providing the credentials prior to adding a server to a cluster is recommended to avoid migrating the cluster. See Clustering: User Provided TLS Credentials.
To configure the cluster membership of an Eclipse Amlen server, use the Eclipse Amlen REST API POST method with the following configuration URI:

http://<admin-endpoint-IP:Port>/ima/v1/configuration/
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.
Restart the server.
Use the Eclipse Amlen REST API POST method on each server with the following Eclipse Amlen 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" 
}
```
Verify that the status of the cluster is Active and the cluster is connected to other servers in the cluster.
Use the Eclipse Amlen 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
  }
}
```

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."
}