Configure Failover Between RCS Servers
Important
Connectors continue to be released outside the IDM release. For the latest documentation, refer to the ICF documentation.
For failover purposes, you can configure a group of RCSs, in either server or client mode. Failover is particularly important when you configure an RCS in client mode because IDM has no way of knowing whether the RCS is available.
To prevent the RCS from being a single point of failure, you can specify a list of RCS servers that the connector can target. To set up a failover configuration, you create either a remoteConnectorServersGroup or a remoteConnectorClientsGroup and list the RCS servers. The connector attempts to contact the first RCS in the list. If that RCS is down, it proceeds to the next RCS.
This example configures a remoteConnectorServersGroup that lists two remote RCS servers, on hosts remote-host-1 and remote-host-2. The RCS servers are listed by their name property. You can configure multiple groups and multiple servers per group.
First, generate the core configuration to obtain the required properties:
curl \ --header "X-OpenIDM-Username: openidm-admin" \ --header "X-OpenIDM-Password: openidm-admin" \ --header "Accept-API-Version: resource=1.0" \ --header "Content-Type: application/json" \ --request POST \ --data '{ "type" : "remoteConnectorServersGroup", "systemType" : "provisioner.openicf" }' \ "http://localhost:8080/openidm/system?_action=createConnectorServerCoreConfig"{ "displayName": "", "name": "", "serversList": [], "algorithm": "failover" }
Use the output returned in the previous example to create your RCS group configuration. Use a PUT request on the config endpoint:
curl \ --header "X-OpenIDM-Username: openidm-admin" \ --header "X-OpenIDM-Password: openidm-admin" \ --header "Accept-API-Version: resource=1.0" \ --header "Content-Type: application/json" \ --request PUT \ --data '{ "_id": "provisioner.openicf.connectorinfoprovider", "connectorsLocation": "connectors", "enabled": true, "remoteConnectorServers": [ { "type": "remoteConnectorServersGroup", "displayName": ".NET Failover Group", "name" : "dotnet-ha", "algorithm" : "failover", "serversList" : [ {"name": "remote-host-1"}, {"name": "remote-host-2"} ] } ] }' \ "http://localhost:8080/openidm/config/provisioner.openicf.connectorinfoprovider"{ "_id": "provisioner.openicf.connectorinfoprovider", "connectorsLocation": "connectors", "enabled": true, "remoteConnectorServers": [ { "type": "remoteConnectorServersGroup", "displayName": ".NET Failover Group", "name": "dotnet-ha", "algorithm": "failover", "serversList": [ { "name": "remote-host-1" }, { "name": "remote-host-2" } ] } ] }
The algorithm can be either failover or roundrobin. If the algorithm is failover, requests are always sent to the first RCS in the list, unless it is unavailable; in which case, requests are sent to the next RCS in the list. If the algorithm is roundrobin, requests are distributed equally between the RCS servers in the list, in the order in which they are received.
Your connector configuration (provisioner.openicf-connector-name.json) references the RCS group, rather than a single RCS. For example, the following excerpt of a PowerShell connector configuration file references the dotnet-ha RCS group created in the previous example:
{
"connectorRef" : {
"bundleName" : "MsPowerShell.Connector",
"connectorName" : "Org.ForgeRock.OpenICF.Connectors.MsPowerShell.MsPowerShellConnector",
"connectorHostRef" : "dotnet-ha",
"bundleVersion" : "[1.4.3.0,1.5.0.0)"
},
...
} This example configures a remoteConnectorClientsGroup that lists two remote RCS servers, on hosts remote-host-1 and remote-host-2. The RCS servers are listed by their name property. You can configure multiple groups and multiple servers per group.
First, generate the core configuration to obtain the required properties:
curl \ --header "X-OpenIDM-Username: openidm-admin" \ --header "X-OpenIDM-Password: openidm-admin" \ --header "Accept-API-Version: resource=1.0" \ --header "Content-Type: application/json" \ --request POST \ --data '{ "type" : "remoteConnectorClientsGroup", "systemType" : "provisioner.openicf" }' \ "http://localhost:8080/openidm/system?_action=createConnectorServerCoreConfig"{ "displayName": "", "name": "", "serversList": [], "algorithm": "failover" }
Use the output returned in the previous example to create your RCS group configuration. Use a PUT request on the config endpoint:
curl \ --header "X-OpenIDM-Username: openidm-admin" \ --header "X-OpenIDM-Password: openidm-admin" \ --header "Accept-API-Version: resource=1.0" \ --header "Content-Type: application/json" \ --request PUT \ --data '{ "_id": "provisioner.openicf.connectorinfoprovider", "connectorsLocation": "connectors", "enabled": true, "remoteConnectorClients": [ { "type": "remoteConnectorClientsGroup", "displayName": ".NET Failover Group", "name" : "dotnet-ha", "algorithm" : "failover", "serversList" : [ {"name": "remote-host-1"}, {"name": "remote-host-2"} ] } ] }' \ "http://localhost:8080/openidm/config/provisioner.openicf.connectorinfoprovider"{ "_id": "provisioner.openicf.connectorinfoprovider", "connectorsLocation": "connectors", "enabled": true, "remoteConnectorClients": [ { "type": "remoteConnectorClientsGroup", "displayName": ".NET Failover Group", "name": "dotnet-ha", "algorithm": "failover", "serversList": [ { "name": "remote-host-1" }, { "name": "remote-host-2" } ] } ] }
The algorithm can be either failover or roundrobin. If the algorithm is failover, requests are always sent to the first RCS in the list, unless it is unavailable; in which case, requests are sent to the next RCS in the list. If the algorithm is roundrobin, requests are distributed equally between the RCS servers in the list, in the order in which they are received.
Your connector configuration (provisioner.openicf-connector-name.json) references the RCS group, rather than a single RCS. For example, the following excerpt of a PowerShell connector configuration file references the dotnet-ha RCS group created in the previous example:
{
"connectorRef" : {
"bundleName" : "MsPowerShell.Connector",
"connectorName" : "Org.ForgeRock.OpenICF.Connectors.MsPowerShell.MsPowerShellConnector",
"connectorHostRef" : "dotnet-ha",
"bundleVersion" : "[1.4.3.0,1.5.0.0)"
},
...
}