Managing your private cloud, Part 1: Introducing the WebSphere CloudBurst Appliance command line interface

The IBM® WebSphere® CloudBurst™ Appliance enables you to construct, deploy, and maintain WebSphere Application Server virtual systems in a private cloud. In order to manage the entire lifecycle of these systems in a private cloud, WebSphere CloudBurst offers multiple administration interfaces, including a rich Web 2.0 interface for GUI-based administration activities, and a command line interface (CLI) that enables a scripted, automated administration approach. This article explains how you can leverage the WebSphere CloudBurst CLI with examples of how this CLI can be put to work in your own WebSphere CloudBurst environment. This content is part of the IBM WebSphere Developer Technical Journal.

Dustin Amrhein, Staff Software Engineer, IBM

Author photoDustin Amrhein joined IBM as a member of the development team for the WebSphere Application Server. While in that position, Dustin worked primarily on web services infrastructure and web services programming models. In addition, Dustin worked on the development of a RESTful services framework for Java runtimes. In his current role Dustin is a WebSphere Client Technical Professional.


developerWorks Professional author
        level

Mike Burr (burrm@us.ibm.com), Senior Software Engineer, IBM  

Author photoMike Burr has worked for IBM since 1990 on a wide variety of products and technologies including network protocol stacks, Java virtual machines, management software and Web application servers. He is currently a member of the WebSphere Technology Institute, a group that prototypes and explores possible future directions for IBM's WebSphere line of products.



22 July 2009

Also available in Chinese

Introduction

A brief overview of the IBM WebSphere CloudBurst Appliance is in order before we discuss its administration capabilities.

WebSphere CloudBurst is an appliance that enables you to create, deploy, and monitor WebSphere Application Server virtual systems in a private cloud. It goes about accomplishing this by building value on top of IBM WebSphere Application Server Hypervisor Edition, a packaging of IBM WebSphere Application Server that is optimized for virtual environments. WebSphere Application Server Hypervisor Edition is a virtual image packaged according to the Open Virutal Format (OVF) standard, and it runs on top of supported hypervisors.

The virtual image contains an operating system, WebSphere Application Server binaries and profiles, and IBM HTTP Server, all pre-installed. The fact that multiple profiles come pre-installed enables the image to take multiple personalities upon activation (when used outside of WebSphere CloudBurst). This lays the foundation for the value delivered by WebSphere CloudBurst.

In addition to WebSphere Application Server Hypervisor Edition images, WebSphere CloudBurst also ships with WebSphere Application Server configurations, called patterns, that have been built from components within the images. For example, a WebSphere Application Server cluster pattern might contain the deployment manager component and two custom node components from the WebSphere Application Server Hypervisor Edition image. You can copy and modify the shipped patterns, plus create custom patterns using any of the components within WebSphere Application Server Hypervisor Edition. WebSphere CloudBurst automatically tunes these configurations for optimal performance based on ten years of field experience, and all patterns are stored on the appliance, enabling you to repurpose these configurations as necessary.

Beyond radically simplifying the process of building WebSphere Application Server configurations, WebSphere CloudBurst dispenses the patterns to a private cloud, thus creating WebSphere virtual systems. WebSphere CloudBurst supports a "bring-your-own-cloud" model, which means you define your own cloud resources to the appliance. This is done by supplying a set of supported hypervisors and a pool of IP addresses that are available for use in the private cloud. Once these resources are defined, WebSphere CloudBurst is able to intelligently place the virtual systems in the private cloud by accounting for cloud resource availability (CPU, memory and disk space) and other considerations, such as high availability characteristics.

To complete the full lifecycle support of WebSphere Application Server virtual systems in a private cloud, WebSphere CloudBurst supplies the capability to monitor and manage these systems. You have a view of all the virtual systems created by WebSphere CloudBurst, and you can easily monitor their resource consumption. In addition, WebSphere CloudBurst tracks usage by users of the appliance. Each user's memory consumption, CPU usage, IP utilization, and so on, is tracked to enable chargeback within an enterprise.

Futher, WebSphere CloudBurst enables you to apply both iFixes and service packs to the virtual systems within the private cloud. WebSphere CloudBurst makes applying such fixes a very low-risk proposition by automatically creating a snapshot of the virtual system before the fixes are applied. If desired, you can roll back to the prior state simply by clicking a button.

WebSphere CloudBurst is a complete solution for managing the entire lifecycle of virtual systems in a private cloud. It provides a solution to each element of the virtual system lifecycle, along the way providing an ease of use that brings unprecedented consumability to the administration of middleware environments.

