configSource: Create configuration files and generate a configmap from 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.

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:

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.