Using the InterSystems Kubernetes Operator (Version 3.7)

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.

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.

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

• Secure Web Gateway management access

• Update and coordinate server authentication credentials

• Synchronize reonfiguration of multiple webgateway nodes

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.

image:

      image: containers.intersystems.com/intersystems/irislatest-em

Required

The image field specifies the URL (registry, repository, image name, and tag) of the InterSystems IRIS image from which to deploy data node containers. The example above specifies an InterSystems IRIS image from the InterSystems Container Registry (ICR). The registry credentials in the secret specified by the imagePullSecrets field are used for access to the registry.

The image fields in other node definitions are also required, and are used in the same way. The sam node definition has four optional additional image fields for third-party images.

updateStrategy:

      updateStrategy:
        type: {RollingUpdate|OnDelete}

Optional

Overrides the top level updateStrategy setting to specify the Kubernetes update strategyOpens in a new tab used for the stateful setsOpens in a new tab representing this node type only. The value can be either RollingUpdate (the default) or OnDelete.

preferredZones:

      preferredZones:
        - zoneN
        - ...

Optional

Specifies the zone or zones in which data nodes should be deployed, and is typically used as follows:

• If mirrored is set to true and at least two zones are specified, Kubernetes is discouraged (but not prevented) from deploying both members of a failover pair in the same zone, which maximizes the chances that at least one is available, and is therefore the best practice for high availability. Bear the following mind, however:

  • Deploying the members of a failover pair in separate zones is likely to slightly increase latency in the synchronous communication between them.

  • Specifying multiple zones for the data nodes means that all of the primaries might not be deployed in the same zone, resulting in slightly increased latency in communication between the data nodes.

  • Specifying multiple zones for data nodes generally makes it impossible to guarantee that nodes of other types (compute, Web Gateway, SAM, IAM) are in the same zone as all of the data node primaries at any given time regardless of your use of preferredZones in their definitions, increasing latency in those connections as well.

  Under most circumstances these interzone latency effects will be negligible, but with some demanding workloads involving high message or query volume, performance may be affected. If after researching the issue of interzone connections on your Kubernetes platform and testing your application thoroughly you are concerned about this performance impact, consider specifying a single zone for your mirrored data nodes.

  Regardless of the zones you specify here, you should use the preferredZones field in the arbiter definition to deploy the arbiter in a separate zone of its own, which also helps optimize mirror availabilityOpens in a new tab.

• The data nodes of an unmirrored cluster are typically deployed in the same zone to minimize latency. If mirrored: false and your Kubernetes cluster includes multiple zones, you can use preferredZones to follow this practice by specifying a single zone in which to deploy the data nodes.

• The value of the preferredZones field in the compute definition, if included, should ensure that the compute nodes are deployed in the same zone or zones as the data nodes to minimize latency (see Plan Compute NodesOpens in a new tab in the Scalability Guide).

podTemplate:

      podTemplate:
        spec:
          args:        

Optional

Specifies overrides and additions to the default pod templateOpens in a new tab applied to the data node pods (and to the pods of other node types in their respective definitions). Because containers are run only within a pod on Kubernetes, a pod template can specify the fields that define numerous Kubernetes entities, including the fields defining a containerOpens in a new tab, which makes it useful for many purposes. Several examples of using containers fields are provided in the following:

• Apply one or more labels to the pod:

  podTemplate:
    metadata:
      labels:
        name: value
         ...
  

  

• Prevent InterSystems IRIS from starting up with the container.

  You can use the args field in the pod template to specify options to the InterSystems IRIS entrypoint application, iris-mainOpens in a new tab. For example, if there is something wrong with the InterSystems IRIS configuration which prevents startup from succeeding, iris-main exits, causing the pod to go into a restart loop, which makes it difficult or impossible to diagnose the problem. You can prevent the instance from starting by adding the iris-main option --up false as follows:

  podTemplate:
    spec:
      args:
      - --up
      - "false"
  

  

  When you do this, the readiness probeOpens in a new tab will not be satisfied, and the deployment will be paused indefinitely:

  $ kubectl get pods
  NAME                      READY   STATUS    RESTARTS   AGE
  my-IrisCluster-data-0     0/1     Running   0          32s
  

  

  After addressing the problem, you can do one of the following:

  • Manually start the instance with a command like the following:

    $ kubectl exec -it my-IrisCluster-data-0 -- iris start IRIS
    

    

  • Remove the podTemplate override and redeploy the pod.

