configSource: Create configuration files and generate a configmap from them
configSource: Create configuration files and generate a configmap from them
configSource:
name: configmap-name
Optional
The configSource field specifies a Kubernetes configmapOpens in a new tab generated from 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.
-
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.
-
A Web Gateway configuration file called CSP.ini to be installed in the webgateway container on web server nodes when deployed, or a CSP-merge.ini merge file to modify the CSP.ini file generated by the IKO. A CSP.conf web server-specific configuration file can also be included.
All configuration merge (*.cpf and CSP.*) files are optional, and they can be included in any combination. For effective security, however, you must include at least a common.cpf file (or instead both a data.cpf and a compute.cpf file) containing the passwordHash parameter to reset the default InterSystems IRIS password.
Kubernetes configmaps keep your containerized applications portable by separating configuration artifacts, such as the content of these files, from container image content. For an IrisCluster, you generate a configmap from the contents of the configuration files you specify and identify it using the configSource field. The IKO then uses the specified configmap during deployment to generate a separate configmap for each node type in the cluster, which in turn is used to create a local configuration file on each node of that type.
Some of the configuration performed by the IKO, for example mirror configuration, uses settings that can be specified in merge files; any settings specified by the IKO are overwritten by the same parameters in user-provided .cpf files.
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 in, or adds settings to, 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 passwordHashOpens in a new tab setting, described in the next section; the data.cpf and compute.cpf template files contain only a sample SystemModeOpens in a new tab setting, which displays text on the InterSystems IRIS Management Portal.
For 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, as calculated by you before deployment; the following illustrates how you would add the [config] section globalsOpens in a new tab parameter to the data.cpf file to configure the database caches of the data nodes to be 20 GB (the globals setting is in MB):
[StartUp]
SystemMode=my-IrisCluster
[config]
globals= 0,0,20480,0,0,0
Set the default InterSystems IRIS password
InterSystems IRIS is installed with several predefined user accountsOpens in a new tab, 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 passwordHashOpens in a new tab parameter, as illustrated in the provided template common.cpf, to reset the default password on all InterSystems IRIS nodes, for example:
[Startup]
PasswordHash=dd0874dc346d23679ed1b49dd9f48baae82b9062,10000,SHA512
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 predefined account, which by default provides management access to the Web Gateway in webgateway nodes and webgateway sidecar containers. For more information, see the following section.
Prepare the Web Gateway configuration files
As explained in Web Access Using the Web Gateway ContainerOpens in a new tab in Running InterSystems Products in Containers, the InterSystems Web Gateway container, which includes both a web server and a Web Gateway instance, has two different purposes in containerized deployments, as follows:
-
To provide a packaged web server component for distributing application connections across multiple InterSystems IRIS nodes, as in a distributed cache or sharded cluster.
-
To serve as a dedicated web server for a containerized InterSystems IRIS instance’s built-in web applications, including the web-based Management Portal.
Your IrisCluster can include one or more webgateway nodes for the first purpose, and a sidecar Web Gateway container in each data and/or compute node pod for the second.
A Web Gateway’s configuration, which is contained in its CSP.ini file, includes server access profiles specifying the InterSystems IRIS servers (instances) with which it interacts and application access profiles specifying which application requests are directed to which of these instances. For a webgateway node interacting with multiple InterSystems IRIS nodes, applications may be evenly or differentially distributed across them. However, a dedicated (sidecar) Web Gateway container has only the server access profile for the instance it is dedicated to and is intended for built-in applications on that instance only, so all web URLs are directed to the server identified by that profile. For these reasons, the CSP.ini files for the two types of Web Gateway have many differences.
The IKO generates the CSP.ini file for all dedicated Web Gateway containers. For webgateway nodes, you have two options for specifying a CSP.ini file in your configmap to be automatically installed on every webgateway node deployed: you can let the IKO generate the CSP.ini file, or you can provide your own. In using the latter option, 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 containing the Web Gateway’s Apache or Nginx-specific configuration, but this is not typically done when an IKO-generated CSP.ini file is used, in which case the IKO also makes the needed changes in the default CSP.conf file.
Creating your own CSP.ini file for web server webgateway nodes is practical if your IrisCluster definition includes limited number of data, compute, and webgateway nodes. In more complex deployments, InterSystems recommends using the IKO-generated file because of the following advantages:
-
The IKO-generated CSP.ini file automatically distributes application connections according to best practices, as described in Populate the server access profiles in the CSP.ini file. This can be done in a user-provided CSP.ini, but creating such a file can be time-consuming and error-prone. Assuming you do not supply your own CSP.conf file, IKO also generates one that configures the needed application paths on the web server.
-
Using the IKO-generated file allows you to include a CSP-merge.ini file in your configmap, which provides the easiest and most effective means of updating the configurations of multiple webgateway nodes in a single operation, as described in Synchronize reconfiguration of multiple webgateway nodes.
-
The IKO-generated CSP.ini file automatically secures connections between webgateway nodes and data and compute nodes with TLS if you so specify in the tls section of the IrisCluster definition, as well as configuring the Web Gateway’s credentials for authenticating to the InterSystems IRIS instances specified in its server access profiles according to the information you provide in the loginSecret field.
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:
Populate the server access profiles in the CSP.ini file
Deployed web server (webgateway) nodes provide a means of distributing application connections 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.) To take advantage of this, use the IKO-generated CSP.ini, or in a user-provided file ensure that the server access profilesOpens in a new tab, which specify the InterSystems IRIS instances to which the Web Gateway directs incoming connections from the web server, are populated according to the relevant best practice for distributing application connections, as follows:
-
If the deployment is a sharded cluster, create server access profiles for all data nodes and compute nodes (if any).
-
If the deployment is a distributed cache cluster, create profiles for all compute (application server) nodes.
-
If the deployment is a standalone instance, its profile should be the one in the configuration.
Web Gateway connections to mirrored data nodes are automatically mirror aware, that is, connections are always to whichever failover member is the current primary.
As noted in Understand IrisCluster node naming, it is possible to populate the server access profiles before deployment because the names assigned to IrisCluster nodes are determinate, following the pattern clustername-nodetype-N (or clustername-data-N-N in the case of mirrored data nodes). For example, in a sharded cluster with four mirrored data nodes and four compute nodes, the server access profiles would include the four data node primaries and four compute nodes, which would be named as follows:
myCluster-data-0-0 myCluster-data-1-0 myCluster-data-2-0 myCluster-data-3-0 |
myCluster-compute-0 myCluster-compute-1 myCluster-compute-2 myCluster-compute-3 |
InterSystems recommends the use of TLS to secure 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.
Secure Web Gateway management access
Access to the Web Gateway’s management pages can be secured in three ways: by specifying the required authentication credentials, by restricting the IP addresses from which the pages can be accessed, and by disabling access entirely. InterSystems recommends that you review and update these settings as follows:
On webgateway nodes:
-
If you provide your own CSP.ini file, you can make your desired changes to all of these settings in the [SYSTEM]Opens in a new tab section of the file:
-
If you want to disable management access altogether, which means the configuration can be changed only by modifying the CSP.ini file in your configmap and using the kubectl replace command to propagate your changes to the webgateway nodes, set the SM_Forms parameter to Disabled. Otherwise, address the next two items.
-
Specify authentication credentials of your choice using the Username and Password parameters. If the password is in plain text, it will be base64-encoded and given a prefix of [[[ when each Web Gateway starts up; if the prefix is already present, the password will be used as-is.
-
The System_Managersetting, in the same section, specifies a list of IP addresses corresponding to machines permitted to access the management pagesOpens in a new tab; if it is omitted, access is limited to the local host. Set this according to your expectations regarding the need for access to the management pages.
-
-
If you use the IKO-generated CSP.ini file, the specified authentication credentials are CSPSystem/SYS (with the password encrypted). Because this is one of the predefined accountsOpens in a new tab on InterSystems IRIS and is thus well known, InterSystems recommends changing these credentials. You can modify them as well as the System_Manager setting (which by default allows all IP addresses), or disable access to the management pages using the SM_Forms parameter, by including a CSP-merge.ini file in your configmap, with contents like one of the following:
[SYSTEM] SM_Forms=Disabled
[SYSTEM] Username=username Password=password System_Manager=IPaddress1,IPaddress2,...
In webgateway sidecar containers:
-
The settings described above, including the authentication credentials. are the same in the IKO-generated CSP.ini for webgateway sidecars as in the IKO-generated CSP.ini for webgateway nodes. If you use the latter, you can modify the file webgateway sidecar configuration file along with the webgateway node file by including a CSP-merge.ini file in your configmap as described above.
-
If you do not use the IKO-generated CSP.ini for webgateway nodes, you can modify the CSP.ini in each sidecar using the kubectl exec command, as described in Synchronize reonfiguration of multiple webgateway nodes.
Update and coordinate server authentication credentials
To interact with an InterSystems IRIS instance, the Web Gateway must authenticate to it, which is why each Web Gateway server access profile specifies the username and password of an account on the InterSystems IRIS instance it specifies to be used for this purpose.
To ensure that all Web Gateways can authenticate to InterSystems IRIS as needed out of the box, the IKO-generated CSP.ini files for the webgateway nodes and the webgateway sidecar containers both specify the credentials _SYSTEM/SYS for this purpose in the server access profiles for the data nodes and compute nodes to which they will distribute application connections and the InterSystems IRIS container they are dedicated to, respectively. This is one of the well-known predefined accountsOpens in a new tab for which the password should be changed during or immediately after deployment (for details, see Authentication and PasswordsOpens in a new tab in Running InterSystems Products in Containers).
For both for the webgateway nodes and the webgateway sidecar containers, you can use the loginSecret field to change the password, or both the username and password, in all server access profiles in both IKO-generated CSP.ini files. This must be the same for both he webgateway nodes and the webgateway sidecar containers due to the need for coordination with the InterSystems IRIS nodes (see below). If you provide your own CSP.ini for the webgateway nodes, the loginSecret field has no effect; instead, specify a secure account that does not use the default password in each remote server access profile ([server-name] sectionOpens in a new tab). This must be the same for all server profiles as well as matching the credentials you supply in a loginSecret for the webgateway sidecar containers,
Once you have determined the server access credentials to be specified using the loginSecret field (and possibly your own CSP.ini file), you must ensure that these credentials are valid on the data and compute nodes with which the webgateway nodes and sidecars will be interacting. To do this, create the necessary entry in the data.cpf, compute.cpf, or common.cpf you include in your configmap, as described in Prepare the configuration merge files, as follows:
-
If you are including only a password in your login secrets, thereby retaining the default username _SYSTEM (or you provided this username in your own CSP.ini), you need use only the PasswordHash parameter in the common.cpf file you provide, as described in Set the default InterSystems IRIS password, to change all default passwords, including the one for _SYSTEM, on all of the targeted InterSystems IRIS nodes to the encrypted value you supply.
-
If you specified a new username as well, you must use the CreateUser action parameter to create the account on all of the targeted instances; you can find an example of using this parameter to create an account at deployment in Create, Modify and Delete Security ObjectsOpens in a new tab in Automating Configuration of InterSystems IRIS with Configuration Merge.
Synchronize reconfiguration of multiple webgateway nodes
As described in Connect to the IrisCluster, the serviceTemplate definition creates one or more Kubernetes servicesOpens in a new tab that expose a pod in the first StatefulSetOpens in a new tab of certain node types 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, where external-ip is the IP address exposed by the relevant service. (For nodes deployed from the webgateway-lockeddown image, specify port 52773 instead of 80 in the URL.)
If you have deployed multiple webgateway nodes, you can make configuration changes across all of them by modifying a file in your configmap and using the kubectl replace command to propagate your changes to the webgateway nodes. In this regard, an advantage of using the IKO-generated CSP.ini file is that you can include in your configmap a file called CSP-merge.ini. This file works in the same way as the .cpf files described in Prepare the configuration merge files, that is, by replacing values of existing parameters in, or adding parameter/value pairs to, the IKO-generated CSP.ini, both when you first deploy your IrisCluster and when you subsequently reconfigure the webgateway nodes. If you supply your own CSP.ini, you must make your updates in the entire file when you edit the configmap. Using the IKO-generated file and CSP-merge.ini lets you make updates more efficiently and (assuming you track of them using change control) more easily review the update history.
When you use the CSP-merge.ini file to modify the IKO-generated CSP.ini file at deployment or later, the settings you include in CSP-merge.ini are also applied to the CSP.ini file in the dedicated (sidecar) webgateway containers. Generally speaking, due to the fact that the sidecar webgateway file contains only the LOCAL server profile and only built-in InterSystems IRIS paths in its application profiles, while the webgateway node file does not contain the former and typically not the latter, changes intended for the webgateway nodes should not affect the dedicated (sidecar) webgateway containers. However it is important to consider this possibility when updating the IKO-generated webgateway node CSP.ini using the CSP-merge.ini file.
If you deploy with the IKO-generated CSP.ini file, when you modify the IrisCluster by updating the definition to change the number of data or compute nodes or add or remove iam nodes and then reapply the cluster definition, a new CSP.ini file, reflecting the changes (including in the distribution of application connections) is automatically generated and installed on the webgateway nodes; any changes you made to the previous file using CSP-merge.ini will have to be made again if still desired, either when reapplying the modified definition or later reconfiguring the nodes as described above.
Be sure to review information about securing Web Gateway connections in Secure Web Gateway management access ,Update and coordinate server authentication credentials, and tls: Configure TLS security.
If you supply your own the CSP.ini file, you can modify this file on individual webgateway nodes in the following ways:
-
Define a service similar to the one created by the serviceTemplate for each webgateway pod that exposes it through an external IP address.
-
Directly modify the CSP.ini file on each pod by using the kubectl exec command to open a shell and edit the file within the container.
Create a configmap for the configuration files
Create a Kubernetes configmap specifying the files you have prepared, using a command like this:
$ kubectl create cm my-iriscluster-config --from-file common.cpf --from-file data.cpf
--from-file compute.cpf --from-file CSP.ini --from-file CSP.conf
To have the IKO generate the CSP.ini file and include a configuration merge file for the webgateway nodes (as described in Prepare the Web Gateway configuration files) you would replace --from-file CSP.ini in the above example with --from-file CSP-merge.ini, as follows:
$ kubectl create cm my-iriscluster-config --from-file common.cpf --from-file data.cpf
--from-file compute.cpf --from-file CSP-merge.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:
configSource:
name: my-iriscluster-config
If you did not create a configmap, do not specify a value for this field.
Modify configmap to reconfigure nodes
To modify the *.cpf or CSP.* settings of nodes in the deployed cluster, edit the node-specific configmap generated by the IKO to make one or more changes to the settings it contains. For instance, if you deploy a cluster called my-iriscluster and the configmap you specify in its configsource field was generated (using the kubectl create command as illustrated above) from a data.cpf file, a compute.cpf file, and either a CSP.ini file or a CSP-merge.ini file, you could modify or remove any or all of the settings in the source files, and add new ones, by using a command like the following:
kubectl edit configmap my-iriscluster-config
To push your changes to the affected *.cpf and/or CSP.* files in the pods, use a kubectl replace ommand like the following to force the IKO to reprocess the spec, incorporating the modified configmap.
kubectl replace -f my-iriscluster.yaml
The kubectl replace command reprocesses the definition even when it has not been changed, which is needed in this case because it is the configmap that has been modified, not the definition.
In addition to the settings you specified, the contents of the deployed configmaps contain settings added by the IKO. Any settings specified by the IKO are overwritten by the same parameters in user-provided .cpf files.
As described in Synchronize reconfiguration of multiple webgateway nodes, the settings already in the webgateway node configmap depend on whether you supplied your own CSP.ini file, as described in Prepare the Web Gateway configuration files, or had the IKO generate the CSP.ini file and supplied a CSP-merge.ini file to modify it (as recommended); in either case you can make whatever changes you want by either modifying settings already in the configmap or adding new ones.
When data nodes are mirrored, the IKO generates a separate configmap for the nodes in each mirror, for example my-iriscluster-data-0 for node 1 of a mirrored sharded cluster, my-iriscluster-data-1 for the second data node, and so on. These correspond to the node naming scheme for mirrored configurations as described in Understand IrisCluster node naming.