Containerless Deployment

Containerless Deployment Platforms

Operating systems supported for containerless deployment include:

• Ubuntu 20.04 or later

• Red Hat Enterprise Linux 8.3 and later version 8 releases, 9.0 and later version 9 releases

Enabling Containerless Mode

Enable containerless mode by adding the Containerless field to the defaults.json file with a value of true, for example:

{
    "Containerless": "true",
    "Provider": "AWS",
    "Label": "Sample",
    "Tag": "TEST"
    "LicenseDir": "/Samples/license/",
    "Credentials": "/Samples/AWS/sample.credentials",
    ...
}

Installing InterSystems IRIS

To install InterSystems IRIS on your provisioned nodes using the installation kit you have selected, use the icm install command, which does not exist in container mode. The kit is identified by the KitURL field, which specifies the path to the installation kit and can be added to either defaults.json or definitions.json. The specified kit must be all of the following:

• Accessible by the node on which InterSystems IRIS is to be installed (though not necessarily by the ICM container itself)

• A 64-bit Linux kit

• A gzipped tar file

For example, in the definitions file:

[
    {
        "Role": "DM",
        "Count": "1",
        "DataVolumeSize": "50",
        "InstanceType": "m4.xlarge",
        "KitURL": "http://kits.acme.com/iris/2022.2.0/unix/IRIS-2022.2.0.792.0-lnxrhx64.tar.gz"
    },
    {
        "Role": "AM",
        "Count": "2",
        "StartCount": "2",
        "LoadBalancer": "true",
        "KitURL": "http://kits.acme.com/iris/2022.2.0/unix/IRIS-2022.2.0.792.0-lnxrhx64.tar.gz"
    }
]

In the defaults file:

{
    "Containerless": "true",
    "KitURL": "http://kits.acme.com/iris/2022.2.0/unix/IRIS-2022.2.0.792.0-lnxrhx64.tar.gz"
    "Provider": "AWS",
    "Label": "Sample",
    "Tag": "TEST"
    "LicenseDir": "/Samples/license/",
    "Credentials": "/Samples/AWS/sample.credentials",
    ...
}

Note:

The KitURL can be a reference to a local file copied to the provisioned nodes, which may be convenient under some circumstances. For example, you can include this KitURL in the defaults file:

"KitURL": "file://tmp/IRIS-2022.2.0.792.0-lnxrhx64.tar.gz"

and use the icm scp command to copy the kit to the provisioned nodes before executing the icm install command, for example:

icm scp -localFile IRIS-2022.2.0.792.0-lnxrhx64.tar.gz -remoteFile /tmp

When you execute the icm install command, ICM installs InterSystems IRIS from the specified kit on each applicable node, resulting in output like the following:

Downloading kit on Acme-DM-TEST-0001...
Downloading kit on Acme-AM-TEST-0002...
Downloading kit on Acme-AM-TEST-0003...
...downloaded kit on Acme-AM-TEST-0002
...downloaded kit on Acme-AM-TEST-0003
...downloaded kit on Acme-DM-TEST-0001
Installing kit on Acme-AM-TEST-0003...
Installing kit on Acme-DM-TEST-0001...
Installing kit on Acme-AM-TEST-0002...
...installed kit on Acme-AM-TEST-0002
...installed kit on Acme-DM-TEST-0001
...installed kit on Acme-AM-TEST-0003
Starting InterSystems IRIS on Acme-DM-TEST-0001...
Starting InterSystems IRIS on Acme-AM-TEST-0002...
Starting InterSystems IRIS on Acme-AM-TEST-0003...
...started InterSystems IRIS on Acme-AM-TEST-0002
...started InterSystems IRIS on Acme-AM-TEST-0003
...started InterSystems IRIS on Acme-DM-TEST-0001
Management Portal available at: http://172.16.110.14:52773/csp/sys/UtilHome.csp

Reinstalling InterSystems IRIS

To make the containerless deployment process as flexible and resilient as possible, the icm install command is fully reentrant — it can be issued multiple times for the same deployment. In this regard it is similar to the icm run command, as described in Redeploying Services.