• Adjust the termination grace period and specify lifecycle hooks.

  When a pod is terminated because the IrisCluster configuration is updated (see Modify the IrisCluster) or due to an explicit action (such as a kubectl delete command), the amount of time it has to complete termination is determined by the terminationGracePeriodSeconds setting. If this time is too short, InterSystems IRIS may not have enough time to shut down before the pod is terminated, which results in upgrades failing because the instance did not shut down properly. For this reason, the default value of terminationGracePeriodSeconds is 3600 seconds (as opposed to the Kubernetes default of 30 seconds).

  The pod template can also specify the postStart and preStop lifecycle hooksOpens in a new tab, which are executed immediately after a container is created and immediately before a container is terminated due to an API request or management event, respectively. (Execution of the latter is limited by the terminationGracePeriodSeconds setting.)

  The following example sets the value of terminationGracePeriodSeconds and specifies the command executed by the InterSystems IRIS entrypoint application, iris-mainOpens in a new tab, when it receives SIGTERM as the preStop hook:

  podTemplate:
    spec:
      terminationGracePeriodSeconds: 600
      lifecycle: 
        preStop: 
          exec: 
            command: ["/bin/sh", "-c", "iris stop IRIS quietly"]
  

  

• Override the default liveness probe and readiness probeOpens in a new tab.

  If you wanted to replace the default liveness probe and readiness probe for data nodes (or another node type), you could specify something like the following in the applicable pod template:

  podTemplate:
    spec:
      livenessProbe:
        exec:
          command:
          - /bin/true
      readinessProbe:
        httpGet:
          path: /csp/user/cache_status.cxw
          port: 1972
  

  

• Limit the number of CPU cores a data or compute node container can use in order to remain within the limits of the InterSystems IRIS license in use; limit the memory containers can use for efficient resource distribution.

  You can use the resources field in the pod template to both request and limit resources to be used by the containers in the pod. In the following example, the pod starts with 256 MB of memory and 2 CPU cores, and is limited to 2 GB of memory and 2 CPU cores:

  podTemplate:
    spec:
      resources:
        requests:
          memory: "256Mi"
          cpu: "2"
        limits:
          memory: "2Gi"
          cpu: "2"
  

  

• Allocate huge pages on cluster nodes.

  You can also use resources to allocate huge pages on InterSystems IRIS or other nodes:

  podTemplate:
    spec:
      resources:
        requests:
          memory: "2Gi"
        limits:
          memory: "2Gi"
          hugepages-2Mi: "2Gi"
  

  

• Override the mount point for durable storage.

  By default, the storageDB predefined persistent volume, which includes durable %SYSOpens in a new tab data, is mounted as /usr/irissys in the container’s file system. If you want to mount the volume at another location, you can override the default by changing the durable %SYS location and the mount point for storageDB, as follows:

  data:
    podTemplate:
      spec:
        env:
        - name: ISC_DATA_DIRECTORY
          value: "/irissys/data2/"
    storageDB:
      mountPath: "/irissys/data2"
  
  

  

compatibilityVersion

Required

Indicates the version of InterSystems IRIS being deployed in the IrisCluster; its value must match the version of the InterSystems IRIS image specified in the image field in the data and (optionally) compute node definitions.

shards:

      shards: N

Optional

Specifies the number of data nodes to be deployed as a sharded cluster. If the shards field is omitted, a single standalone instance of InterSystems IRIS is deployed, optionally as the data server in a distributed cache cluster; for more information, see Define the IrisCluster topology.

