Using ICM with Custom and Third-Party Containers

Important:

As of release 2023.3 of InterSystems IRIS, InterSystems Cloud Manager (ICM) is deprecated; it will be removed from future versions.

This page describes using ICM to deploy customer and third-party containers. Instructions assume that your Docker image resides in a repository accessible by ICM. For information on how to configure your container to communicate with other containers and services (including InterSystems IRIS), see Scripting with ICM.

Container Naming

Each container running on a given host must have a unique name. When deploying a container using icm run, the container can be named using the -container option:

# icm run -container gracie -image docker/whalesay

You can see the name reflected in the output of icm ps:

# icm ps
Machine           IP Address   Container Status     Health  Image
-------           ---------    --------  -----      ------  ----
Acme-DM-TEST-0001 172.16.110.9 gracie    Restarting         docker/whalesay

Note:

If the -container option is not provided, the default container name iris is used. This name is reserved and should be used only for containers derived from InterSystems IRIS images provided by InterSystems.

Overriding Default Commands

If you want to override a container's default command, you can do so with -command. For example, suppose the docker/whalesay image runs command /bin/bash by default:

# icm docker -command "ps -a"

CONTAINER ID  IMAGE            COMMAND      CREATED     STATUS      NAMES
17f4ece54c2f  docker/whalesay  "/bin/bash"  4 days ago  Restarting  gracie

To have the container run a different command, such as pwd, you could deploy it as follows:

# icm run -container gracie -image docker/whalesay command pwd

You can verify that the command succeeded by examining the Docker logs:

# icm docker -command "logs gracie"
/cowsay

Using Docker Options

Your container may require Docker options or overrides not explicitly provided by ICM; these can be included using the -options option. This section provides examples a few of the more common use cases. For complete information about Docker options see https://docs.docker.com/engine/reference/run/Opens in a new tab.

Restarting

By default, ICM deploys containers with the option --restart unless-stopped. This means that if the container crosses an execution boundary for any reason other than an icm stop command (container exit, Docker restart, and so on), Docker keeps attempting to run it. In certain cases however, we want the container to run once and remain terminated. In this case, we can suppress restart as follows:

# icm run -container gracie -image docker/whalesay -options "--restart no"
# icm ps
Machine           IP Address   Container Status     Health   Image
-------           ---------    --------  -----      ------   -----
Acme-DM-TEST-0001 172.16.110.9 gracie    Exited (0)          docker/whalesay

Privileges

Some containers require additional privileges to run, or you may want to remove default privileges. Examples:

# icm run -container sensors -image hello-world -options "--privileged"
# icm run -container fred -image hello-world -options "--cap-add SYS_TIME"
# icm run -container fred -image hello-world -options "--cap-drop MKNOD"

Environment Variables

Environment variables can be passed to your container using the Docker option --env. These variables are be set within your container in a manner similar to the bash export command:

# icm run container fred image hello-world options "--env TERM=vt100"

Mount Volumes

If your container needs to access files on the host machine, a mount point can be created within your container using the Docker --volume option. For example:

# icm run container fred image hello-world options "--volume /dev2:/dev2"

This makes the contents of directory /dev2 on the host available at mount point /dev2 within the container:


# icm ssh -command "touch /dev2/example.txt"  // on the host
# icm exec -command "ls /dev2"                // in the container
example.txt

Ports

Ports within your container can be mapped to the host using the Docker option --publish:

# icm run -container fred -image hello-world -options "--publish 80:8080"
# icm run -container fred -image hello-world -options "--publish-all"

You must open the corresponding port on the host if you wish to access the port from outside. This can be achieved in a number of ways, including:

By editing the Terraform template file infrastructure.tf directly.
By issuing commands to the host using the icm ssh command.
By modifying the security settings in the console of the cloud provider.

You also have to ensure that you are not colliding with a port mapped to another container or service on the same host. Finally, keep in mind that --publish has no effect on containers when the overlay network is of type host.

The following example modifies the Terraform template for AWS to allow incoming TCP communication over port 563 (NNTP over TLS):

File: /ICM/etc/Terraform/AWS/VPC/infrastructure.tf
Resource: aws_security_group

Rule:

ingress {
  from_port = 563
  to_port = 563
  protocol = "tcp"
  cidr_blocks = ["0.0.0.0/0"]
}

Deploying on a Preexisting Cluster

Scripting with ICM