Basic administration in WebSphere CloudBurst

The fact that WebSphere CloudBurst provides full control over the lifecycle of WebSphere Application Server virtual systems implies robust administration capabilities. You must be able to carry out many different tasks, including defining your private cloud, creating custom patterns, deploying patterns to the cloud, and monitoring the state of the virtual systems. To help you perform these activities, WebSphere CloudBurst provides a graphical, Web 2.0 based interface, an HTTP REST interface, and a command line interface (CLI) based on Jython 2.2.1. The graphical interface is fine for casual users, or for infrequent actions that require user intervention. The HTTP REST interface provides a programming language agnostic method for interacting with the appliance. It can also be used to include some WebSphere CloudBurst administrative tasks as part of rich enterprise mashups. For frequently performed tasks or those require little to no intervention, the CLI is the way to go.

When you sign on to the WebSphere CloudBurst console, the first panel looks similar to Figure 1.

Figure 1. WebSphere CloudBurst Administration Console
WebSphere CloudBurst Administration Console

The console provides a graphical gateway from which you can perform all the necessary administration capabilites on the WebSphere CloudBurst Appliance. The rich interface is intuitive and inviting, especially if you are new to the appliance. In addition, the console changes based on the current user so that a user sees only links for capabilities to which he has access. For example, if you only have permissions for deploying patterns to the cloud, then you would not see the Cloud, Appliance, or Catalog links in the top toolbar.

The WebSphere CloudBurst CLI gives you the capability to create a set of automated, scripted administrative tasks, and it provides an API that is both easy to use and powerful.

The remainder of this article takes a closer look at using this CLI.

Getting started with the CLI

Before you can begin working with the WebSphere CloudBurst CLI, you first need to download the tools from the WebSphere CloudBurst administration console:

  1. Log in to the console and click the Download now! link under the Use command line tools heading. A .zip file containing the command line tools will be downloaded to your machine.
  2. Expand the downloaded file to a directory, thus establishing the cloudburst.cli directory. This is the root directory for the WebSphere CloudBurst CLI tooling.
  3. You must have an IBM Java™ Runtime Environment (JRE) Version 6 installed on your machine (SR3 or higher, if using an IBM-provided JRE). If you needto, you can download a supported Linux JDK.

Resources and resource collections are the core concepts in the WebSphere CloudBurst CLI:

  • Resources are used to represent the various entities managed by the WebSphere CloudBurst Appliance. For example, each hypervisor, pattern, and virtual system is a resource. Resource objects are used in the CloudBurst CLI to read or update information about a particular entity.
  • A resource collection is a group of resource objects that are related in some way. For example, a resource collection could contain all the hypervisors defined to the WebSphere CloudBurst Appliance, or the parts contained in a given pattern. Resource collections are used to define new resources and to list or search existing resources.

The WebSphere CloudBurst CLI is based on Jython version 2.2.1, an implementation of the Python language that runs within a Java virtual machine. Commands and scripts to the WebSphere CloudBurst CLI are expressed as Python statements and expressions.

Within the Jython environment, the WebSphere CloudBurst CLI offers a special cloudburst module to interact with the appliance. All resources and resource collections are accessed through this cloudburst module, providing a consistent access pattern and reducing the risks of namespace collision with user scripts. In addition to this special module, since the CLI environment is based on Jython, you can harness the capabilities of the Java language in your administrative interactions.

The WebSphere CloudBurst CLI supports interactive and batch modes of operation, described in the next sections.

Using interactive mode

In interactive mode, you type commands into the command prompt and the console displays the results. To start an interactive session, you must provide information about the location of the WebSphere CloudBurst Appliance, as well as your login credentials.

In Listing 1, an interactive CLI session is started by typing cloudburst and providing the appliance's:

  • host name with the -h argument
  • username via the -u option
  • password via the -p option.

All commands enacted during this session will be sent to the WebSphere CloudBurst Appliance located at mycloudburst.com.

Listing 1. Initiating the CLI session
C:\cloudburst\cloudburst.cli\bin>cloudburst -h mycloudburst.com -u cloudburstUser 
	-p password

The WebSphere CloudBurst CLI also supports passing the host name, userid, and password via environment variables as well. To do so, set the CLOUDBURST_HOSTNAME, CLOUDBURST_USERID and CLOUDBURST_PASSWORD environment variables before running the cloudburst command and then omit the command line parameters shown above.

While running an interactive CLI session, the normal command shell prompt is changed to >>>. If a command extends beyond a single input line, the command prompt changes to ... to indicate that the command on the previous line is being continued. (These prompts are shown in the examples in this article when interactive mode is being illustrated to match what you will see on your screen; in other words, do not enter these prompt characters.) To exit interactive mode, enter exit and press Enter at the >>> prompt.