When an icm install command is repeated, ICM stops and uninstalls the installed instances, then installs InterSystems IRIS from the specified kit again. You might want to repeat the command for one of the following reasons:

• Reinstalling the existing instances.

  To replace the installed InterSystems IRIS instances with new ones from the same kit, simply repeat the original icm run command that first deployed the containers. You might do this if you have made a change in the definitions files that requires reinstallation, for example you have updated the licenses in the directory specified by the LicenseDir field.

• Installing InterSystems IRIS on nodes you have added to the infrastructure, as described in Reprovisioning the Infrastructure.

  When you repeat an icm install command after adding nodes to the infrastructure, instances on the existing nodes are reinstalled as described in the preceding, while new instances are installed on the new nodes. This allows the existing nodes to be reconfigured for the new deployment topology, if necessary.

• Overcoming deployment errors.

  If the icm install command fails on one or more nodes due to factors outside ICM’s control, such as network latency or interruptions, you can issue the command again; in most cases, deployment will succeed on repeated tries. If the error persists, however, it may require manual intervention — for example, if it is caused by an error in one of the configuration files — before you issue the command again.

Uninstalling InterSystems IRIS

The icm uninstall command, which does not exist in container mode, is used in containerless mode to stop and uninstall all InterSystems IRIS instances in the deployment (without options). You can use the -role and -machine options, as usual, to limit the command to a specific role or node. For example,

icm uninstall

uninstalls InterSystems IRIS on all nodes in the deployment, while

icm uninstall -role AM

uninstalls InterSystems IRIS on the AM nodes only.

Additional Containerless Mode Commands

Several container mode commands work in the same way, or an analagous way, in containerless mode, including use of the -machine and -role options, as follows:

• icm ssh, icm scp, icm session, icm sql

  The behavior of these commands is identical in container mode and containerless mode.

• icm ps

  The columns included in icm ps output in containerless mode are shown in the following example:

  # icm ps -json
  Machine            IP Address     Instance   Kit             Status   Health
  -------            ----------     --------   ---             ------   ------
  Acme-DM-TEST-0001  54.67.2.117    IRIS       2022.2.0.792.0  running  ok
  Acme-AM-TEST-0002  54.153.96.236  IRIS       2022.2.0.792.0  running  ok
  Acme-AM-TEST-0003  54.103.9.388   IRIS       2022.2.0.792.0  running  ok
  
  

  

  The Instance field provides the name of each instance (in a container provided by InterSystems this is always IRIS) and the Kit field the kit from which it was installed. Values for Status include running, down, and sign-on inhibited; values for Health include ok, warn, and alert.

  Note:

  When the icm ps command is used prior to the icm install command in a containerless mode deployment, the Status field displays the value not installed.

• icm stop, icm start

  The icm stop and icm start commands execute the iris stop and iris start commands (see Controlling InterSystems IRIS Instances) on all InterSystems IRIS instances or the specified instance(s).

