Scripting in IBM PureApplication System


The PureApplication System command-line interface (CLI) tool provides a scripting environment in which you can run commands to manage PureApplication System remotely. You can also run Python scripts or individual Python commands. The scripting environment is based on Jython, the Java-based implementation of Python. The Jython interpreter implements some of the Python 2.5.1 language. The CLI uses the Jython interpreter, along with standard Jython libraries, functions, and classes to help you manage your PureApplication System environment.

In addition to the Jython-based scripting environment, PureApplication System provides a REST API that enables you to write scripts in any programming language.

Getting started

Before getting started, go to the PureApplication System Knowledge Center and bookmark the following two topics:

You can download PureCLI from the PureApplication System Welcome page. Figure 1 shows the download screen:

Figure 1. Downloading the CLI
Downloading the CLI
Downloading the CLI

The download is a zip file, so extract it into a directory such as /purecli.. Listing 1 shows an example directory structure from a PureCLI installation:

Listing 1. PureCLI directory structure
├── bin
│  ├──
│  └──
├── lib
│  ├──
│ │  ├── admin
│ │ │  ├── resources
│ │ │  ├── settings
│ │ │  └── troubleshooting
│ │  ├── deployer
│ │ │  ├── messages
│ │ │ │  └── ext
│ │ │  ├── resources
│ │ │  └── settings
│ │  └── utility
│  └──
│      ├── admin
│      │  ├── resources
│      │  ├── settings
│      │  └── troubleshooting
│      ├── deployer
│      │  ├── messages
│      │ │  └── ext
│      │  ├── resources
│      │  └── settings
│      └── utility
├── logs
└── samplesCODE

The bin and lib directories have subdirectories for two versions: and PureCLI automatically updates to a new version if it detects it in IBM PureApplication System.

Hello World example

With PureCLI, the equivalent of a Hello World example is to access PureApplication System from the command line. Go to the bin directory and execute pure (or pure.bat on Windows®). It should give you the results shown in Listing 2:

Listing 2. Executing pure
    pure -h [HOST] -u [USER] -p [PASSWORD]
    pure -h [HOST] -u [USER] -p [PASSWORD] -c [COMMAND]
    pure -h [HOST] -u [USER] -p [PASSWORD] -f [SCRIPT_FILE] [ARG]*

Verify that the host name or IP address is correct and that the machine running the CLI command has network connectivity to Port 443. Modify the command line with the correct host and credentials, execute it again, and you should get the output in Listing 3:

Listing 3. Connected to PureApplication System
Welcome to the IBM PureApplication System CLI.  Enter "help" if you need help getting started.

Enter the help command to get started. Listing 4 shows an excerpt of the help:

Listing 4. Excerpt of help
In addition to the standard Jython libraries, the CLI provides a rich set of functions and classes
in the admin and deployer packages to help you manage your system.  More extensive help is available
for the deployer and admin packages by entering:
   >>> help(deployer)
   >>> help(admin)

Now you can start using PureCLI for some real work.

Using PureCLI

As in the above section, you can use PureCLI interactively. Among the uses for interactive mode are testing commands before putting them in a file, and obtaining help for PureCLI commands. For example, to find out how many compute nodes you have in your PureApplication System, use the following commands:

  • Enter help(admin) to get help about available functions. You see that there is function called admin.computenodes.
  • Execute admin.computenodes to get a list of JSON formatted objects about compute nodes.
  • To get the total number of compute nodes, enter len(admin.computenodes). It returns the number 6, which means you have six compute nodes in PureApplication System.

As an example of typical output, Listing 5 shows a JSON object of a single compute node:

Listing 5. Compute node JSON object
  "acl": (nested object),
  "architecture": "10X",
  "cloud": (nested object),
  "energystats": (nested object),
  "firmwarelevel": "1AOO56G",
  "healthstats": (nested object),
  "id": "176bc2b8-a41c-4468-9236-cb1f62dcac64",
  "leds": (nested object),
  "locations": (nested object),
  "machinetype": "7863",
  "name": "SN#10B4E6B",
  "numberofpowercycles": 3,
  "physicalcpus": (nested object),
  "physicalioadapters": (nested object),
  "physicalmemory": (nested object),
  "powerstate": "powered_on",
  "pvuvalue": 70,
  "state": "available",
  "vios": (nested object),
  "virtualmachines": (nested object)