Data nodes can be added to the deployed cluster by increasing this setting and reapplying the definition (as described in Modifying the IrisCluster), but the setting cannot be decreased.

If you have deployed from a definition that does not contain this field — that is, either a distributed cache cluster or a stand-alone instance — you can convert the IrisCluster to a sharded cluster by:

• Adding the shards field.

• If necessary, modifying the number of compute nodes to make it a multiple of the value you specified for shards by changing the value of the replicas field, or by adding a compute node definition to the topology section if there is none.

• Making any other needed or desired modifications, such as adding a web server tier through the webgateway definition, changing the persistent storage definitions for the data nodes, adding mirroring, and so on.

mirrored:

      mirrored: {true|false}

Optional

Determines whether the data nodes in the deployment are mirroredOpens in a new tab.

If the value of mirrored is true, two mirrored instances, consisting of primary and backup failover membersOpens in a new tab, are deployed by default for each data node specified by the shards field. For example, if shards: 4 and mirrored: true, eight data node instances are deployed as four failover pairs, creating a mirrored sharded cluster with four data nodes. If mirrored is true when shards is omitted, two mirrored instances are deployed as a standalone InterSystems IRIS instance, which can optionally be the mirrored data server of a distributed cache cluster; for details, see Define the IrisCluster topology.

The default for mirrored is false.

mirrorMap:

      mirrorMap: primary,backup,drasync,rorsync,rwrasync,...

As noted above, data nodes or standalone instances deployed when mirrored is true consist by default of two instances, a primary and a backup. You can add one or more additional members to the field’s value. For example, if you wanted each mirrored data node (or the mirrored standalone instance) to include the failover members, a DR async, and two read-only reporting asyncs, you would specify mirrorMap: primary,backup,drasync,rorasync,rorasync; for mirrors with the failover members and three DR asyncs, you would specify mirrorMap: primary,backup,drasync,drasync,drasync, The maximum number of mirror members is 16, therefore you can add up to 14 asyncs to each mirror.

The default for mirrorMap is primary,backup.

When using this field, bear the following in mind:

• The mirrorMap field takes effect only when mirrored is true and compatibilityVersion is 2022.3.0 or higher.

• Async members are not configured as data shards; they are just normal instances that belong to the mirror.

• Be mindful of the ratio of mirror members to availability zones; for example, two availability zones and three mirror members might result in the primaries of two data nodes being deployed in different availability zones. For more information about the effects of deploying in multiple availability zones, see preferredZones.

mirrorName:

      mirrorName: basename

Optional

Specify a custom basename for any defined mirrors.

By default, mirrors created by IKO currently use the following naming scheme:

IRISMIRROR1
IRISMIRROR2
IRISMIRROR3
...

You can specify a different basename by providing a value for the mirrorName field. For example, mirrorName: MYMIRROR would result in the following mirror names:

MYMIRROR1
MYMIRROR2
MYMIRROR3
...

storage*:

      storage{DB|WIJ|Journal1|Journal2}:
        resources:
          requests:
            storage: size
        storageClassName: storage-class-name

Optional

Specify custom characteristics, such as size or storage class, for one or more of the four predefined persistent volumes deployed with each data node, as follows:

• storageDB — The volume on which data is stored (including durable %SYSOpens in a new tab data), mounted by default as /usr/irissys in the container’s file system.

• storageWIJ — The volume containing the WIJ directoryOpens in a new tab.

• storageJournal1 — The volume containing the primary journal directoryOpens in a new tab.

• storageJournal2 — The volume containing the alternate journal directoryOpens in a new tab.

These predefined volumes are mounted in /irissys inside the container, and are 2 GB by default. In addition to specifying a size override, you can include any other field from the Kubernetes persistent volume claim specOpens in a new tab to override default characteristics. For example, you can add storageClassName to override the deployment’s default storage class, as shown.