• icm upgrade

  In containerless mode, icm upgrade does the following:

  • Downloads the InterSystems IRIS kit specified by the KitURL field.

  • Stops the current InterSystems IRIS instance using iris stop.

  • Uninstalls the current InterSystems IRIS instance.

  • Installs the InterSystems IRIS kit specified by KitURL.

  • Starts the newly-installed InterSystems IRIS instance using iris start.

  The following shows output from the icm upgrade command in containerless mode:

  # icm ps
  Machine            IP Address     Instance   Kit             Status   Health
  -------            ----------     --------   ---             ------   ------
  Acme-DM-TEST-0001  54.67.2.117    IRIS       2022.2.0.792.0  running  ok
  Acme-AM-TEST-0002  54.153.96.236  IRIS       2022.2.0.792.0  running  ok
  Acme-AM-TEST-0003  54.103.9.388   IRIS       2022.2.0.792.0  running  ok
  
  # icm upgrade
  Downloading kit on Acme-DM-TEST-0001...
  Downloading kit on Acme-AM-TEST-0002...
  Downloading kit on Acme-AM-TEST-0003...
  ...downloaded kit on Acme-AM-TEST-0002
  ...downloaded kit on Acme-AM-TEST-0003
  ...downloaded kit on Acme-DM-TEST-0001
  Stopping InterSystems IRIS on Acme-DM-TEST-0001...
  Stopping InterSystems IRIS on Acme-AM-TEST-0003...
  Stopping InterSystems IRIS on Acme-AM-TEST-0002...
  ...stopped InterSystems IRIS on Acme-DM-TEST-0001
  ...stopped InterSystems IRIS on Acme-AM-TEST-0002
  ...stopped InterSystems IRIS on Acme-AM-TEST-0003
  Uninstalling InterSystems IRIS on Acme-AM-TEST-0003...
  Uninstalling InterSystems IRIS on Acme-DM-TEST-0001...
  Uninstalling InterSystems IRIS on Acme-AM-TEST-0002...
  ...uninstalled InterSystems IRIS on Acme-DM-TEST-0001
  ...uninstalled InterSystems IRIS on Acme-AM-TEST-0002
  ...uninstalled InterSystems IRIS on Acme-AM-TEST-0003
  Installing kit on Acme-AM-TEST-0002...
  Installing kit on Acme-DM-TEST-0001...
  Installing kit on Acme-AM-TEST-0003...
  ...installed kit on Acme-AM-TEST-0002
  ...installed kit on Acme-DM-TEST-0001
  ...installed kit on Acme-AM-TEST-0003
  Starting InterSystems IRIS on Acme-DM-TEST-0001...
  Starting InterSystems IRIS on Acme-AM-TEST-0002...
  Starting InterSystems IRIS on Acme-AM-TEST-0003...
  ...started InterSystems IRIS on Acme-AM-TEST-0002
  ...started InterSystems IRIS on Acme-AM-TEST-0003
  ...started InterSystems IRIS on Acme-DM-TEST-0001
  
  # icm ps
  Machine            IP Address     Instance   Kit             Status   Health
  -------            ----------     --------   ---             ------   ------
  Acme-DM-TEST-0001  54.67.2.117    IRIS       2022.2.1.417.0  running  ok
  Acme-AM-TEST-0002  54.153.96.236  IRIS       2022.2.1.417.0  running  ok
  Acme-AM-TEST-0003  54.103.9.388   IRIS       2022.2.1.417.0  running  ok
  
  

  

  After upgrade, you may want to update the value of KitURL in your defaults or definitions file to reflect the upgrade.

Nonroot Installation in Containerless Mode

At some sites, security policies prohibit applications having root access to systems. A nonroot InterSystems IRIS instance is installed by a user without root access. If you plan to use containerless mode to install nonroot instances, please carefully review the differences between root and nonroot installation and instances in Installing as a Nonroot User before proceeding.

Required Configuration Fields

For nonroot installation, the defaults.json file must contain the following fields (in addition to containerless: true):

• The nonroot field must be set to true.

• The ISCInstalldir field must specify a file system location to which the installing user — that is, the user specified by the SSHUser field — has write access (which is not the case with the default installation directory, /usr/irissys). For example, if SSHUser is irisowner, you could include the following:

  "ISCInstallDir": "/home/irisowner/irissys"
  

  

  (Bear in mind some providers require specific usernames in the SSHUser field; for more information, see Security-related Parameters.)

• If the installing user does not have write access to /irissys, the default location for durable %SYS volumes, the fields used to override the mount points for the storage volumes mounted by ICM must be changed to mount points on persistent storage to which the user does have write access, for example:

  "DataMountPoint": "/home/irisowner/data",
  "WIJMountPoint": "/home/irisowner/wij",
  "Journal1MountPoint": "/home/irisowner/journal1",
  "Journal2MountPoint": "/home/irisowner/journal2"
  

  
  Important:

  In nonroot installation, ICM does not allocate, format, or mount external volumes; it is the user's responsibility to make sure the directories specified using the mount point fields represent accessible persistent storage.

In addition, if WS nodes are included in a containerless mode nonroot deployment, the WS definition in the definitions.json file must specify an InterSystems IRIS kit in the KitURL field and InterSystems IRIS license in the LicenseKey field, for example:

