IKO - Lessons Learned (Part 2 - The IrisCluster)

We now get to make use of the IKO.

Below we define the environment we will be creating via a Custom Resource Definition (CRD). It lets us define something outside the realm of what the Kubernetes standard knows (this is objects such as your pods, services, persistent volumes (and claims), configmaps, secrets, and lots more). We are building a new kind of object, an IrisCluster object.

apiVersion: intersystems.com/v1alpha1
kind: IrisCluster
metadata:
  name: simple
spec:
  licenseKeySecret:
    #; to activate ISC license key
    name: iris-key-secret
  configSource:
    #; contains CSP-merge.ini, which is merged into IKO's
    #; auto-generated configuration.
    name: iris-cpf
  imagePullSecrets:
    - name: intersystems-pull-secret

  topology:
    data:
      image: containers.intersystems.com/intersystems/irishealth:2023.3
      compatibilityVersion: "2023.3"
    webgateway:
      replicas: 1
      image: containers.intersystems.com/intersystems/webgateway:2023.3
      applicationPaths:
        #; All of the IRIS instance's system default applications.
        #; For Management Portal only, just use '/csp/sys'.
        #; To support other applications, please add them to this list.
        - /csp/sys
        - /csp/broker
        - /api
        - /isc
        - /oauth2
        - /ui
        - /csp/healthshare
      alternativeServers: LoadBalancing
      loginSecret:
        name: iris-webgateway-secret

  serviceTemplate:
    # ; to enable external IP addresses
    spec:
      type: LoadBalancer

The IrisCluster object oversees and facilitates the deployment of all the components of our IRIS environment. In this specific environment we will have:

• 1 IRIS For Health Instance (in the form of a data node)
• 1 Web Gateway (in the form of a web gateway node)

The iris-key-secret is an an object of kind secret. Here we will store our key. To create it:

kubectl create secret generic iris-key-secret --from-file=iris.key

Note that you'll get an error if your file is not named iris.key. If you insist on naming it something else you can do this:

kubectl create secret generic iris-key-secret --from-file=iris.key=yourKeyFile.key

The iris-cpf is a configuration file. We will create it as an object of configmap kind.

kubectl create cm iris-cpf --from-file common.cpf

In the common.cpf file there is just the password hash. You can create it using the passwordhash image as follows:

$ docker run --rm -it containers.intersystems.com/intersystems/passwordhash:1.1 -algorithm SHA512 -workfactor 10000
Enter password:
Enter password again:
PasswordHash=2b679c8c944e2cbc2c5e4b12c62b76d5dee07f28099083940b816197ca0ffbd807c36cef7d16e17bdfe4f7a2cd45a09f6e50bef1bac8f5978362eef7d2997f3a,eac33175d6268d7bb89edb48600a3fd59d9ccd4777959bbbcc31cdb726f9b956e31fedd44c016a48d0098ffc605ac6a17b5767bfdebefe01b078ef2efd40f84f,10000,SHA512

Then put the output in your common.cpf (attached). Note that the data.cpf and compute.cpf mentioned in the IKO docs are to specify additional configuration of the data and compute nodes. This is overkill for us right now - just know that they exist.

We just want to define a password of our own at startup. If we do not, we will be prompted to change our password the first time we sign in (note that the first time the default username/password is _SYSTEM/SYS, in case you do not define one).

Onto the next secret, the one for pulling the image from the registry. I use the InterSystems Container Registry (ICR), but lots of our clients have their own registries where they push our images to. That is great too. Just note that how you create your secret depends on how you access your registry. For the ICR it is as follows:

kubectl create secret docker-registry intersystems-pull-secret --docker-server=https://containers.intersystems.com --docker-username='<your username>' --docker-password='<your password>' --docker-email='<your email>'

We have one secret left, but let's just gloss over the topology first.

Topology is the IRIS environment we want to create. Specifically, this is the data node and web gateway. Regarding the image, I see some people like to use the :latest tag as is normally good practice to ensure the most up to date software. I think in this case it would actually be better practice to specify what version one wants as it is best practice to specify the compatibilityVersion. See more about that here.

As for the webgateway, we can configure how many we want, what application paths should be available and the loginSecret. This secret is how the webgateway will be logging into IRIS.

kubectl create secret generic iris-webgateway-secret --from-literal='username=CSPSystem' --from-literal='password=SYS'

That's our last secret, but you can read up more about them on the Kubernetes documentation.

Finally, we have the serviceTemplate.

Our process will create two services that are of significance to us (the rest are outside the scope of this article and should not concern you at this time): 1) simple and 2) simple-webgateway.

For now, all you need to know about services is that they expose applications that run on pods. By running kubectl get svc, you can see external IP that these two services create. If you're running your kubernetes cluster on docker-desktop like me, then it will be localhost.

And we notice the familiar ports.

That's because this is our internal and external webservers. For example, we can go to our management portal through the external web server: http://localhost/csp/sys/UtilHome.csp. http takes us automatically to port 80 (https to 443) which is why we don't need to specify the port here.

That's it for now. In the next article we'll take another bite out of services.