CLI Scripting in PureApplication System

Body

 

 

CLI Scripting Crash Course

 

The PureApplication System CLI enables you to manage your environment remotely in a non-graphical interface. It provides a Jython scripting environment where you can run your own custom Python scripts or invoke individual Python C commands. Since it's built upon the REST APIs, it will allow you to perform any actions available on the REST APIs with greater flexibility and code re-usability.

The CLI comes with a small collection of useful sample scripts that can be used out-of-the-box in batch mode. With that being said, these sample scripts are also great learning resources for those who wish to create their own custom scripts. With the CLI installed, the sample scripts can be found under pure.cli/samples.

 

The CLI comes with a library of admin and deployer objects and functions that can be easily invoked within your own Python or Jython scripts. Each object's function usage can be found easily by scanning through the library's source code. The library is located under pure.cli/lib.

 

Each PureApplication System release will have a separate object library. It is downloaded automatically when you connect to a rack. If the local repository (pure.cli/lib) does not contain a library version that matches the build of your rack, a copy will be downloaded. While the object library itself exhibits this revision control behavior, the sample scripts do not. You will have to re-download the full CLI if you would like to refresh/update your sample scripts.

Similar to the PureApplication System GUI, behind the scenes, the CLI also makes REST calls (GET, POST, PUT, DELETE, etc…) to the PureSystem Manager. The file cli.log (can be found under pure.cli/logs) logs these REST calls and can be particularly useful when troubleshooting CLI exceptions. Similar to open-source tools such as Firebug, cli.log will allow you to see the REST calls and allow easy debug and code inspection. By understanding this API, system administrators will be able take full advantage of the CLI, have greater control over multiple systems, and save time and resources with code reuse.

 

 

Getting Started:

 

Browsing the object library is one way to familiarize yourself to the CLI. In interactive mode, you can also call help() on the packages to display all the objects and classes belonging to that package. Calling help() on the individual object to display usage, examples and useful functions:

 

Admin Objects (admin.*)

 

>>> help(admin)

The admin package provides several functions and objects to help you manage the IBM PureApplication System. Additional information about each of the following functions and objects is available by passing it as an argument to the help() function, for example:

>>> help(admin.clouds)

Conceptual information that helps you use the CLI:

Objects and classes for managing cloud resources:

   admin.ipgroups

...

[omitted for brevity]

...

   admin.backupLocations

>>> help(admin.user)

A User object represents a particular user defined in the system. This is read only.

 

Additional help is available for the following methods:

   __contains__, __delattr__, delete, __eq__, __hash__, isStatusTransient,

   __nonzero__, refresh, __repr__, __str__, syncRoles, __unicode__, waitFor

 

Additional help is available for the following properties:

   auth_mode, bidi_national_calendar, bidi_text_direction, created_time,

   current_status, email, groups, id, name, password, roles, shellaccounts,

   url, user_id

 

Remember to append an underscore to the property name when asking for help using a specific instance of a resource rather than the class. For example, "help(deployer.pattern.name)" or "help(mypattern.name_)" will work, but "help(mypattern.name)" will resolve the name of the pattern referenced by mypattern and attempt to provide help for the resulting string rather than the property itself.

 

 

Deployer Objects (deployer.*)

 

>>> help(deployer)

The deployer package provides several functions and objects to help you manage the pure system. Additional information about each of the following functions and objects is available by passing it as an argument to the help() function, for example:

>>> help(deployer.patterns)

   Conceptual information that helps you use the CLI:

   deployer.resource

...

[omitted for brevity]

...

   deployer.export_artifacts

>>> help(deployer.ip)

An IP object represents a particular ip address defined in the system. Unlike the object in admin package, it is read-only.

 

Additional help is available for the following properties:

   created, currentmessage, currentmessage_text, currentstatus,

   currentstatus_text, id, ipaddress, ipgroup, updated, userhostname

 

Remember to append an underscore to the property name when asking for help using a specific instance of a resource rather than the class. For example, "help(deployer.pattern.name)" or "help(mypattern.name_)" will work, but "help(mypattern.name)" will resolve the name of the pattern referenced by mypattern and attempt to provide help for the resulting string rather than the property itself.

 

 

Relationship between Collections and Objects

 

The pure.cli objects are organized by the Python native list data type. To read more about Python data structures and associated native methods, go to https://docs.python.org/2/tutorial/datastructures.html

Example: admin.users vs. admin.user

admin.users = Python list of admin.user objects

In the examples above, the admin.users collection contains admin.user objects.

>>> help(admin.user)

A User object represents a particular user defined in the system. This is read only.

 