When including a size override, the value of the storage field can be specified in any unit between kilobytes and exabytesOpens in a new tab. The amount of data storage to be mounted on sharded cluster data nodes is determined during the cluster planning process and should include a comfortable margin for the future growth of your workload. In addition to overriding the sizes of the predefined volumes, you can use additional persistent volumes defined in the volumeClaimTemplates field and specified in the volumeMounts field to ensure that sufficient storage is available to each data node.

The same four storage* fields can be used to modify the same predefined volumes in the compute node definition in the same ways. These volumes are also 2 GB by default. The data storage for sharded cluster compute nodes or distributed cache cluster application servers should be kept to a bare minimumOpens in a new tab to conserve resources, as these nodes do not store application data, so size overrides of these volumes on compute nodes may be desirable.

Storage volumes on data and/or compute nodes in a deployed cluster can be expanded, provided the storage class specified by storageClassName is defined to allow volume expansionOpens in a new tab. To expand a volume, increase the storage value in the definition and reapply it (as described in Modifying the IrisCluster). The command kubectl get pvc shows the cluster’s current storage volumes sizes, while kubectl get iriscluster -o yaml shows the current volume sizes in the format of the cluster definition, and kubectl get sts shows the values from the definition applied when the cluster was created, without reflecting subsequent changes.

In the webgateway node definition you can override the characteristics of the single predefined volume, storageDB. The default size of this volume is 32 MB. Predefined volumes are also deployed with sam and iam nodes, and you can specify overrides for these in their respective definitions.

volumeMounts:

      volumeMounts:
      - mountPath: pathN
        name: volumeClaimTemplateN or volumeN
      - ...        

Optional

Specifies one or more persistent storage volumesOpens in a new tab, as defined in the volumeClaimTemplates field, and/or ephemeral storage volumesOpens in a new tab, as specified in the volumes field, to be deployed with each data node, in addition to the predefined persistent volumes. Each volume is defined by the name of one of the volume claim templates or volumes and a mountPath, which is a direct reference to a location in the container’s filesystem, visible to the InterSystems IRIS instance, on which to mount the volume.

The volumeMounts field can also be used to specify additional (typically ephemeral) volumes in the compute and webgateway node definitions.

irisDatabases:

Optional

      irisDatabases:
      - name: irisDatabaseN
        directory: path
        mirrored: {true|false}
        ecp: {true|false}
        seed: path
        logicalOnly: {true|false}
      - ...

Specifies one or more databasesOpens in a new tab to be created on persistent volumes, whether on the predefined storageDB predefined persistent volume (the default) or a volume you defined under volumeMounts, and mounted on the data node instance. Except for name, the following fields are optional:

• name

  The nameOpens in a new tab of the database, which must be unique.

• directory

  The location in the container file system or on a persistent volume in which to create the database. If omitted, the default is /usr/irissys/mgr/database-name, unless the mount point for the storageDB persistent volume has been changed, as illustrated in the last example in the podTemplate section, in which case the new mount point replaces /usr/irissys.

• mirrored

  If true and the IrisCluster is mirrored (the value of data/mirrored is true), the database is created as a mirrored database in the mirror specified by the mirrorName field.

• ecp

  If true, the database is configured for access by ECP clients; this is necessary for the database to be accessible to compute nodes in a sharded or distributed cache cluster.

• seed

  The location in the container file system or on a persistent volume of an existing, nonmirrored database from which the new database is to be cloned to the container filesystem or persistent volume location specified by directory. For example, if name is databaseCA, directory is /usr/irissys/mgr, and seed is /my-persistent-volume-C/databaseA, databaseA is cloned to /usr/irissys/mgr/databaseCA.

• logicalOnly

  If true, the existing database specified by seed is to be mounted at the location specified by directory, rather than being cloned.

irisNamespaces:

Optional

      irisNamespaces:
      - name: irisNamespaceN
        routines: database-name
        globals: database-name
        interop: {true|false}
      - ...

Specifies one or more namespacesOpens in a new tab to be created on the data node. The name and globals fields are required, the other are optional:

• name

  The nameOpens in a new tab of the namespace, which must be unique.

