Skip to main content

configSource: Create configuration files and provide a configmap for them

configSource: Create configuration files and provide a configmap for them

    name: name


The configSource field specifies a Kubernetes configmapOpens in a new tab containing one or more of the following:

  • A configuration merge file called common.cpf used to customize the configurations of InterSystems IRIS cluster nodes (data and compute) when deployed.


    For effective security, the common.cpf file (or both the data.cpf and compute.cpf files, below) should include the passwordHash parameter to set the default InterSystems IRIS password.

  • A configuration merge file called data.cpf used to further customize data nodes only; settings in this file override the same settings in common.cpf.

  • A configuration merge file called compute.cpf used to further customize compute nodes only; settings in this file override the same settings in common.cpf.

  • An InterSystems Web Gateway configuration file CSP.ini to be installed on webgateway (web server) nodes when deployed. A CSP.conf web server-specific configuration file can also be included.


All configuration merge (.cpf) files are optional, and they can be included in any combination. At least one, however, should be included so that the default InterSystems IRIS password can be reset.

Some of the configuration performed by the IKO, for example mirror configuration, uses settings than can be specified in merge files; any settings specified by the IKO override the same parameters set in user-provided .cpf files.

Kubernetes configmaps keep your containerized applications portable by separating configuration artifacts, such as these files, from container image content. To use configuration merge files to customize the configurations of the IrisCluster’s InterSystems IRIS nodes (data and compute), provide your own Web Gateway configuration file for the webgateway nodes, or both, you should:

Prepare the configuration merge files

The configuration parameter file, also called the CPF, defines the configuration of an InterSystems IRIS instance. On startup, InterSystems IRIS reads the CPF to obtain the values for most of its settings. The configuration merge feature allows you to specify a merge file that overwrites the values of one or more settings that in the default CPF that comes with an instance when it is deployed. For details, see Automating Configuration of InterSystems IRIS with Configuration Merge.

To use configuration merge when deploying your IrisCluster, customize the template common.cpf, data.cpf, and compute.cpf files provided in the samples/ directory by adding the CPF settings you want to apply to all InterSystems IRIS nodes, the data nodes, and the compute nodes (if included) respectively. The provided common.cpf template file contains only a sample passwordHash setting, described in the next section; the data.cpfand compute.cpf template files contain only a sample SystemMode setting, which displays text on the InterSystems IRIS Management Portal.

For numerous helpful examples of parameters you might customize for several purposes, see Useful Parameters for Automated Deployment in Automating Configuration of InterSystems IRIS with Configuration Merge. For example, the data nodes in a sharded cluster must be configured to allocate a database cache of the appropriate size; Deploy Sharded Clusters in “Useful Parameters” illustrates how you would add the [config] section globals parameter to the data.cpf file to configure the database caches of the data nodes at the size you calculated. This is shown in the following, with a value of 20 GB (the globals setting is in MB):

globals= 0,0,20480,0,0,0

Set the default InterSystems IRIS password

InterSystems IRIS is installed with several predefined user accounts, the initial password for which is SYS. For effective security, it is important that this default password be changed immediately upon deployment of all InterSystems IRIS containers. For this reason, even if you have no other reason to provide configuration merge files (which are optional), you should include at least a common.cpf containing the passwordHash parameter, as illustrated in the provided template common.cpf, to reset the default password on all InterSystems IRIS nodes, for example:


InterSystems publishes through the ICR the intersystems/passwordhash image, from which you can create a container that generates the hash for you; for more information about this, the passwordHash parameter, and the default password, see Authentication and PasswordsOpens in a new tab in Running InterSystems Products in Containers.


The passwordHash parameter does not change the default password for the CSPSystem account, which is used by InterSystems IRIS and the local Web Gateway instance installed with it to communicate with each other, and by default provides management access to the Web gateway. For more information, see the following section.

Prepare the Web Gateway configuration file