Many attributes have (nested object) as a value. To get the JSON object of nested objects, simply enter the attribute name in the function call. For example, to get all of the virtual machines of the first compute node, enter the command: admin.computenodes[0].virtualmachines.

There are many objects and functions available with PureCLI, and you can control all of PureApplication System from the command line, without using the browser GUI.

As shown in Listing 2, you can execute script files with PureCLI, which is how the CLI is typically used. Interactive PureCLI is a good way to learn about and test various ways to get what you need, and when you know what you need, you can put the commands in a script.

Managing workloads

A workload is an instance of a pattern running in PureApplication System. Patterns are one of the key technologies of PureApplication System and a pattern is a complete architecture of your application. Using PureCLI, you can deploy and manage patterns from the command line and you can script and automate deployments and other related tasks.

The PureCLI command help(deployer) gives available functions to manage workloads. The following section provides an example of using PureCLI.

Deploying a pattern

A real-life example of using PureCLI scripting is to deploy a pattern and view the status of the deployment. Listing 6 shows a script that you can use to deploy a pattern, and Listing 7 shows the deployment status.

The deploy script in Listing 6 accepts two command-line arguments, pattern name and environment profile name. Two arguments are all that are needed to deploy a pattern. When deployment starts, the virtual instance ID is printed to the console and saved to a file for later use.

Listing 6. Deploy a pattern
import sys
import time
import os

if len(sys.argv)!=3:
  print "Usage: %s <pattern name> <environment profile name>"