Additional help is available for the following methods:

   __contains__, __delattr__, delete, __eq__, __hash__, isStatusTransient,

   __nonzero__, refresh, __repr__, __str__, syncRoles, __unicode__, waitFor

 

Additional help is available for the following properties:

   auth_mode, bidi_national_calendar, bidi_text_direction, created_time,

   current_status, email, groups, id, name, password, roles, shellaccounts,

   url, user_id

 

Remember to append an underscore to the property name when asking for help using a specific instance of a resource rather than the class. For example, "help(deployer.pattern.name)" or "help(mypattern.name_)" will work, but "help(mypattern.name)" will resolve the name of the pattern referenced by mypattern and attempt to provide help for the resulting string rather than the property itself.

 

>>> help(admin.users)

A Users object represents the collection of users defined to the system. Objects of this type are used to iterate over, list and search for users in the system.

 

Additional help is available for the following methods:

   admin, __contains__, create, delete, __delitem__, __getattr__,

   __getitem__, __iter__, __len__, list, __lshift__, __repr__, __rshift__,

   self, __str__, __unicode__

 

The following call demonstrates the relationship between a collection and an object in pure.cli. len(list) is a native Python function to get the size of a list. admin.users[len(admin.users)-1] will return the last user object in the users collection.

>>> admin.users[len(admin.users)-1]

  {    "auth_mode": "internal",    "bidi_national_calendar": None,    "bidi_text_direction": None,    "created_time": "Feb 4, 2015 10:12:24 AM",    "current_status": None,    "email": "test@us.ibm.com",    "groups": (nested object),    "id": "7a5ed5ba-5ac7-4f15-8ad8-57a64b47d616",    "name": "Tester Four",    "password": (write-only),    "roles": (nested object),    "shellaccounts": (nested object),    "url": "/admin/resources/users/7a5ed5ba-5ac7-4f15-8ad8-57a64b47d616",    "user_id": "tester4"  }

 

 

Create, update, delete object

 

Most collections in this library will have a create() function. Most objects will have an update() and delete() function. You can use the help() function or view the class source code to learn more about the other class-bound functions.

Usage

<collection>.create(<json_representation_of_object>)

 

Example:

>>> admin.ipgroups.create(‘name’:’IPGroup Name’, vlan: 101,‘gateway’:’172.16.32.1’,’subnet’:’172.16.32.0’,’gateway‘:'172.16.32.1’)

 

Usage:

<collection>.create(</path/to/artifact.zip>)

 

Example:

>>> deployer.virtualimages.create(‘/tmp/rhel_7.0_x64.ova’)

 

Usage:

<object>.delete()

 

Example:

>>> admin.DB2FixPacks[0].delete()

 

 

List/Filter object in collection

 

You can list all the objects in the collection, list them by index, filter them by certain fields or by a search string.

Usage:

List filtered by field: <collection>.list(<‘attribute1’:’value1’>,<‘attribute2’:’value2’>)

List filtered by string: <collection>[<search string>]

List all: <collection>

List object by index: <collection>[<index>]

 

Example:

>>> deployer.patterns.list({‘name’:’MyPattern’})

>>> deployer.patterns[“MyPattern”]

>>> deployer.patterns

>>> deployer.patterns[0]

>>> deployer.patterns[:2]

 

No wildcards needed to filter. The above will find any pattern with mypattern in its name

 

 

Iterate through all objects in a collection

 

You can incorporate any Python flow control statement to your script or on the CLI console:

Usage:

for <object> in <collection>:

    print <object>.<attribute>

 

Example:

>>> for cloud in admin.clouds:

>>>     print cloud.name

 

>>> for event in admin.events.list(‘category’:’CallHome’):

>>>     print event.create_date + ‘ : ’+ event.msg_text

 

 

Setting object attribute

 

>>> admin.computenode[0].cloud = admin.cloud[0]

>>> group.roles += admin.PERMISSION_ROLE

 

Use '=' to replace and '+=' to append

 

 

Building your own collections from REST output

 

You can use built-in helpers such as deployer.http and deployer.prettify to get direct output from http REST calls. From there they can be treated as another collection.

  from deployer import http, prettify  def getThings():          url ="<REST-URL>"          json = http.get(url)          result = prettify.PrettyList(json)          return result

 

The deployer.http helper object allows you to perform REST functions (GET, PUT, POST, DELETE) while the deployer.prettify object parses in and formats the output into usable form to the CLI.

 

Additional Reading:

• PureApplication System documentation topic - Using the command-line interface
• developerWorks article - Managing administrative access in IBM PureApplication System

 

Acknowledgements: The author would like to thank IBMer Noel Colon for his help with this material.

 

 

title image (modified) credit: (cc) Some rights reserved by Libertad