Introduction to Configuration Merge

Configuration Merge

The configuration merge feature lets you make as many changes as you wish to the configuration of any InterSystems IRIS instance in a single operation. To use it, you simply record the changes you want to make in a declarative configuration merge file and apply that file to the instance, when it is deployed or at any later point. Configuration merge can easily be used to automatically deploy multiple instances with varying configurations from the same container image or kit, as well as to simultaneously reconfigure multiple running instances, enabling automated reconfiguration of clusters or other multi-instance deployments. Configuration merge can be used in deployment of any InterSystems IRIS instance, containerized or locally installed, on any supported UNIX® or Linux platform, including Linux cloud nodes. You can reconfigure running instances using configuration merge on both UNIX/Linux and Windows platforms.

For examples of configuration merge files used to deploy containers, see Deploying an InterSystems IRIS Container with a Merge File. The Configuration Parameter File Reference contains a comprehensive description of all InterSystems IRIS configuration parameters.

InterSystems IRIS Configuration

The configuration of an InterSystems IRIS instance is determined by a file in its installation directory named iris.cpf, which contains configuration parameters as name/value pairs. Every time the instance starts, including for the first time after it is deployed, it reads this configuration parameter file, or CPF, to obtain the values for these settings. This allows you to reconfigure an instance at any time by modifying its CPF and then restarting it.

For example, the globals setting in the [config] section of the CPF determines the size of the instance’s database cache. The setting in the CPF of a newly installed instance specifies an initial cache size equal to 25% of total system memory, which is not intended for production use. To change the size of the database cache, you can open the instance’s CPF in any text editor and specify the desired cache size as the value of globals, then restart the instance. Most parameters can be changed using other methods; for example, you can also modify the value of globals using the Management Portal or using the methods in the persistent class Config.configOpens in a new tab. Updating an instance’s CPF, however, is the only general mechanism that lets you make multiple configuration changes to an instance in a single operation and automate the simultaneous configuration of multiple instances.

For an overview of the use and contents of the CPF, see the Configuration Parameter File Reference.

Configuration Merge File

A configuration merge file is a partial CPF that contains any desired subset of InterSystems IRIS configuration parameters and values or an [Actions] section or both. When a merge file is applied to an instance with configuration merge, there are two types of operations that can occur. The first type is updating settings in the instance’s CPF corresponding to the InterSystems IRIS configuration parameters and values specified in the merge file, see Merge Updates. The second type is creating, deleting, or modifying InterSystems IRIS objects corresponding to the contents of the [Actions] section, see Merge Actions.

A merge file has the same syntax as a CPF (described in the CPF Format section), and can have any name and extension. The merge file may contain any of the parameters found within the CPF, though it is not necessary to include the values you are not changing.

Unlike the CPF, a merge file can contain duplicates of the same section and parameter. In this case, InterSystems IRIS prioritizes the value closer to the end of the file, which allows you to create a template merge file. For example, if you keep generally desired values at the top of the file and append instance-specific values at the bottom, InterSystems IRIS will prioritize the instance-specific values when reading the merge file.

Merge Updates

When a merge file is applied to an instance with configuration merge to update InterSystems IRIS configuration parameters, those settings are merged into the instance’s CPF, replacing the values, as if you had edited the CPF and changed the values manually. If a parameter in the merge file is not present in the original CPF, it is simply added in the appropriate place.

For example, the data and compute nodes in a sharded cluster typically require with a database cache that is much larger than that generally configured for other purposes, and have more shared memory configured as well. To configure an instance to have a larger database cache and more shared memory when deployed, or to reconfigure an existing instance this way, you can apply a configuration merge file that includes the globals parameter (which specifies the size of the database cache) and the gmheap parameter (which specifies the amount of shared memory) with the desired values; these replace the default values in the CPF of the instance. The following illustrates the use of a merge file to update both the parameters when deploying an instance:

For examples of using configuration merge to update configuration parameters, see Useful Update Parameters in Automated Deployment.

Merge Actions

In addition to changing the values of configuration parameters, configuration merge can create, modify, and delete dozens of different InterSystems IRIS objects, such as namespaces and databases; users, roles, and resources; and mirrors and mirror members. This is done using the parameters in the [Actions] section, which is valid only in a merge file and does not appear in (and cannot be added to) an instance’s CPF. For example, to add a global mapping to an instance, you would include in the merge file an [Actions] section containing the CreateMapGlobal parameter. The parameters in this section, which create, modify, and delete system objects, are sometimes called action parameters, to distinguish them from those that update parameter values, which are known as update parameters.

Action parameters can be used to manage objects on both new and existing instances. The operations specified by action parameters are idempotent, meaning that they are executed only if they would result in a change. More specifically:

• A Create action is not executed if the specified object exists.

• A Modify action is not executed if the specified object does not exist. (If the object exists but the action does not add to/modify the properties of the object, the action is executed but to no effect.)

• A Delete action is not executed if the specified object does not exist.

• A Config action is not executed if the object exists and the action does not add to/modify the properties of that object; if the object does not exist, or it exists and the action adds to/modifies its properties, the action is executed.

Action parameters are very useful in deployment, for example to configure several deployed instances as a mirror using the ConfigMirror action and the MirrorSetName and MirrorDBName properties of the CreateDatabase action, enabling the new mirror to be fully operational, with mirrored databases in place, immediately following deployment. On the other hand, when used in reconfiguring an existing instance with the iris merge command, action parameters can enable you to immediately make changes that would otherwise require a Management Portal procedure or a class method call; notable examples are adding an arbiter to an existing mirror with adding a new database to an existing mirror using the MirrorSetName and MirrorDBName properties of the ModifyDatabase action, , which must be done on the running primary instance.

The operations performed by action parameters are effected by calling methods of classes in the Config and Security classes and in the SYS.DatabaseOpens in a new tab and %SYSTEM.SQL.SecurityOpens in a new tab classes, as well as two SQL commands.

For examples of the use of action parameters, see Useful Action Parameters in Automated Deployment.

For the list of available action parameters, see [Actions] Parameter Reference.

Configuration Merge Uses

There are two primary uses for configuration merge:

• Configuring multi-instance topologies and stand-alone instances during deployment.

• Reconfiguring deployed multi-instance topologies and stand-alone instances.

For more information on using configuration merge during deployment, see Configuration Merge in Deployment.

For more information on using configuration merge to reconfigure existing InterSystems IRIS instances, see Reconfigure an Existing Instance Using Configuration Merge.

See Also

• Best Practices for Configuration Merge