Using the Configuration Merge Feature

You can modify the default iris.cpf using a declarative configuration merge file. A merge file is a partial CPF that sets the desired values for any number of CPF parameters.

Configuration merge is useful for a number of purposes. A merge file lets you specify individual settings for instances deployed from the same source, supporting automated deployment and a DevOps approach. You can use configuration merge with containerized and noncontainerized InterSystems IRIS instances; for more information, see Configuration merge in deployment and Reconfigure an existing instance using configuration merge in Automating Configuration of InterSystems IRIS with Configuration Merge.

Configuration merge is very useful in automated deployment (on UNIX® and Linux systems only) because it makes the specified configuration changes before the new instance first starts, allowing you to customize the configurations of multiple instances deployed from the same container image or install kit. Automated deployment of multinode topologies can use multiple merge files to customize different groups of instances; for example, in automated deployment of a sharded cluster with compute nodes, you would apply different merge files for data node 1, the remaining data nodes, and the compute nodes in that order, and when deploying a mirror, you would apply different merge files for the primary, backup, and async members.

Automated reconfiguration of multiple instances can be achieved in the same way, by restarting groups of instances specifying the applicable merge file for each.

The iris merge command (available on Windows as well as UNIX and Linux systems) lets you use configuration merge to reconfigure a running instance. By automating application of the same merge file to multiple running instances using iris merge, you can simultaneously reconfigure all of those instances in the same way, applying the same set of configuration changes across your application or cluster. A single automated program can of course apply different merge files to different groups of instances (such as different mirror member or cluster nodes types) as described in the foregoing.

For an example of using a merge file, see the section that follows. For more information about using a merge file when deploying InterSystems IRIS containers, see Deploying an InterSystems IRIS Container with a Merge File. For information about using a merge file with the InterSystems Kubernetes Operator (IKO), see configSource: Create configuration files and a config map for themOpens in a new tab in Using the InterSystems Kubernetes Operator.

Configuration Merge Example

This example describes how to use a merge file at startup to modify the shared memory heap and the database cache in a noncontainerized instance. These settings are controlled by the gmheap and globals parameters respectively.

The first step is to create the merge file. The example file below in named config_merge.cpf, though any name or extension is valid. Note that the merge file uses the same syntax as a CPF.

# Example configuration merge file.

[config]
globals=0,0,800,0,0,0
gmheap=256000

Next, use the iris stop command to shut down the target instance for the merge.

$ sudo iris stop IRIS

Finally, restart the instance with ISC_CPF_MERGE_FILE set, as in the following script.

When this script runs, InterSystems IRIS modifies the iris.cpf file as specified in the config_merge.cpf file.

#!/bin/bash

# Start InterSystems IRIS with the necessary parameters (all on one line).
sudo ISC_CPF_MERGE_FILE=/merge_files/config_merge.cpf iris start IRIS

When the instance starts up, the merge is complete! Check that the iris.cpf file contains the desired values for the gmheap and globals settings.

[config]
...
errlog=500
globals=0,0,800,0,0,0
gmheap=256000
history=500,1024
...

Note:

If the merge file specified by ISC_CPF_MERGE_FILE is not present, instance startup displays an error message and continues.