How do I manage configuration changes within a cluster in OpenIDM 4.x?
The purpose of this article is to provide information on configuration management within a cluster in OpenIDM. This information does not apply to IDM 5 and later, since IDM 5 introduced improvements to simplify the configuration and management of a cluster.
1 reader recommends this article
Archived
This article has been archived and is no longer maintained by ForgeRock.
Typical configuration
The following shows a typical cluster configuration for two OpenIDM nodes:
| Node 1 | Node 2 |
|---|---|
| openidm.node.id=idm1 openidm.instance.type=clustered-first # openidm.fileinstall.enabled=false # openidm.config.repo.enabled=false # felix.fileinstall.disableConfigSave=false | openidm.node.id=idm2 openidm.instance.type=clustered-additional openidm.fileinstall.enabled=false # openidm.config.repo.enabled=false # felix.fileinstall.disableConfigSave=false |
|
This node applies changes made to the JSON files on disk both at startup and runtime to the current instance and will be persisted within the repository. Changes made via REST will be persisted within the repository and written back to the on-disk JSON configuration files. |
This node does not apply changes made to the JSON files on disk either at startup or runtime. Changes made via REST will be persisted within the repository and written back to the on-disk JSON configuration files. |
Configuration properties
The following configuration properties determine how and when the configuration is loaded from, or written to the on-disk JSON configuration files:
| Configuration property | Meaning |
|---|---|
| openidm.fileinstall.enabled |
This property specifies whether changes made to the on-disk JSON configuration files will be loaded by OpenIDM, applied to the active configuration and persisted within the repository. The default is true. Set in the system.properties file (located in the /path/to/openidm/conf directory). |
| openidm.config.repo.enabled |
This property specifies whether the OpenIDM configuration will be persisted within the repository or whether it will only be stored within memory. The default is true. Set in the system.properties file (located in the /path/to/openidm/conf directory). |
| felix.fileinstall.disableConfigSave |
This property specifies whether changes to the active configuration will be persisted back to the on-disk JSON configuration files. The default is true. This property actually behaves in the opposite way to what one would expect; a value of true ensures that the on-disk JSON files are updated based on the active configuration and a value of false prevents the update of the JSON files. Set in the config.properties file (located in the /path/to/openidm/conf directory). |
Known issue
There is a known issue when modifying the configuration via both the Admin UI and on-disk JSON configuration files: OPENIDM-6588 (In a multi-node cluster updating a config file directly on one node does not update the corresponding file on other nodes). This issue causes the configuration for two nodes in a cluster to become out of sync at runtime.
This affects behavior as follows:
- Configuration changes performed via the REST interface or the Admin UI will propagate to all of the nodes within the cluster. The propagation of changes occurs via an event mechanism, which utilizes the shared repository to notify cluster instances of changes.
- Configuration changes made to the on-disk JSON files, regardless of which node they occur on, will only be applied if the openidm.fileinstall.enabled property is commented out or explicitly set to true. When applied, the changes are not propagated to other nodes in the cluster and will only take immediate effect on the node where the changes occurred.
Note
IDM 5 introduced changes to cluster management as detailed in: Release Notes › Core Releases. You should refer to the documentation in later versions (Integrator's Guide › Clustering, Failover, and Availability) and Best practice for clustering in IDM for advice on managing your clusters successfully in IDM 5 and later.
Making configuration changes
For a typical cluster configuration, you should apply changes to the cluster as follows in order to ensure the configuration remains consistent across all nodes at all times:
- Whenever possible, perform changes via the Admin UI in order to ensure that configuration updates are propagated to all nodes in the cluster. See OpenIDM Integrator's Guide › Configuring OpenIDM from the Admin UI for further information.
- When it is necessary to modify a configuration object that is not accessible via the Admin UI:
- Use a REST client (such as Postman or curl) to modify the configuration object directly. See OpenIDM Integrator's Guide › Configuring OpenIDM Over REST for further information. This is the preferred method.
- Modify the on-disk JSON files directly if you are unable to or prefer not to use REST. You should follow this process:
- Shut down all of the clustered-additional nodes and ensure that the openidm.fileinstall.enabled=false property has been set within the system.properties file on clustered-additional nodes.
- Modify the JSON files on the clustered-first node.
- Restart each of the clustered-additional nodes in order to reload the updated configuration from the repository.
See Also
OpenIDM Integrator's Guide › Configuring OpenIDM from the Admin UI
OpenIDM Integrator's Guide › Configuring OpenIDM Over REST
OpenIDM Integrator's Guide › Configuring OpenIDM for High Availability
OpenIDM Integrator's Guide › Disabling Automating Polling of Configuration Changes
Related Training
N/A