Cluster standby mode

The cluster standby feature lets you segment a set of IDM instances into two groups: active and standby.

Active instances process schedules (including clustered reconciliation schedules) and mappings configured for queued sync. Standby instances don’t process these operations, functioning as hot spares that can be activated on demand.

Standby instances still respond to direct client API requests, such as managed object mutations and client-dispatched reconciliation invocations. A load balancer or reverse proxy must ensure that standby nodes are not targeted by client-dispatched requests.

Setting up and maintaining an active-standby deployment architecture is complex. The cluster standby endpoint gives you control over individual node behavior, but the broader deployment configuration (such as, networking, load balancing, database replication, and failover orchestration) is the responsibility of the deployer and is outside the boundaries of product support.

Enable standby mode

To enable the cluster standby feature, set both of the following properties to true in resolver/boot.properties for each instance that participates in standby mode:

org.forgerock.feature.cluster.active.passive=true
org.forgerock.feature.cluster.improved=true

Instances with both properties set to true startup into standby mode by default.

Transition active nodes

Use the openidm/cluster/active endpoint to transition a node between active and standby states.

Learn more about the cluster activation endpoint.

Activate a standby node

To transition a standby node to active:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--request PUT \
--header "Accept-API-Version: resource=1.0" \
--header 'Content-Type: application/json' \
--header 'If-Match: *' \
--data '{"state":"ACTIVE"}' \
'http://localhost:8080/openidm/cluster/active'

Set an active node to standby

To transition an active node to standby:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--request PUT \
--header "Accept-API-Version: resource=1.0" \
--header 'Content-Type: application/json' \
--header 'If-Match: *' \
--data '{"state":"STANDBY"}' \
'http://localhost:8080/openidm/cluster/active'

Read the current state

To check the current state of a node:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--request GET \
--header "Accept-API-Version: resource=1.0" \
'http://localhost:8080/openidm/cluster/active'

Standby node behavior

When a node is in standby mode:

The node doesn’t execute persistent schedules.
The node doesn’t participate in clustered reconciliation.
The node doesn’t process queued sync mappings.
The node does respond to direct API requests (REST calls for managed objects, configuration, and so on).

When a node transitions from standby to active, it resumes processing schedules, clustered reconciliation, and queued sync.

Configure standby endpoint authentication

Access to the openidm/cluster/active endpoint is authenticated using credentials stored as a secret. Configure the username and password through the purpose identified by idm.cluster.activation.credentials.

Learn more in Store username and password as a secret.

Failover procedure

The following is a typical failover procedure:

Transition the formerly active nodes by sending a PUT request with {"state":"STANDBY"} to each applicable node.
Activate the formerly standby nodes by sending a PUT request with {"state":"ACTIVE"} to each applicable node.
Update the load balancer configuration to route traffic to the newly active nodes.

To failback, reverse the procedure.

Both active and standby IDM instances must access a database layer with consistent state during failover transitions. Ensure that database replication latencies between the repositories supporting active and standby nodes are less than the time required to complete the failover cutover.

PingIDM