#pattern name and env profile name as arguments
print "Deploying pattern '%s' to profile '%s'..." %  \
#retrieve pattern and environment profile objects from PureApplication
#based on given names
mypattern=deployer.virtualsystempatterns.list({"app_name": patternName})[0]
#initiate deployment
virtualInstance=mypattern.deploy("%s %s" %
#get instance ID
#print out ID and save ID to a file, for later use
print "Pattern %s is deploying. ID: %s" % (patternName,virtualInstanceID)

After deployment has started, you can view the deployment status using the script in Listing 7:

Listing 7. Get the deployment status
import sys
import time
import os

if len(sys.argv)==2:
  #read virtual instance id from command line
  #read id from a file
#get instance
if len(instances)==0:
  print "Instance %s does not exist." % (virtualInstanceID)
  #print deployment history
  for line in history:
    print "%s: %s" % (line['created_time'],line['current_message'])
  print 'Instance "%s"... %s' % (name,status)
  if status=="RUNNING":
    #list virtual machines
    print 'Virtual machines:'
    for vm in virtualmachines:
      print "  %s (%s): %s" % (hostname,ipaddr,name)

The script reads the virtual instance ID from a file that was written by the deployment script in Listing 6. You can also provide the virtual instance ID as a command-line argument. The ID is used to get the instance object, and the script prints out the deployment history. If the instance is running, the script displays the name, hostname, and IP address of each virtual machine in the virtual system instance. Listing 8 shows an example of deployment status:

Listing 8. Deployment status
2015-03-23T08:56:27.047Z: Deployment has been queued
2015-03-23T08:56:30.058Z: Reserving cloud resources
2015-03-23T08:56:32.528Z: Generating model for topology and network
2015-03-23T08:56:37.408Z: Pattern deployment starting
2015-03-23T08:56:38.398Z: Registering virtual system sjs Base OS 105502
2015-03-23T08:58:40.275Z: Added new disk for virtual machine OS_Node.11427100964512 of size 20 GB
2015-03-23T08:58:40.876Z: Starting virtual machines in virtual system sjs Base OS 105502
2015-03-23T08:58:40.898Z: Starting virtual machine OS_Node.11427100964512
2015-03-23T08:59:52.763Z: Executing script packages
     Executing script package Default add disk on virtual machine OS_Node.11427100964512
     Script package Default add disk on virtual machine OS_Node.11427100964512 completed successfully
     Executing script package Must Gather Logs on virtual machine OS_Node.11427100964512
     Script package Must Gather Logs on virtual machine OS_Node.11427100964512 completed successfully
     Virtual machines are ready
Instance "sjs Base OS 105502"... RUNNING
Virtual machines: ( OS_Node.11427100964512

If you want to, you can delete the running instance using the command deployer.virtualsysteminstances.delete(virtualInstanceID).

Using the REST API

PureCLI is very useful, and the REST API is even more useful -- in fact, PureCLI itself uses the REST API. To use the REST API, you don't need to download anything -- you can just start using it from the command line using curl, or using your favorite programming language. Listing 9 shows how to access the REST API using the curl command:

Listing 9. curl access to PureApplication System
curl --cacert <IPASHOSTORIP> -k -H "X-IBM-PureSystem-API-Version: 1.0" 
-H "Accept: application/json" --user <UID>:<PWD> https://<IPASHOSTORIP><RESTPATH>

IPASHOSTORIP is the address to PureApplication System, UID and PWD are self-explanatory, and RESTPATH is the path to the resource.

Listing shared services

An obvious use case for the REST API is when you need something that is not readily available in PureCLI, such as getting a listing of shared service instances and how much RAM and CPU they are using.

Output from the REST API is JSON. If you use Python for scripting, the simplejson module converts JSON strings to easily consumable Python objects.

Listing 10 shows a script that lists shared services using a REST API call. The script includes a Python wrapper to curl, and it is executed using the normal python interpreter, without the need for PureCLI:

Listing 10. Get shared services instances using the REST API
import sys
import time
import os
import simplejson

if len(sys.argv)!=4:
  print "Usage: %s <ip address> <uid> <pwd>" % sys.argv[0]


#call REST API using curl and return JSON
def callREST(path):
  cmd=["curl","--cacert",pureappIPAddress,"https://%s%s" %
     "-k","-H",'"X-IBM-PureSystem-API-Version: 1.0"',
     "-H",'"Accept: application/json"', "--user"," %s:%s" % (uid,password)]
  cmd= " ".join(cmd)
  rc= os.system(cmd+" > "+fname+" 2> err_output.txt")
  json = simplejson.loads(jsonStr)
  if rc != 0:
    print "some error happened: %d" % rc
  return json

print "Available services:"
for svc in json:
  if name not in alreadyPrinted:
    print "  %s" % (name)
print "Deployments:"
for svc in json:
  print "  Name: %s" % svc["deployment_name"]
  for instance in svc["instances"]:
    print "    %s (RAM: %d MB, vCPU: %d) %s" %
  print "    Total: RAM: %.2f GB, vCPU: %d" % (totalram/1000.0,totalcpu)
print "Totals for shared services:"
print "  RAM : %.2f GB" % totalramforsvc
print "  vCPU: %d" % totalcpuforsvc

The above script calls the REST API via a curl wrapper function and returns JSON. Relevant parts of the JSON that list all shared instances are then printed, as well as some information about the services. Here is an excerpt of the output:

Listing 11. Excerpt of output of sharedsvc script
Name: Caching Service
  Caching-Catalog.21421683118601 (RAM: 16768 MB, vCPU: 2) ipas3-CloudGroup1
  Caching-Catalog.11421683118600 (RAM: 16768 MB, vCPU: 2) ipas3-CloudGroup1
  Caching-Container.11421683118602 (RAM: 15744 MB, vCPU: 2) ipas3-CloudGroup1
  Caching-Master.11421683118599 (RAM: 16768 MB, vCPU: 2) ipas3-CloudGroup1
  Total: RAM: 66.05 GB, vCPU: 8
Name: ELB Proxy Service
  Services-elbInstance.11422448392023 (RAM: 4864 MB, vCPU: 2) ipas3-CloudGroup2
  Services-elbManagement.11422448392022 (RAM: 2432 MB, vCPU: 1) ipas3-CloudGroup2
  Services-elbInstance.21422448392024 (RAM: 4864 MB, vCPU: 2) ipas3-CloudGroup2
  Total: RAM: 12.16 GB, vCPU: 5
Totals for shared services:
  RAM : 146.43 GB
  vCPU: 36


This tutorial showed some examples of using the IBM PureApplication System CLI and REST API. Both of these tools are well documented, and you can use them to automate many tasks related to PureApplication System. Access control mechanisms in PureApplication System make these tools available to all users of PureApplication System, ranging from system administrators to individual contractors deploying single development environments for their personal use.


The author would like to thank IBM colleague Marcus Törnqvist for reviewing this article.

Downloadable resources

Related topics


Sign in or register to add and subscribe to comments.

Zone=Cloud computing, Middleware
ArticleTitle=Scripting in IBM PureApplication System