docs.intersystems.com
Home  /  Architecture  /  InterSystems Cloud Manager Guide  /  Scripting with ICM


InterSystems Cloud Manager Guide
Scripting with ICM
[Back]  [Next] 
InterSystems: The power behind what matters   
Search:  


This appendix describes how to issue a series of ICM commands from a script and how to identify and coordinate containers and services across a deployment.
ICM Exit Status
ICM sets the UNIX exit status after each command, providing a simple way to determine whether a given ICM command succeeded. The following examples examine the special variable $? after each command:
# icm inventory
Machine            IP Address     DNS Name
-------             ---------      -------
ISC-DM-TEST-0001  54.191.233.2   ec2-54-191-233-2.amazonaws.com
ISC-DS-TEST-0002  54.202.223.57  ec2-54-202-223-57.amazonaws.com
ISC-DS-TEST-0003  54.202.223.58  ec2-54-202-223-58.amazonaws.com
# echo $?
0

# icm publish
Unrecognized goal: 'publish' (try "icm -help")
# echo $?
1

# icm ps -role QM
Unrecognized role 'QM'
# echo $?
1

# icm terminal
Error: Interactive commands cannot match more than one instance
# echo $?
1
ICM Logging
ICM logs its output to a file (default icm.log) and to the console. Whereas all output is sent to the log file, its console output can be captured and split into stdout and stderr. The following example completes without error:
# icm inventory > std.out 2> std.err
# cat std.out
Machine            IP Address     DNS Name
-------             ---------      -------
ISC-DM-TEST-0001  54.191.233.2   ec2-54-191-233-2.amazonaws.com
ISC-DS-TEST-0002  54.202.223.57  ec2-54-202-223-57.amazonaws.com
ISC-DS-TEST-0003  54.202.223.58  ec2-54-202-223-58.amazonaws.com
# cat std.err
The following example contains error output:
# icm publish > std.out 2> std.err
# cat std.out
# cat std.err
Unrecognized goal: 'publish' (try "icm -help")
Remote Script Invocation
Commands can be used in combination to copy scripts to a host or container and remotely invoke them. The following example copies an exported InterSystems IRIS™ routine into an InterSystems IRIS cluster, then compiles and runs it:
# icm scp -localPath Routine1.xml -remotePath /tmp/
# icm iscos -command 'Do ##class(%SYSTEM.OBJ).Load("/tmp/Routine1.xml", "c-d")'
# icm iscos -command 'Do ^Routine1'
This example copies a shell script to the host, changes its permissions, and executes it:
# icm scp -localPath script1.sh -remotePath /tmp/
# icm ssh -command 'sudo chmod a+x /tmp/script1.sh'
# icm ssh -command '/tmp/script1.sh abc 123'
This example does the same thing, but within a custom or third-party container:
# icm cp -localPath script2.sh -remotePath /tmp/ -container gracie
# icm exec -command 'chmod a+x /tmp/script2.sh' -container gracie
# icm exec -command '/tmp/script2.sh abc 123' -container gracie
Using JSON Mode
Your script may need to gather information from ICM about the state of the cluster. Examples would be:
Parsing the human-readable output of ICM is difficult and prone to breakage. A more reliable solution is to have ICM generate its output in JSON format using the json option. The output iswritten to a file named response.json in the current working directory.
Normal Output
Most ICM commands do not result in any output upon success, in which case the exit value will be 0, no output will be written to stderr, and the JSON will be the empty array:
# icm exec -command "ls /" -json
# cat response.json
[]
ICM commands that produce useful output on success are detailed in the following. Note that the order of fields is not guaranteed.
icm inventory
The format of the icm inventory command is an array whose elements correspond to each provisioned instance; each element in turn contains a list of the name-value pairs machineName, ipAddress, and dnsName, as shown in the following:
# icm inventory -json
Machine            IP Address     DNS Name
-------             ---------      -------
ISC-DM-TEST-0001  54.191.233.2   ec2-54-191-233-2.amazonaws.com
ISC-DS-TEST-0002  54.202.223.57  ec2-54-202-223-57.amazonaws.com
ISC-DS-TEST-0003  54.202.223.58  ec2-54-202-223-58.amazonaws.com