Listings 2 and 3 show the use of the command that displays all users in the WebSphere CloudBurst system.

Listing 2. Listing all users - command
>>> cloudburst.users
Listing 3. Listing all users - output
[
  {
    "currentmessage": "RM02011",
    "currentmessage_text": "Active in the last five minutes",
    "currentstatus": "RM01061",
    "currentstatus_text": "Logged in and active",
    "email": "",
    "fullname": "Administrator",
    "groups": (nested object),
    "id": 1,
    "parts": (nested object),
    "password": (write-only),
    "patterns": (nested object),
    "roles": (nested object),
    "scripts": (nested object),
    "username": "cbadmin",
    "virtualimages": (nested object),
    "virtualsystems": (nested object)
  }
]

Beyond simply viewing resources and resource collections, you can operate on the items managed by WebSphere CloudBurst. For example, suppose you want to add a user with permission to deploy patterns to the private cloud. You can accomplish this in a couple of different ways.

The first is to use the interactive wizard to create a new user, shown in Listings 4 and 5. Here, you are prompted to enter the username, fullname, password, and e-mail address for the new user. As a result, the new user is created, and the details of the user are displayed.

Listing 4. Creating a new user with the wizard - command
>>> cloudburst.users.create(cloudburst.wizard)
Listing 5. Creating a new user with the wizard - ouput
Enter ?? for help using the wizard.

username: newuser
fullname: Pattern Deployer
password: password
email: newuser@mycompany.com
{
  "currentmessage": "RM02013",
  "currentmessage_text": "User has not logged in yet",
  "currentstatus": "RM01062",
  "currentstatus_text": "Inactive",
  "email": "newuser@mycompany.com",
  "fullname": "Pattern Creator",
  "groups": (nested object),
  "id": 2,
  "parts": (nested object),
  "password": (write-only),
  "patterns": (nested object),
  "roles": (nested object),
  "scripts": (nested object),
  "username": "newuser",
  "virtualimages": (nested object),
  "virtualsystems": (nested object)
}

The same result can be accomplished using an inline Python dict object, shown in Listings 6 and 7. Be aware that << is an alias for the create() method used in the example above.

Listing 6. Creating a new user with JSON - command
>>> cloudburst.users << {"username":"newuser", "fullname":"Pattern Deployer", 
... "password":"password", "email":"newuser@mycompany.com"}
Listing 7. Creating a new user with JSON - output
{
  "currentmessage": "RM02013",
  "currentmessage_text": "User has not logged in yet",
  "currentstatus": "RM01062",
  "currentstatus_text": "Inactive",
  "email": "newuser@mycompany.com",
  "fullname": "Pattern Deployer",
  "groups": (nested object),
  "id": 3,
  "parts": (nested object),
  "password": (write-only),
  "patterns": (nested object),
  "roles": (nested object),
  "scripts": (nested object),
  "username": "newuser",
  "virtualimages": (nested object),
  "virtualsystems": (nested object)
}

The CLI also offers a very handy help function that you can call on resources, resource collections, and the methods of those items:

  • For a resource or resource collection, the help function provides a brief summary of the item as well as the available attributes and methods.
  • For a method, help provides a summary of the method and the input that it accepts.

Listings 8 and 9 show how you can use a help method to finid out the attributes and methods associated with a hypervisor resource.

Listing 8. Using the help function - command
>>> help(cloudburst.hypervisors[0])
Listing 9. Using the help function - output
A Hypervisor object represents a particular hypervisor defined on the
CloudBurst appliance.  Use the Hypervisor object to query and
manipulate the hypervisor definition on the appliance.  Attributes of
the hypervisor and relationships between the hypervisor and other
resources on the CloudBurst appliance are represented as Jython
attributes on the Hypervisor object.  Manipulate these Jython
attributes using standard Jython mechanisms to make changes to the
corresponding data on the CloudBurst appliance.

Additional help is available for the following methods:
   acceptCertificate, __contains__, __delattr__, delete, discover, __eq__,
   __hash__, isMaintenance, isStarted, isStatusTransient, maintenance,
   __nonzero__, refresh, __repr__, start, __str__, __unicode__, waitFor

