Configure high availability

Purpose

Configures an Eclipse Amlen server to participate in a high availability (HA) pair.

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 HighAvailability object configuration data in the payload of the POST method by using the following schema. Content-type is set to application/json:


{    
   "HighAvailability": {
      "Group": "string",
      "EnableHA": true|false,
      "StartupMode": "string",
      "RemoteDiscoveryNIC": "string",
      "LocalReplicationNIC": "string",
      "LocalDiscoveryNIC": "string",
      "DiscoveryTimeout": integer,
      "HeartbeatTimeout": integer,
      "PreferredPrimary": true|false,
      "RemoteDiscoveryPort": integer,
      "ReplicationPort": integer,
      "ExternalReplicationPort": integer,
      "ExternalReplicationNIC":  
      "UseSecuredConnections": true|false,
      "RequireCertificates": true|false             
    }
}

Where:

Group

Required.

Specifies the group name of the HA pair.

The value must be the same on both servers in the pair.

The value can be a maximum of 128 characters.

When this value is set, replication and discovery addresses are not required.

EnableHA: true|false

Optional.

Specifies whether HA is enabled (true) or disabled (false).

The default value is false.

StartupMode

Optional.

Specifies the mode in which the node starts.

The value can be one of the following values:

AutoDetect

AutoDetect means that, at start up, the nodes of the HA-Pair detect one another and automatically establish the HA-Pair. If the node cannot detect the other node in the HA-Pair, it does not start.
StandAlone

StandAlone is used to bring up a single node with the intention to later bring up another node that synchronizes with the first node and creates an HA-Pair. If another node is detected as the node starts, the node does not start.

RemoteDiscoveryNIC

Required if "EnableHA": true is specified.

Specifies the IP address of the NIC that is used for HA discovery on the remote node in the HA pair.

LocalReplicationNIC

Required if "EnableHA": true is specified.

Specifies the IPv4 or IPv6 address of the NIC that is used for HA replication on the local node in the HA pair.

LocalDiscoveryNIC: Required if "EnableHA": true is specified.; Specifies the IPv4 or IPv6 address of the NIC that is used for HA discovery on the local node in the HA pair.
DiscoveryTimeout: Optional.; Specifies the time in seconds that the node attempts to discover the HA pair node.; The value must be in the range 10-2147483647.; The default value is 600.
HeartbeatTimeout: Optional.; Specifies the time in seconds to detect that the other node in the HA pair has failed.; The value must be in the range 1-2147483647.; The default value is 10.
PreferredPrimary: true|false: Optional.; Specifies whether the node that the command is run on is the preferred primary when both nodes are started in auto-detect mode.; The default value is false.
RemoteDiscoveryPort: Optional.; Specifies the port number to be used for HA discovery on the remote node in the HA pair.; The value must be in the range 1024-65535.; By default, this value is not set.
ReplicationPort: Optional.; Specifies the port number to be used for HA replication on the local node in the HA pair.; The value must be in the range 1024-65535.; By default, this value is not set.
ExternalReplicationPort: Optional.; Specifies the external port number to be used for HA replication on the local node in the HA pair.; The value must be in the range 1024-65535.; By default, this value is not set.
ExternalReplicationNIC: Optional.; Specifies the IPv4 or IPv6 address of the NIC that is used for HA replication.
UseSecuredConnections: true|false: Optional.; Specifies whether to use Transport Layer Security for discovery and data channels between the nodes in the HA pair.; The default value is false.
RequireCertificates: true|false: Optional.; Specifies whether when using TLS the nodes in the HA pair are required to send certificates.; If false any certificates that are sent will still be validated.; Only recommended for temporary use when upgrading from IBM WIoTP Message Gateway to Eclipse Amlen.; The default value is true.

Usage Notes®

Capitalization and double quotation marks must be used as shown.
Group is a required item.
Depending on the update that you make, you might need to restart the Eclipse Amlen server after you use the REST API POST method to update the HA configuration.
You can restart the Eclipse Amlen server by using the REST API POST method with the following Eclipse Amlen configuration URI:
```
http://<admin-endpoint-IP:Port>/ima/v1/service/restart
```
Provide configuration data in the payload of the POST method by using the following schema. Ensure that capitalization and double quotation marks are used as shown.
```
{    
  "Service": "Server" 
      
}
```

Related REST Administration APIs

Example

Updates the HA configuration by using cURL:


curl -X POST  \
   -H 'Content-Type: application/json'  \
   -d  '{    
            "HighAvailability": {                  
            "Group": "Group2", 
            "EnableHA": true, 
            "RemoteDiscoveryNIC": "192.0.4.2",
            "LocalReplicationNIC": "192.0.2.6",
            "LocalDiscoveryNIC": "192.0.3.2",                 
            "PreferredPrimary": true 
        }
     }
  '  \
http://127.0.0.1:9089/ima/v1/configuration/

An example response to the POST method:


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