Skip to main content

Containerless Deployment

If you want to use ICM to provision cloud infrastructure and install noncontainerized InterSystems IRIS instances on that infrastructure, or to install InterSystems IRIS on a PreExisting cluster, you can do so using containerless mode.

In essence, containerless mode replaces the containerized deployment of InterSystems IRIS by ICM with direct installation from traditional kits, while retaining all the other steps in the ICM provisioning and deployment process. This is accomplished by adding commands to ICM and adapting several others. In containerless mode, Docker is not installed on the provisioned nodes and the icm run command cannot be used to deploy containers on those nodes.

ICM can execute nonroot installation of InterSystems IRIS in containerless mode; for more in formation see Nonroot Installation in Containerless Mode

Containerless Deployment Platforms

Operating systems supported for containerless deployment include:

  • Ubuntu 18.04 or later

  • Red Hat Enterprise Linux 7.3 to 7.7

  • SUSE Enterprise Linux 12 SP4, 15, and 15 SP1

The following operating systems are not supported but have been tested:

  • CentOS

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": "Acme",
    "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/2019.4.0/unix/IRIS-2019.4.0.792.0-lnxrhx64.tar.gz"
    },
    {
        "Role": "AM",
        "Count": "2",
        "StartCount": "2",
        "LoadBalancer": "true",
        "KitURL": "http://kits.acme.com/iris/2019.4.0/unix/IRIS-2019.4.0.792.0-lnxrhx64.tar.gz"
    }
]

In the defaults file:

{
    "Containerless": "true",
    "KitURL": "http://kits.acme.com/iris/2019.4.0/unix/IRIS-2019.4.0.792.0-lnxrhx64.tar.gz"
    "Provider": "AWS",
    "Label": "Acme",
    "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-2019.4.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-2019.4.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
Note:

You can use the UserCPF field and a configuration merge file to install multiple instances with different configuration settings from the same kit; for more information, see Deploying with Customized InterSystems IRIS Configurations in the “ICM Reference” chapter.

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 in the “Using ICM” chapter.

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       2019.4.0.792.0  running  ok
Acme-AM-TEST-0002  54.153.96.236  IRIS       2019.4.0.792.0  running  ok
Acme-AM-TEST-0003  54.103.9.388   IRIS       2019.4.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 in the “Using Multiple Instances of InterSystems IRIS” chapter of the System Administration Guide) 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       2019.4.0.792.0  running  ok
Acme-AM-TEST-0002  54.153.96.236  IRIS       2019.4.0.792.0  running  ok
Acme-AM-TEST-0003  54.103.9.388   IRIS       2019.4.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       2019.4.1.417.0  running  ok
Acme-AM-TEST-0002  54.153.96.236  IRIS       2019.4.1.417.0  running  ok
Acme-AM-TEST-0003  54.103.9.388   IRIS       2019.4.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 in the Installation Guide 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 in the “ICM Reference” chapter.

  • 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, you must include the KitURL and LicenseKey fields in the WS definition in the definitions.json file, for example:

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

Because non-root users may not bind to ports below 1024, the Web Gateway port has been moved from 80 to 52773 in non-root 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

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 non-root 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 
  non-root 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 non-root 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 
  non-root deployment on ubuntu: Retrieve apt-get updates
# apt-get update
------------------------------------------------------------------------
Issue found: Requirement not met for non-root deployment on ubuntu: 
  Install net-tools
# apt-get --allow-unauthenticated -y install net-tools
------------------------------------------------------------------------
Potential issue found: Cannot determine if requirement met for 
  non-root deployment on ubuntu: Clean apt-get cache
# apt-get -y clean all
------------------------------------------------------------------------
Potential issue found: Cannot determine if requirement met for 
  non-root 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 in this appendix.

Next sectionSharing ICM Deployments
Previous sectionICM Reference
Feedback