Additional help is available for the following properties:
   address, certificate, certified, cloud, created, currentmessage,
   currentmessage_text, currentstatus, currentstatus_text, desiredstatus,
   desiredstatus_text, id, name, networks, password, storage, type, updated,
   userid

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(cloudburst.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.

Using batch mode

Aside from interactive mode, the other manner for invoking the CLI interface is batch mode. The batch mode can be invoked with either the -c or -f argument. The -c argument lets you provide a command to the invocation. For example, suppose you just wanted a quick listing of the hypervisors that make up your cloud. You can do this by initiating a CLI session and passing the appropriate command with the -c argument. As shown in Listings 10 and 11, the command is supplied at the same time the session is initiated, and so the interactive shell is not started.

Listing 10. Supplying a command to the CLI - command
C:\cloudburst\cloudburst.cli\bin>cloudburst -h mycloudburst.com -u cloudburstUser 
	-p password -c "cloudburst.hypervisors"
Listing 11. Supplying a command to the CLI - output
[
  {
    "address": "https://myhypervisor01.com/sdk",
    "certificate": (nested object),
    "certified": "T",
    "cloud": (nested object),
    "created": May 13, 2009 4:25:02 PM,
    "currentmessage": "RM03103",
    "currentmessage_text": "Started (move to maintenance mode to make changes)",

    "currentstatus": "RM01006",
    "currentstatus_text": "Started",
    "desiredstatus": "RM01006",
    "desiredstatus_text": "Started",
    "id": 1,
    "name": "Virtual WAS",
    "networks": (nested object),
    "password": "12422499021750",
    "storage": (nested object),
    "type": "ESX",
    "updated": May 13, 2009 4:25:48 PM,
    "userid": "root"
  }
]

You can also pass in multiple commands by passing in multiple -c arguments. In the command shown in Listing 12, three different commands are executed:

  • First, newuser WebSphere CloudBurst user is created.
  • The newuser e-mail address is changed to newguy@mycompany.com.
  • Finally, the current state of the resource representing newuser is retrieved.

By using multiple -c arguments, you can construct an ordered set of steps, as all commands are executed left to right.

Listing 12. Supplying multiple commands to the CLI - command
C:\cloudburst\cloudburst.cli>cloudburst -h wstiblade12.rtp.raleigh.ibm.com -u cb
admin -p cbadmin -c "newuser = cloudburst.users.create({'username':'newuser', 'fullname':'
Pattern Deployer', 'password':'password', 'email':'newuser@mycompany.com'})" -c
"newuser.email='newguy@mycompany.com'" -c "newuser”
Listing 13. Supplying multiple commands to the CLI - output
{
  "currentmessage": "RM02013",
  "currentmessage_text": "User has not logged in yet",
  "currentstatus": "RM01062",
  "currentstatus_text": "Inactive",
  "email": "newuser@mycompany.com",
  "fullname": "Pattern Deployer",
  "groups": (nested object),
  "id": 7,
  "parts": (nested object),
  "password": (write-only),
  "patterns": (nested object),
  "roles": (nested object),
  "scripts": (nested object),
  "username": "newuser",
  "virtualimages": (nested object),
  "virtualsystems": (nested object)
}
{
  "currentmessage": "RM02013",
  "currentmessage_text": "User has not logged in yet",
  "currentstatus": "RM01062",
  "currentstatus_text": "Inactive",
  "email": "newguy@mycompany.com",
  "fullname": "Pattern Deployer",
  "groups": (nested object),
  "id": 7,
  "parts": (nested object),
  "password": (write-only),
  "patterns": (nested object),
  "roles": (nested object),
  "scripts": (nested object),
  "username": "newuser",
  "virtualimages": (nested object),
  "virtualsystems": (nested object)
}

Using file mode

Using the -c argument with both interactive and batch modes is valuable for using the CLI interface to drive frequently run tasks, or to perform tasks that require constant user intervention. However, when you want to create automated administrative processes built around scripting, the WebSphere CloudBurst CLI offers file mode, which is batch mode using the -f argument.

In this mode, you initiate the session and provides a Jython script file by using the -f argument. The command syntax is the exact same as in interactive and command modes.

The script shown in Listing 14 iterates over all the patterns and displays to the console any pattern whose owner is the cbadmin user. If the script below were named findAdminPatterns.jy, it could be run as shown in Listing 15.

Listing 14. Sample WebSphere CloudBurst Jython script
cbadmin = cloudburst.users.cbadmin[0]

for pattern in cloudburst.patterns:
    if pattern.owner == cbadmin:
        print pattern
Listing 15. Invoking the CLI using the -f command - command
C:\cloudburst\cloudburst.cli\bin>cloudburst.bat -h mycloudburst.com -u cloudburstUser 
	-p password -f findAdminPatterns.jy
Listing 16. Invoking the CLI using the -f command - output
{
  "acl": (nested object),
  "advancedoptions": (nested object),
  "created": May 13, 2009 1:29:03 PM,
  "currentmessage": None,
  "currentmessage_text": None,
  "currentstatus": "RM01028",
  "currentstatus_text": "Read-only",
  "description": "Single server is a WebSphere Application Server topology or pa
rt of a WebSphere Application Server Network Deployment topology.  The single no
de can be used for a development environment, or as part of a multiple node, pro
duction environment in which the application configuration is manually duplicate
d.",
  "id": 1,
  "name": "WebSphere single server",
  "owner": (nested object),
  "parts": (nested object),
  "updated": May 13, 2009 1:29:40 PM,
  "validationmessage": "RM10051",
  "validationmessage_text": "OK",
  "validationstatus": "RM01001",
  "validationstatus_text": "Defined",
  "virtualimage": (nested object),
  "virtualsystems": (nested object)
}

Script files can create new resources and resource collections as well. The script in Listing 17 creates a script package, attaches a .zip file, and specifies the necessary run characteristics. In addition, the script creates a new cluster pattern and places the script package on the deployment manager component.

Listing 17. Create new script package and pattern
#first create the new script package
newScript = cloudburst.scripts << {'name':'Install My App'}
newScript.archive.set('c:\\apps\\myapp\\installMyApp.zip')
newScript.command = '${WAS_PROFILE_ROOT}/bin/wsadmin.sh'
newScript.location = '/opt/tmp/myapp'
newScript.log = '/opt/tmp/myapp/logs'
newScript.commandargs = '-f /opt/tmp/myapp/installMyApp.jacl'

# now create the cluster pattern
patternName = 'My Cluster Pattern'
description = 'Cluster with custom application installed'
virtualImage = cloudburst.virtualimages['WebSphere Application Server 7.0.0.3'][0]
newPattern = cloudburst.patterns << {'name': patternName, 'description': description, 
'virtualimage': virtualImage}

# create Dmgr part and add script package
dmgrPart = cloudburst.parts['Deployment manager'][0]
dmgrPpart = newPattern.parts << dmgrPart
dmgrPpart.scripts << newScript

# add a script that configures the IBM HTTP Server on the same node as the Dmgr
dmgrPpart.scripts << cloudburst.scripts['AddIhsNode'][0]

# create two custom nodes for the cluster
customNodePart = cloudburst.parts['Custom node'][0]
customNodePpart = newPattern.parts << customNodePart
customNodePpart.count = 2

After running this script using the -f command in the CLI, you should be able to verify the results by either querying the CLI for the new pattern, or by logging into the administration console. In the WebSphere CloudBurst console, you should see a pattern similar to the one shown in Figure 2.

Figure 2. New pattern in console
Newly created pattern including script package

Using batch mode with the -f argument gives you all the power of the CLI APIs, and the ability to establish an automated administration process for WebSphere CloudBurst. Keep in mind that the CLI is based on Jython 2.2.1, so most of the functionality supported by this level of Jython is available to scripts that are run within the CLI environment. For example, you can access parameters passed to scripts on the command line using the sys.argv variable.

Samples

The WebSphere CloudBurst CLI includes a samples directory that contains several scripts that can be used with the –f option described above. These scripts offer examples for different tasks that can be accomplished through scripting, and can also be used as a starting point for writing your own customized scripts. Comments documented within the scripts offer more information about the tasks that each performs.

Summary

The WebSphere CloudBurst Appliance encompasses many different resources to enable enterprises to construct private WebSphere cloud environments. In order for you to administer these different resources, the appliance provides both a graphical user interface and a command line interface. The CLI provides a Jython environment that lets you view and operate on the resources and resource collections that represent the items in your private cloud. Most administrative tasks that can be done in the GUI can be accomplished in the CLI as well. In addition, the CLI provides different modes of operation to support everything from user-driven action to fully automated tasks. Best of all, the CLI is easy to setup. All you need to do is download the tools provided by WebSphere CloudBurst and a supported JRE.

The information shared here is only a high level review of the WebSphere CloudBurst CLI, but the concepts can be extended to accomplish nearly any administrative task in the system. By learning how to use the WebSphere CloudBurst CLI, you unleash a powerful tool for administering private WebSphere cloud environments.

Resources

Learn

Get products and technologies

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into WebSphere on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=WebSphere, Architecture, Web development, Information Management
ArticleID=415458
ArticleTitle=Managing your private cloud, Part 1: Introducing the WebSphere CloudBurst Appliance command line interface
publish-date=07222009