As described in Configure the Web Gateway in the Web Gateway Configuration Guide, the Web Gateway’s configuration is managed using the Web Gateway management pages, but contained in the CSP.ini file (much as an InterSystems IRIS instance’s configuration is contained in the iris.cpf file). The CSP.ini file you include in your configmap, or the one generated by the IKO if you do not include one, is automatically installed on every webgateway node deployed. If you have experience with the Web Gateway, you can use a CSP.ini from an existing installation as a template and prepare one to be installed on your webgateway nodes by the IKO. You can also supply your own CSP.conf file, which contains the Web Gateway’s Apache or Nginx-specific configuration. If your deployment includes multiple webgateway nodes, bear in mind the information in the following sections when deciding whether to supply your own configuration files or allow the IKO to generate them:

  • Populating the remote server pool in the CSP.ini file

  • Updating the configuration of multiple Web Gateways

  • Changing the Web Gateway’s default password

  • Securing Web Gateway connections to remote InterSystems IRIS servers

Populating the remote server pool in the CSP.ini file

Because an IrisCluster does not include a Kubernetes-based mechanism for distributing application connections, deployed web server (webgateway) nodes provide the only means of controlling this distribution within the IrisCluster specification. (You can also deploy a custom load balancer on the Kubernetes cluster hosting the IrisCluster or use a third party-tool to distribute connections.) For this reason, ensure that the remote server pool in the configuration file, which specifies the InterSystems IRIS instances to which the Web Gateway directs incoming connections from the web server, is populated according to the relevant best practice for distributing application connections, as follows:

  • If the deployment is a sharded cluster and includes compute nodes, add all data and compute nodes to the pool; if there are no compute nodes, add all data nodes.

  • If the deployment is a distributed cache cluster, add all compute (application server) nodes to the pool.

  • If the deployment is a standalone instance, it should be the only remote server in the pool.


Web Gateway connections to mirrored data nodes are automatically mirror aware, that is, connections are always to twhichever failover member is the current primary.

It is possible to populate the remote server pool before deployment because the names assigned to IrisCluster nodes always follow the same pattern, which is clustername-nodetype-0. For example, in an IrisCluster called myCluster, data node 1 of a sharded cluster, the data server of a distributed cache cluster, and a standalone instance would all be called myCluster-data-0 unless mirrored, in which case the primary (as deployed) would be myCluster-data-0-1 and the backup myCluster-data-0-2. Other nodes are named in the same format (except that they cannot be mirrored), for example myCluster-compute-0. Therefore, if an IrisCluster of this name was a sharded cluster with four mirrored data nodes, four compute nodes, an arbiter, and two webgateway nodes, they would be named as shown in the following table. The data nodes that would go in the remote server pool in the Web Gateway configuration file — that is, the deployed mirror primaries – are indicated by *; all of the compute nodes would be added to the pool.


If you included one or more DR async members in each mirror using the mirrorMap field, they would be named myCluster-data-0-3 and so on in sequence, but the Web Gateway never connects to async mirror members.

If you do not include a CSP.ini file in your configmap, the IKO will generate one appropriate for the cluster and install it on every webgateway node, populating the remote server pool as described in the foregoing. The IKO can also generate a CSP.conf file if you do not provide one.


InterSystems recommends the use of TLS to secures all connections in your deployment. The CSP.ini file generated by the IKO secures connections between webgateway nodes and data and compute nodes if you so specify in the tls section of the IrisCluster definition. If you provide your own CSP.ini and prepopulate the remote server pool, you can include TLS for each entry; if you do not prepopulate, you can configure it when you populate the remote server pools using the Web Gateway management pages on the individual nodes.

Updating the configuration of multiple Web Gateways

As described in Connect to the IrisCluster, the serviceTemplate field creates one or more Kubernetes servicesOpens in a new tab that expose the first stateful set in the pod for each deployed node type to the network through an external IP address. This includes webgateway nodes, which means that if you have deployed just one, you can always access its management pages to change its configuration by loading the URL http://external-ip:80/csp/bin/Systems/Module.cxw in your browser. (For nodes deployed from the webgateway-lockeddown image, load http://external-ip:52773/csp/bin/Systems/Module.cxw.) If you want to make configuration changes across multiple webgateway nodes, however, you have three options:

  • If you provided your own CSP.ini file, use the procedure described in Create a configmap for the configuration files for modifying the CSP.ini or .cpf files on deployed nodes.

  • Create a similar service for each of the webgateway nodes that exposes it through an external IP address, then use the URL above to make the changes on each node separately.

  • Directly modify the CSP.ini file on each pod by using the kubectl exec command to open a shell or edit the file within the container.