• routines

  The name of the default routines database for the namespace.

• globals

  The name of the default globals database for the namespace.

• interop

  If true, the namespace will be interoperability-enabled.

containers:

      containers:
      - name: containerName
        image: registry/repository/image:tag
        field1: value
        ...
      - ...

Optional

Specifies one or more containers to run in the pod alongside each data node (so-called sidecar containers). To define each sidecar container, create an entry in the array of core.ContainerOpens in a new tab; only name and image are required.

The containers field can also be used to specify sidecar containers in the compute definition. This field takes effect only when compatibilityVersion is 2022.3.0 or higher.

webgateway: Sidecar Web Gateway containers

      webgateway:
        image: registry/repository/image:tag
        type: {apache|apache-lockeddown|nginx}
        applicationPaths:
        - pathN
        - ...
      loginSecret:
        name: secret-name

Optional, but recommended for InterSystems IRIS Management Portal access

The InterSystems Web Gateway passes HTTP requests from a web server to InterSystems IRIS instances, including both application connections and requests for an instance’s web-based Management Portal. As described in detail in Web Access Using the Web Gateway ContainerOpens in a new tab in Running InterSystems Products in Containers, there are two primary approaches to distributing both application connections and Management Portal requests to multiple InterSystems IRIS containers: one-to-many, in which a shared Web Gateway container handles both, and many-to-many, in which one or more Web Gateway containers are deployed as web server nodes for application connections while each InterSystems IRIS container is deployed with a dedicated Web Gateway container to provide access to its Management Portal and other built-in web applications. The IKO provides a simple means of using the latter approach, defining dedicated Web Gateway containers separately from the web server nodes defined in the webgateway section of topology.

On Kubernetes platforms, the standard way to address the need for companion containers is to add so-called sidecar containers to the relevant pods, and the containers field described above is used for this purpose generally. But given the required Web Gateway and web server configuration, a dedicated Web Gateway sidecar would be difficult to configure and maintain, and would not take advantage of the automatic configuration available for web server nodes. The optional webgateway field in the data definition allows you to easily add a dedicated Web Gateway container to every data node pod as a sidecar. In addition to being configured to provide Management Portal access, the Web Gateway sidecar provides web access to iam and sam nodes, if defined.

The fields in the sidecar webgateway definition are a subset of those in the web server node (webgateway) definition. Specific usage is as follows:

• You must specify a value for the image field and can optionally specify values for the type and applicationPaths fields. To serve the Management Portal of the accompanying InterSystems IRIS, you must define /csp/sys as an application path. You should also configure /csp/broker, which provides access to files shared by several built-in system applicationsOpens in a new tab.

• If you are specifying a secret containing a password and optionally username in the loginSecret field of the webgateway definition, specify the same secret with the same field here. (For more information, see Update and coordinate server authentication credentials.)

• The replicas and ephemeral fields do not apply to the sidecar webgateway; there is always one, and it is always ephemeral.

image

image: containers.intersystems.com/intersystems/iris:latest-em

Required

Compute nodes are deployed from the same InterSystems IRIS image as data nodes; an example is shown.

replicas:

         replicas: N

Optional

Specifies the number of identical compute nodes to deploy. In a sharded cluster, this should be a multiple of the number of data nodes specified by shards (for more information, see Plan Compute NodesOpens in a new tab in the Scalability Guide).

You can add compute nodes to, or remove them from, the deployed IrisCluster by modifying the configmap or by changing this setting and reapplying the definition.

The replicas field also appears in the webgateway definition, where it specifies the number of web server nodes to deploy and is required, and the sam and iam definitions, where it is used to remove an existing sam or iam node from a deployment.

Note:

In place of the replica field, you can use a Kubernetes HorizontalPodAutoscalerOpens in a new tab to automatically increase or decrease the number of compute nodes based on factors such as CPU load. The following example includes all of the required fields:

    compute:
      image: containers.intersystems.com/intersystems/iris:latest-em
      compatibilityVersion: "2023.2.0"
      hpa:
        spec:
          minReplicas: 2
          maxReplicas: 4
          scaleTargetRef:
            kind: StatefulSet
            name: acme-compute
            apiVersion: app/v2

