Container Management Commands

The commands in this section are used to manage the containers you have deployed on your provisioned infrastructure.

Many ICM command options can be used with more than one command. For example, the -role option can be used with a number of commands to specify the type of node for which the command should be run — for example, icm inventory -role AM lists only the nodes in the deployment that are of type AM — and the -image option, which specifies an image from which to deploy containers for both the icm run and icm upgrade commands. For complete lists of ICM commands and their options, see ICM Commands and Options in the “ICM Reference” chapter.

icm ps

When deployment is complete, the icm ps command shows you the run state of containers running on the nodes, for example:

$ icm ps -container iris
Machine             IP Address    Container Status Health  Image
-------             ----------    --------- ------ ------  -----
ANDY-DATA-TEST-0001 00.56.140.23  iris      Up     healthy intersystems/iris:latest-em
ANDY-DATA-TEST-0002 00.53.190.37  iris      Up     healthy intersystems/iris:latest-em
ANDY-DATA-TEST-0003 00.67.116.202 iris      Up     healthy intersystems/iris:latest-em
ANDY-DATA-TEST-0004 00.153.49.109 iris      Up     healthy intersystems/iris:latest-em

If the -container restriction is omitted, all containers running on the nodes are listed. This includes both other containers deployed by ICM (for example, Weave network containers, or any custom or third party containers you deployed using the icm run command) and any deployed by other means after completion of the ICM deployment..

Beyond node name, IP address, container name, and the image the container was created from, the icm ps command includes the following columns:

Status — One of the following status values generated by Docker: created, restarting, running, removing (or up), paused, exited, or dead.
Health — For iris, arbiter, and webgateway containers, one of the values starting, healthy, or unhealthy; for other containers none (or blank). When Status is exited, Health may display the exit value (where 0 means success).
For iris containers the Health value reflects the health state of the InterSystems IRIS instance in the container. (For information about the InterSystems IRIS health state, see System Monitor Health StateOpens in a new tab in the “Using the System Monitor” chapter of the Monitoring Guide). For arbiter containers it reflects the status of the ISCAgent, and for webgateway containers the status of the InterSystems Web Gateway web server. Bear in mind that unhealthy may be temporary, as it can result from a warning that is subsequently cleared.

Mirror — When mirroring is enabled (see Rules for Mirroring), the mirror member status (for example PRIMARY, BACKUP, SYNCHRONIZING) returned by the %SYSTEM.Mirror.GetMemberStatus()Opens in a new tabmirroring API call. For example:

$ icm ps -container iris
Machine             IP Address    Container Status Health  Mirror  Image
-------             ----------    --------- ------ ------  ------  -----
ANDY-DATA-TEST-0001 00.56.140.23  iris      Up     healthy PRIMARY intersystems/iris:latest-em
ANDY-DATA-TEST-0002 00.53.190.37  iris      Up     healthy BACKUP  intersystems/iris:latest-em
ANDY-DATA-TEST-0003 00.67.116.202 iris      Up     healthy PRIMARY intersystems/iris:latest-em
ANDY-DATA-TEST-0004 00.153.49.109 iris      Up     healthy BACKUP  intersystems/iris:latest-em

For an explanation of the meaning of each status, see Mirror Member Journal Transfer and Dejournaling StatusOpens in a new tab in the “Mirroring” chapter of the High Availability Guide.

Additional deployment and management phase commands are listed in the following. For complete information about these commands, see ICM Reference.

icm stop

The icm stop command stops the specified containers (or iris by default) on the specified nodes, or on all nodes if no machine or role constraints provided). For example, to stop the InterSystems IRIS containers on the application servers in the distributed cache cluster configuration:


$ icm stop -container iris -role DS

Stopping container iris on ANDY-DATA-TEST-0001...
Stopping container iris on ANDY-DATA-TEST-0002...
Stopping container iris on ANDY-DATA-TEST-0004...
Stopping container iris on ANDY-DATA-TEST-0003...
...completed stop of container iris on ANDY-DATA-TEST-0004
...completed stop of container iris on ANDY-DATA-TEST-0001
...completed stop of container iris on ANDY-DATA-TEST-0002
...completed stop of container iris on ANDY-DATA-TEST-0003

icm start

The icm start command starts the specified containers (or iris by default) on the specified nodes, or on all nodes if no machine or role constraints provided). For example, to restart one of the stopped application server InterSystems IRIS containers:

$ icm start -container iris -machine ANDY-DATA-TEST-0002...
Starting container iris on ANDY-DATA-TEST-0002...
...completed start of container iris on ANDY-DATA-0002

icm pull

The icm pull command downloads the specified image to the specified machines. For example, to add an image to data node 1 in the sharded cluster:

$ icm pull -image intersystems/webgateway:latest-em -role DATA
Pulling ANDY-DATA-TEST-0001 image intersystems/webgateway:latest-em...
...pulled ANDY-DATA-TEST-0001 image intersystems/webgateway:latest-em

Note that the -image option is not required if the image you want to pull is the one specified by the DockerImage field in the definitions file, for example:

"DockerImage": "intersystems/iris-arm64:latest-em",

Although the icm run automatically command pulls any images not already present on the host, an explicit icm pull might be desirable for testing, staging, or other purposes.

icm rm

The icm rm command deletes the specified container (or iris by default), but not the image from which it was started, from the specified nodes, or from all nodes if no machine or role is specified. Only a stopped container can be deleted.

icm upgrade

The icm upgrade command replaces the specified container on the specified machines. ICM orchestrates the following sequence of events to carry out an upgrade:

Pull the new image
Create the new container
Stop the existing container
Remove the existing container
Start the new container

By staging the new image in steps 1 and 2, the downtime required between steps 3-5 is kept relatively short.

For example, to upgrade the InterSystems IRIS container on an application server:

$ icm upgrade -image intersystems/iris:latest-em -machine ANDY-AM-TEST-0003
Pulling ANDY-AM-TEST-0003 image intersystems/iris:latest-em...
...pulled ANDY-AM-TEST-0003 image intersystems/iris:latest-em
Stopping container ANDY-AM-TEST-0003...
...completed stop of container ANDY-AM-TEST-0003
Removing container ANDY-AM-TEST-0003...
...removed container ANDY-AM-TEST-0003
Running image intersystems/iris:latest-em in container ANDY-AM-TEST-0003...
...running image intersystems/iris:latest-em in container ANDY-AM-TEST-0003

The -image option is optional for the icm upgrade command. If you do not specify an image, ICM uses the value of the DockerImage field in the instances.json file (see The Instances File in the chapter “Essential ICM Elements”). If you do specify an image, when the upgrade is complete, that value is updated with the image you specified.

Note:

The major versions of the image from which you launch ICM and the InterSystems images you deploy must match. For example, you cannot deploy a 2022.2 version of InterSystems IRIS using a 2022.1 version of ICM. Therefore you must upgrade ICM before upgrading your InterSystems containers.

If you are upgrading a container other than iris, you must use the -container option to specify the container name.

For important information about upgrading InterSystems IRIS containers, see Upgrading InterSystems IRIS ContainersOpens in a new tab in Running InterSystems Products in Containers.

As is true of ICM as a whole, the icm upgrade command is intended to be scriptable, allowing you to create varying scripted procedures for different types of upgrades so that you don’t have to repeat them manually on each occasion. For example, as noted in Upgrading a MirrorOpens in a new tab in the Installation Guide, upgrading the members of a mirror must be done in a specific order using a specific procedure; scripting the icm upgrade command lends itself to this purpose. For example, you could create a procedure incorporating some version of these basic steps:

Use the icm ps command identify the current primary failover members in a mirrored sharded cluster:

$ icm ps -container iris
Machine IP Address Container Status Health Mirror Image
------- ---------- --------- ------ ------ ------ -----
Andy-DATA-TEST-0001  35.229.124.197 iris Up healthy PRIMARY intersystems/iris:2022.1.0.205.0
Andy-DATA-TEST-0002  34.138.234.124 iris Up healthy BACKUP  intersystems/iris:2022.1.0.205.0
Andy-DATA-TEST-0003  34.139.3.48    iris Up healthy PRIMARY intersystems/iris:2022.1.0.205.0
Andy-DATA-TEST-0004  34.73.107.58   iris Up healthy BACKUP  intersystems/iris:2022.1.0.205.0

Use the -machine option with icm upgrade to selectively upgrade the backups first:
```
icm upgrade -machine ".*(2|4)" -image intersystems/iris:2022.1.0.223.0
```
Use icm upgrade -machine upgrade the primaries, causing the mirrors to fail over to the previously upgraded backups and completing the mirror upgrade:
```
icm upgrade -machine ".*(1|3)" -image intersystems/iris:2022.1.0.223.0
```

Service Management Commands

Redeploying Services