Be sure to review information about securing webgateway connections in Changing the Web Gateway’s default password and tls: Configure TLS security.)

Changing the Web Gateway’s default password

The predefined CSPSystem account on an InterSystems IRIS instance is used for communication between an InterSystems IRIS instance and the local InterSystems Web Gateway instance installed with it, and by default is used for access to the local Web Gateway’s configuration through its management pages. For effective security, you must change the default password for this account (along with the other predefined accounts) on both an InterSystems IRIS instance and its local Web Gateway instance either as part of deployment or immediately after; Authentication and Passwords in Running InterSystems Products in Containers provides details on this topic and instructions for making these changes in an InterSystems IRIS container.

In the case of a webgateway node deployed by the IKO, if you provide your own CSP.ini file, ensure that if CSPSystem (or any other predefined account) is specified as the management access account, the password is not SYS; if it is, change it. You can also change the access credentials to any username and password you choose. Additionally, while the Web Gateway encrypts the management access password in the CSP.ini file on first starting up, including it in plain text could expose it on disk or the network, so the best practice is to make sure it is encrypted in the file you provide; you can do this after you change it, if necessary, by starting up a local test Web Gateway instance with your configuration file in place, which encrypts the password.

Changing the credentials for remote servers

In a separate measure from the Web Gateway management access credentials discussed in Changing the Web Gateway’s default password, each entry in a Web Gateway’s remote server pool specifies the username and password of an account on the specified InterSystems IRIS instance to be used to authenticate to the instance. If you provide your own CSP.ini, ensure that the specified account is a secure one that does not use the default password (see Authentication and Passwords). You can then specify this account for each remote server in your CSP.ini (clearly it is simplest to use the same account for all).

The CSP.ini generated by the IKO does not configure credentials for the remote server pool entrues. To change this, which you must for effective security, use either the second method described above for updating multiple Web Gateway configurations (creating services) or the third (using kubectl exec).

Create a configmap for the configuration files

Create a Kubernetes configmap specifying the files, using a command like this:

$ kubectl create cm iris-cpf --from-file common.cpf --from-file data.cpf 
    --from-file compute.cpf --from-file CSP.ini --from-file CSP.conf

Update configSource:

In the IrisCluster definition file, specify the name of the configmap as the value for configSource for the name field within configSource, for example:

    name: iris-cpf

If you did not create a configmap, do not specify a value for this field.

Modify the configmap to reconfigure nodes

To modify the *.cpf or CSP.* files on deployed nodes, you can edit the configmap to make one or more changes to one or more of the files it contains. For example, this command would allow you to modify any or all of the files included in the kubectl create command illustrated above:

kubectl edit configmap iris-cpf

When you modify the configmap, your changes are automatically pushed to the affected *.cpf and/or CSP.* files in the pods. Due to continuous monitoring of merge files in InterSystems IRIS containers (see How do I reconfigure an existing instance using configuration merge? in Automating Configuration of InterSystems IRIS with Configuration Merge and Configuring the Web Gateway in Running InterSystems Products in Containers) your changes are then merged into the configurations of the data, compute, and/or webgateway nodes in the IrisCluster.


For webgateway nodes only, in order for the configuration changes to take effect you must do one of the following:

  • Reload the Web Gateway instance’s configuration (which can be done programmatically).

  • Restart the instance by deleting the pod, for example:

    kubectl delete pod sample-webgateway-0

Bear in mind that when you edit the configmap, you will see settings added to your original files by the IKO; the contents will not be exactly the same as the source files you specified, but should be recognizable throughout.

FeedbackOpens in a new tab