Best Practices for Configuration Merge

InterSystems recommends keeping the merge files involved in any application of the configuration merge feature under version control. Version control provides a record of all configuration changes, from deployment forward, over the life of an instance or a multi-instance topology. It also allows you to restore a previous configuration and easily share merge files with other users. You can also easily update your automated deployment or reconfiguration process, which uses configuration merge, by updating the merge files applied with the latest version of the merge file. You could also require users to get the latest version of the appropriate merge file before deploying or reconfiguring an instance, even in the case of individual instances used for purposes such as development or testing. This would ensure all deployments and reconfigured instances have identical configurations which match a central specification, regardless of if it is a single instance or multiple instances.

If you use configuration merge, the strongly recommended best practice is to confine all configuration changes to this method — even when this means, for example, using iris merge to change just one or two parameters on one instance. If changes to the instance’s CPF are not made with configuration merge, assuming you version and store the merge files, the changes won’t be source controlled, and a record of those changes will not exist. This poses a risk of configuration merge overwriting these changes made by other means, and with no record of the changes, they won’t be recovered. In the case of a single instance, for example, a lone development instance, this risk may be acceptable; where a record of configuration changes to roll back to in the event of a problem is not necessarily needed. However, in the case of many instances or in a production environment, this risk is not acceptable. Therefore, if you confine all configuration changes to configuration merge, you can avoid the possibility and risk of configuration merge overwriting changes made by other means.

In a container, the potential of configuration merge overwriting changes made by other means is very great due to the continuous monitoring and merging of the merge file identified by the ISC_CPF_MERGE_FILE variable, as described in The iris merge Command. This allows you to use configuration merge and a central repository of merge files to apply further changes to existing instances simply by updating their merge files at any time. However, if the configuration parameters included in the merge file have been changed on the instance in the container by another method since deployment, the update merge can erase those changes, of which there may not be any record. Confining all configuration changes to configuration merge avoids this. (If the merge file does not exist, startup displays an error message and continues.)

If you do not confine changes to configuration merge, you can avoid the possibility of configuration merge making unwanted changes by including in your automation (using, for example, the iris-main --after option) the scripting of either or both of the following after instance startup:

• The deletion of the ISC_CPF_MERGE_FILE environment variable in each deployed container. (If the merge file does not exist, startup displays an error message and continues.)

• The replacement of the merge file in each container with an empty file.