IDM 7.3.1

Configuration updates in a cluster

IDM can read its configuration from the following locations:

  • Repository. Each instance reads its configuration from the configobjects and configobjectproperties tables in a JDBC repository, or from the ou=config,dc=openidm,dc=forgerock,dc=com baseDN in a DS repository.

  • Filesystem. Each instance reads its configuration from the JSON files under its conf directory 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 its conf/ 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 openidm.config.repo.enabled=true, openidm.fileinstall.enabled=false on one node, you must set exactly the same options on every node in the cluster.

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.