InterSystems Cloud Manager Guide
Sharing ICM Deployments
There are a number of situations in which different users on different systems might want to use ICM to manage or interact with the same deployment. For example, one user may be responsible for provisioning the infrastructure, while another in a different location is responsible for application deployment and upgrades.
However, ICM deployment is defined by its input files and results in the generation of several output files. Without access to these state files in the ICM container from which the deployment was made, it is difficult for anyone to manage or monitor the deployment (including the original deployer, should those files be lost).
To aid in this task, ICM can be run in distributed management mode
, in which it stores the deployment’s state files on a Consul cluster for access by other additional ICM containers. If distributed management mode is not used, state files can also be shared manually
ICM’s distributed management mode uses the Consul service discovery tool from Hashicorp to give multiple users in any networked locations management access to a single ICM deployment. This is done through the use of multiple ICM containers, each of which includes a Consul client clustered with one or more Consul servers storing the needed state files.
Deploys 1, 3, or 5 Consul servers on CN
nodes, which are clustered together with its Consul client.
Pushes the deployment’s state files (see State Files
for specifics) to the Consul cluster.
Outputs a docker run
command for creating subsequent ICM containers for the deployment.
To create the primary ICM container and the Consul cluster, do the following:
Possible values are 1, 3, and 5. A single Consul server represents a single point of failure and thus is not recommended. A five-server cluster is more reliable than a three-server cluster, but incurs greater cost.
Include a CN node definition in the definitions.json
file specifying at least as many CN nodes as the value of the ConsulServers
field, for example:
Add the consul.sh
script in the ICM container to the docker run
command for the primary ICM, as follows:
docker run --name primaryICM -it --cap-add SYS_TIME intersystems/icm:stable consul.sh
When you issue the icm provision
command on the primary ICM command line, a Consul server is deployed on each CN node as it is provisioned until the specified number of servers is reached. When the command concludes successfully, the primary ICM pushes the state files to the Consul cluster, and its output includes the secondary ICM creation command. When you subsequently issue any command in the primary ICM that might alter the instances.json
file, such as icm run
or icm upgrade
, the primary ICM pushes the new file to the Consul cluster. When you use the icm unprovision
command in the primary ICM to unprovision the deployment, its state files are removed from the Consul cluster.
A Consul gossip encryption key, used by the secondary ICM’s Consul client to join the cluster.
The IP address of any one of the Consul servers, used by the client to find the cluster.
A Consul token, used to control access to data on the cluster.
docker run -it --name ICM --cap-add SYS_TIME intersystems/icm:stable consul.sh \
qQ6MPKCH1YzTb0j9Yst33w== 220.127.116.11 47d2b28c-b978-44d3-8126-aeef1a33eb80
You can use the secondary ICM creation command as many times as you wish, in any location that has network access to the deployment.
In both primary and secondary ICM containers, the consul members
command can be used to display information about the Consul cluster, for example:
/Samples/GCP # consul members
Node Address Status Type Build Protocol DC Segment
consul-ACME-CN-TEST-0002.weave.local 18.104.22.168:8301 failed server 1.1.0 2 dc1 <all>
consul-ACME-CN-TEST-0003.weave.local 22.214.171.124:8301 alive server 1.1.0 2 dc1 <all>
consul-ACME-CN-TEST-0004.weave.local 126.96.36.199:8301 alive server 1.1.0 2 dc1 <all>
3be7366b4495 172.17.0.4:8301 alive client 1.1.0 2 dc1 <default>
e0e87449a610 172.17.0.3:8301 alive client 1.1.0 2 dc1 <default>
Consul containers are also included in the output of the icm ps
command, as shown in the following:
Samples/GCP # icm ps
Pulling from consul cluster...
...pulled from consul cluster
Machine IP Address Container Status Health Image
------- ---------- --------- ------ ------ -----
ACME-DM-TEST-0001 188.8.131.52 weave Up weaveworks/weave:2.3.0
ACME-DM-TEST-0001 184.108.40.206 weavevolumes-2.3.0 Created weaveworks/weaveexec:2.3.0
ACME-DM-TEST-0001 220.127.116.11 weavedb Created weaveworks/weavedb:latest
ACME-CN-TEST-0004 18.104.22.168 consul Up consul:1.1.0
ACME-CN-TEST-0004 22.214.171.124 weave Up weaveworks/weave:2.3.0
ACME-CN-TEST-0004 126.96.36.199 weavevolumes-2.3.0 Created weaveworks/weaveexec:2.3.0
ACME-CN-TEST-0004 188.8.131.52 weavedb Created weaveworks/weavedb:latest
ACME-CN-TEST-0002 184.108.40.206 consul Up consul:1.1.0
ACME-CN-TEST-0002 220.127.116.11 weave Up weaveworks/weave:2.3.0
ACME-CN-TEST-0002 18.104.22.168 weavevolumes-2.3.0 Created weaveworks/weaveexec:2.3.0
ACME-CN-TEST-0002 22.214.171.124 weavedb Created weaveworks/weavedb:latest
ACME-CN-TEST-0003 126.96.36.199 consul Up consul:1.1.0
ACME-CN-TEST-0003 188.8.131.52 weave Up weaveworks/weave:2.3.0
ACME-CN-TEST-0003 184.108.40.206 weavevolumes-2.3.0 Created weaveworks/weaveexec:2.3.0
ACME-CN-TEST-0003 220.127.116.11 weavedb Created weaveworks/weavedb:latest
Because no concurrency control is applied to ICM commands, simultaneous conflicting commands issued in different ICM containers cannot all succeed; the results are based on timing and may include errors. For example, suppose two users in different containers simultaneously issue the command icm rm -machine ACME-DM-TEST-0001
. One user will see this:
Removing container iris on ACME-DM-TEST-0001...
...removed container iris on ACME-DM-TEST-0001
while the other will see the following:
Removing container iris on ACME-DM-TEST-0001...
Error: No such container: iris
This section explains how to share ICM deployments manually, describing which state files are required to share a deployment, methods for accessing them from outside the container, and how to persist those files so an ICM-driven deployment can be shared with other users or accessed from another location.
The state files are read from and written to the current working directory, though all of them can be overridden to use a custom name and location. Input files are as follows:
Any security keys, InterSystems IRIS™ licenses, or other files referenced from within these configuration files should be considered input as well.
Output files are as follows:
The layout of the files under ICM-GUID
/ is as follows:
Under each definition directory are the following files:
A variety of log files, temporary files, and other files appear in this hierarchy as well, but they are not required for sharing a deployment.
For provider PreExisting, no Terraform files are generated.
InterSystems recommends that you avoid generating state files local to the ICM container, for the following reasons:
Immutability is violated.
Data can be lost if container removed/updated/replaced.
Ability to edit configuration files within the ICM container is limited.
Tedious and error-prone copying of state files out of the container is required.
A better practice is to mount a directory from the host within the ICM container to use as your working directory; that way all changes within the container are always available on the host. This can be accomplished using the Docker --volume
option when the ICM container is first created, as follows:
$ docker run it -cap-add SYS_TIME --volume <host_path>:<container_path> <image>
Overall, you would take these steps:
Create, start, and attach to ICM container.
Issue ICM commands.
Exit or detach from ICM container.
The state files (both input and output) are then present in host_path
. See the sample script in Launch ICM
for an example of this approach.
Methods of preserving and sharing state files with others include:
Make a tar/gzip
The resulting archive can be emailed, put on an FTP site, a USB stick, and so on.
Make backups to a location from which others can restore
Register the path to the state files on the host with a backup service.
Mount a disk volume accessible by others in your organization
The path to the state files could be a Samba mount, for example.
Specify a disk location backed up to the cloud
You might use services such as Dropbox, Google Drive, OneDrive, and so on.
Store in a document database
This could be cloud-based or on-premises.
The advantage of the latter three methods is that they allow others to modify the deployment. Note however that ICM does not support simultaneous operations issued from more than one ICM container at a time, so a policy ensuring exclusive read-write access would need to be enforced.
Content Date/Time: 2019-04-10 14:45:56