{
  "Role": "WS",
  "Count": "1",
  "KitURL": "file://tmp/IRIS-2022.2.0.221.0-lnxubuntux64.tar.gz",
  "LicenseKey": "heterogenous-sharding-iris.key"
}

Note:

Because nonroot users may not bind to ports below 1024, the Web Gateway port has been moved from 80 to 52773 in containerless nonroot mode. For example, the URL for the Web Gateway on a WS node would be like the following:

http://133.98.229.35.google.com:52773/csp/bin/Systems/Module.cxw

The WebServerPort parameter, which specifies the web server port for InterSystems IRIS in all deployments, also specifies the Web Gateway port in nonroot containerless mode; the default is 52773.

Provisioning Phase

ICM assumes that all needed configuration requiring root access on the hosts of infrastructure to be provisioned by ICM (or identified by the user in a Preexisting deployment) has been completed before the icm provision command is used to provision the infrastructure. During the provisioning phase, ICM attempts to ascertain whether its requirements have been met, and if not displays messages identifying issues found along with suggestions on how to mitigate them. The following example has been edited for brevity::

# icm provision
Configuring Acme-DATA-TEST-0001...
provision on Acme-DATA-TEST-0001 failed (attempt 1 of 1)...
Acme-DATA-TEST-0001 - Error: Thread exited with value 1
SSH operation failed
See /Samples/GCP/state/Acme-DATA-TEST/Acme-DATA-TEST-0001/ssh.err 
  and /Samples/GCP/state/Acme-DATA-TEST/Acme-DATA-TEST-0001/ssh.out
Errors occurred during execution; aborting operation
To reprovision, specify -stateDir state

# cat /Samples/GCP/state/Acme-DATA-TEST/Acme-DATA-TEST-0001/ssh.err
20201203-21:19:16:320888393 Error: 2 nonroot issues found; 
  please examine configNode.log, address the issues, and re-provision

# cat /Samples/GCP/state/Acme-DATA-TEST/Acme-DATA-TEST-0001/ssh.out
------------------------------------------------------------------------
Potential issue found: Cannot determine if requirement met for 
  nonroot deployment: Configure iptables
# /sbin/iptables --delete INPUT --jump REJECT --reject-with icmp-host-prohibited
# /sbin/iptables --delete FORWARD --jump REJECT --reject-with icmp-host-prohibited
# /sbin/iptables-save
------------------------------------------------------------------------
Issue found: Requirement not met for nonroot deployment: IP forwarding
# echo "net.ipv4.ip_forward=1" | tee -a /etc/sysctl.conf
# sysctl -w net.ipv4.ip_forward=1
------------------------------------------------------------------------
Potential issue found: Cannot determine if requirement met for 
  nonroot deployment on ubuntu: Retrieve apt-get updates
# apt-get update
------------------------------------------------------------------------
Issue found: Requirement not met for nonroot deployment on ubuntu: 
  Install net-tools
# apt-get --allow-unauthenticated -y install net-tools
------------------------------------------------------------------------
Potential issue found: Cannot determine if requirement met for 
  nonroot deployment on ubuntu: Clean apt-get cache
# apt-get -y clean all
------------------------------------------------------------------------
Potential issue found: Cannot determine if requirement met for 
  nonroot deployment on GCP: Configure core dump
# systemctl disable apport; systemctl stop apport; sysctl -p; 
  sysctl -w kernel.core_pattern='%e.%p.%h.%t.core'
# echo "%e.%p.%h.%t.core" > /proc/sys/kernel/core_pattern

You can then carry out these changes directly on the systems involved as root (or as an update to their VM templates).

Note:

• The commands do not need to be run individually; they can all be executed together in a single operation

• These commands are formulated to be run as root; some will need reformatting to work with sudo.

• Some of the commands suggested for a “potential issue” may not succeed because they were not required; this is normal.

Once you have made the needed changes, reprovision with the command icm provision -force. You are now ready to deploy using the icm install command, as described earlier on this page.