# cat response.json
[
  {
    "machineName": "ISC-DM-TEST-0001",
    "ipAddress": "54.191.233.2",
    "dnsName": "54_191_233_2.amazonaws.com"
  },
  {
    "machineName": "ISC-DS-TEST-0002",
    "ipAddress": "54.202.223.57",
    "dnsName": "54_202_223_57.amazonaws.com"
  }
  },
  {
    "machineName": "ISC-DS-TEST-0002",
    "ipAddress": "54202.223.58",
    "dnsName": "54_202_223_58.amazonaws.com"
  }
]
icm ps
The format of the icm ps command is an array whose elements correspond to each container; each element in turn is a list of the name-value pairs machineName, container, status, and image.
# icm ps -json
Machine            IP Address    Container  Status  Image
-------             ---------    --------   -----   ----
ISC-DM-TEST-0001  54.191.233.2   iris       Up      isc/iris:stable
ISC-DM-TEST-0001  54.191.233.2   spark      Exited  isc/spark-2.1:latest
ISC-DS-TEST-0002  54.202.223.57  iris       Up      isc/iris:stable
ISC-DS-TEST-0002  54.202.223.57  spark      Exited  isc/spark-2.1:latest
ISC-DS-TEST-0003  54.202.223.58  iris       Up      isc/iris:stable
ISC-DS-TEST-0003  54.202.223.58  spark      Exited  isc/spark-2.1:latest

# cat response.json
[
  {
    "machineName": "ISC-DM-TEST-0001",
    "container": "iris",
    "status": "Up",
    "image": "isc/icm:stable"
  },
  {
    "machineName": "ISC-DM-TEST-0001",
    "container": "spark",
    "status": "Exited",
    "image": "isc/icm:stable"
  },
  {
    "machineName": "ISC-DS-TEST-0002",
    "container": "iris",
    "status": "Up",
    "image": "isc/icm:stable"
  },
  {
    "machineName": "ISC-DS-TEST-0002",
    "container": "spark",
    "status": "Exited",
    "image": "isc/icm:stable"
  },
  {
    "machineName": "ISC-DS-TEST-0003",
    "container": "iris",
    "status": "Up",
    "image": "isc/icm:stable"
  },
  {
    "machineName": "ISC-DS-TEST-0003",
    "container": "spark",
    "status": "Exited",
    "image": "isc/icm:stable"
  }
]
Abnormal Output
When an error occurs, the format of the JSON output depends on whether the error occurred local to the ICM application or was from a target application on the host or instance.
Local Errors
When an ICM command results in an error, the JSON will contain an object and a name-value pair describing the error, as follows:
# icm ps -role QM -json
Unrecognized role 'QM'

# cat response.json
{
    "error": "Unrecognized role 'QM'"
}
Remote Errors
A remote error is considered to have occurred when one or more of the following is true:
When a remote error occurs, the JSON will be an array of objects containing name-value pairs; the name corresponds to that of the target machine, and the value is another object containing a list of name-value pairs including one or more of the following:
Here is an example:
# icm ssh -command "ls file.txt" -json
Executing command 'ls file.txt' on host ISC-DM-TEST-0001...
ls: cannot access file.txt: No such file or directory
Error: See tmp/DM-TEST/DM-TEST-0001/ssh.err
Errors occurred during execution; aborting operation

# cat response.json
[
  {
    "ISC-DM-TEST-0001": {
      "file": "tmp/DM-TEST/DM-TEST-0001/ssh.err"
    }
  }
]

# cat tmp/DM-TEST/DM-TEST-0001/ssh.err
ls: cannot access file.txt: No such file or directory