Configure Eclipse Amlen server cluster membership

Purpose

Configures the cluster membership of an Eclipse Amlen server.

URI

Use the Eclipse Amlen REST API POST method with the following Eclipse Amlen configuration URI:

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

Object configuration data

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: An optional parameter that can be set when the configured cluster member is behind a firewall, and for which the IP address that cluster members need to connect to is different (translated by a NAT firewall, for example) than the local interface. This value should be the IP address of the control channel interface that is visible to other cluster members.; If this parameter is set, the Cluster.DiscoveryServerList of other cluster members should consist of the ControlAddressExternal plus the ControlPortExternal of cluster members that define them.; For cluster members that do not define ControlAddressExternal and/or ControlPortExternal, the Cluster.DiscoveryServerList should contain the ControlAddress and ControlPort.
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.

Usage Notes®

Capitalization and double quotation marks must be used as shown.
Changes to cluster membership configuration do not take effect until the server is restarted.

Related REST Administration APIs

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