The compatibilityVersion field must be set to 2023.1.or later to use the hpa field. IKO updates the contents of scaleTargetRef to match the cluster, but the section must be present (with any values) in order for Kubernetes to validate the definition.

ephemeral

      emphemeral: {true|false} 

Optional

When set to true, only ephemeral (not persistent) volumes are created. If any storage is required, the local disk is used. Default is false.

Use this option if you want the cluster’s compute nodes to come up more quickly, do not plan to install any custom applications, and do not want to preserve any state on the compute nodes. Can also be used in the webgateway definition on the same basis.

image

image: containers.intersystems.com/intersystems/webgateway:latest

Required

Use one of the following InterSystems images to deploy webgateway nodes:

• webgateway (as shown in the example) — Deploys an InterSystems Web Gateway instance and an Apache web server.

• webgateway-lockeddown — To meet the strictest security requirements, deploys a nonroot Web Gateway instance installed with locked-down security and a nonroot Apache web server configured to use port 52773 instead of the standard port 80.

• webgateway-nginx — Deploys a Web Gateway instance and an Nginx web server.

For information about these images and the differences between them, see Web Access Using the Web Gateway ContainerOpens in a new tab in Running InterSystems Products in Containers.

type:

      type: {apache|apache-lockeddown|nginx}

Optional

Specifies deployment of an Apache web server, a locked down Apache web server, or an Nginx web server (as described for the previous field); the default is apache.

replicas:

      replicas: N

Required

Specifies the number of identical webgateway nodes to deploy.

You can add webgateway nodes to, or remove them from, the deployed IrisCluster by modifying the configmap or by changing this setting and reapplying the definition.

The replicas field also appears in the compute section, where it specifies the number of compute nodes to deploy, and the sam and iam definitions, where it is used to remove an existing sam or iam node from a deployment.

ephemeral:

      emphemeral: {true|false} 

Optional

When set to true, only ephemeral (not persistent) volumes are created. If any storage is required, the local disk is used. Default is false.

Use this option if you want the cluster’s web server nodes to come up more quickly, do not plan to install any custom applications, and do not want to preserve any state on the web server nodes. Can also be used in the compute definition on the same basis.

applicationPaths:

      applicationPaths:
        - pathN
        - ...

Optional

Provides a list of application pathsOpens in a new tab to configure in the Web Gateway. Application paths should not have a trailing slash, and the path /csp is reserved.

alternativeServers:

      alternativeServers: {FailOver|LoadBalancing}

Optional

Selects the method by which the Web Gateway on each node determines which of the InterSystems IRIS servers — that is, which data or (optionally) compute node — in its server access profiles to connect to (see Load Balancing and Failover Between Multiple InterSystems IRIS Server InstancesOpens in a new tab in the Web Gateway Guide). Possible values are FailOver and LoadBalancing, with a default of LoadBalancing.

loginSecret:

       loginSecret:
         name: secret-name 

Optional, but recommended for effective security

The loginSecret field specifies a Kubernetes secret containing a password and optional username entry with which the Web Gateway authenticates to the InterSystems IRIS instances specified in its server access profiles. For information about the use of these credentials to connect to InterSystems IRIS and their role in Web Gateway configuration, see Update and coordinate server authentication credentials.

Create a generic secret for this purpose, as in this example:

kubectl create secret generic webgateway-secret --from-literal=username=wg-auth --from-literal=password=[[[U1lT8g7

If the password is in plain text, it is base64-encoded and given the prefix of [[[ to indicate this encoding; if the prefix is already present, the password is used as is.

You must also supply a loginSecret as described above when specifying a dedicated webgateway sidecar container in the data and/or compute definitions, which due to the need to coordinate with InterSystems IRIS should be the same as the one provided here. (You can also specify a similar loginSecret for a different purpose in the sam definition.)