Configuration updates in a cluster
IDM can read its configuration from the following locations:
-
Repository. Each instance reads its configuration from the
configobjectsandconfigobjectpropertiestables in a JDBC repository, or from theou=config,dc=openidm,dc=forgerock,dc=combaseDN in a DS repository. -
Filesystem. Each instance reads its configuration from the JSON files under its
confdirectory and stores the configuration locally in memory.In a clustered deployment, file-based configuration changes must be applied manually across all instances.
-
Memory. The configuration can diverge if an instance is cut from its cluster due to a networking issue or a misconfigured load balancer. In this case, configuration changes made in the repository might not be detected and the configuration in memory will not be updated.
There are two properties in the conf/system.properties
file that determine how configuration changes are handled for each instance:
- openidm.config.repo.enabled
-
When this property is set to
true, the instance reads configuration changes from the repository.The default setting (
# openidm.config.repo.enabled=false) indicates that the parameter is true. Uncomment that line to prevent the instance from reading configuration changes from the repository. - openidm.fileinstall.enabled
-
When this property is set to
true, the instance reads its configuration from the files in itsconf/directory.The default setting (
# openidm.fileinstall.enabled=false) indicates that the parameter is true. Uncomment that line to prevent the instance from reading file-based configuration changes.
|
Every node in the cluster must have the identical configuration setting. For example, if you set |
Repository-based configuration
Traditional clustered deployments share a mutable configuration that is read from a shared repository. The repository initially loads the configuration from the JSON files in the conf directory of the first instance that is configured in the cluster. However configuration changes are made, they are written to the repository, and the repository is the authoritative configuration source.
Therefore, a traditional clustered deployment generally has the following configuration:
openidm.config.repo.enabled=true openidm.fileinstall.enabled=false
File-based configuration
A file-based configuration lets you store the system configuration in a version-controlled filesystem, and to push a new version out to all nodes when the configuration changes. Using a file-based configuration therefore makes versioning and rolling out new configuration easier than pushing new configuration out over REST.
Container deployments typically require an immutable configuration that is read from a file system (such as a Docker image) and stored in memory. The file system is the authoritative configuration source and configuration changes are not written to the repository.
Therefore, a container deployment generally has the following configuration:
openidm.config.repo.enabled=false openidm.fileinstall.enabled=true
If file-based configuration is used, you must ensure that the configuration across instances remains consistent. Because the file-based configuration is not shared between instances, changes made to one node’s configuration must be applied manually to all nodes across the cluster.
By default, IDM polls JSON configuration files in each conf/ directory for changes. For security reasons, it is generally recommended that you disable automatic polling of configuration files to prevent untested configuration changes from disrupting your identity service.
For information on this parameter, refer to Disabling Automatic Configuration Updates.