Professional Documents
Culture Documents
Managing Your Private Cloud, Part 2
Managing Your Private Cloud, Part 2
Dustin Amrhein
Staff Software Engineer
IBM
04 Nov 2009
Several interface options are available to help you to interact with the IBM®
WebSphere® CloudBurst™ Appliance, which provides functionality for creating,
deploying, and managing IBM WebSphere Application Server virtual systems in a
private cloud. These interfaces include a Web 2.0 graphical user interface, a Jython
command line interface, and an HTTP REST API. This article discusses the HTTP
REST API, which provides a language-neutral interface that is ideal for integrating
WebSphere CloudBurst capabilities into existing applications or user interfaces.
Introduction
The IBM WebSphere CloudBurst Appliance provides you with the capability to
manage the full lifecycle of WebSphere Application Server virtual systems in a
private cloud, including the ability to create, deploy, and manage such virtual
systems.
Three user interfaces enable you to leverage the function of the appliance:
• The Web 2.0 graphical user interface (GUI) is generally the right fit for
infrequently performed actions or for introducing new users to the
capabilities of the appliance.
When using the REST API, you also need to be aware of certain HTTP headers that
are required in every request. Table 1 provides a listing of those headers and a brief
explanation of their use.
The remainder of this article presents examples that illustrate how the WebSphere
CloudBurst REST API can be used, specifically to:
This article does not dictate the use of any particular HTTP client to make these
requests. In fact, any client (programattic or otherwise) that is capable of sending
HTTP requests with the headers and body format specified in this article can be
used to communicate with the WebSphere CloudBurst Appliance through the REST
API.
For the purpose of illustrating the results of the HTTP requests that are shown here,
screen captures of the graphical user interface are also presented on occasion.
Also, these examples assume that the appliance is available using the
mycloudburst.com host name.
• Creating a hypervisor.
• Adding the hypervisor to a cloud group.
• Defining an IP group to be used by the hypervisor.
To carry out these actions using the REST API, you must be a user with at least
Cloud Administration role permissions.
URL: https://mycloudburst.com:443/resources/hypervisors
HTTP Method: POST
HTTP request headers:
HTTP Body:
Accept: application/json
Accept-Language: en
Authorization: Basic <base64encode(userid:password)>
Content-Type: application/json
X-CloudBurst-API-Version: 1.0
HTTP request body:
{
"address": "ftchypervisor-1.com",
"name": "Functional test hypervisor - 1",
"password": "ftpassword",
"type": "ESX",
"userid": "ftuser"
}
{
"desiredstatus_text": "Maintenance mode",
"currentstatus_text": "Maintenance mode",
"networks": [
],
"userid": "root",
"certified": "I",
"created": 1251407372817,
"name": "Functional test hypervisor - 1",
"currentstatus": "RM01025",
"desiredstatus": "RM01025",
"currentmessage": "RM03106",
"address": "https://ftchypervisor-1.com/sdk",
"cloud": null,
"type": "ESX",
"storage": [
],
"updated": 1251407372817,
"id": 5,
"password": "125140737281455",
"currentmessage_text": "Maintenance mode (must add to a cloud group to start)"
}
2. Next, you need to accept the SSL certificate of the hypervisor that you
just created. To do this, you need to send an HTTP GET request to the
resources/hypervisors/<hypervisor_id>certificate URL.
For the hypervisor above, you could accept the certificate by sending a
GET request to the
https://mycloudburst.com:443/resources/hypervisors/5/certificate
URL. The contents of the SSL certificate are returned in the HTTP
response body sent back as a result of this GET request. After issuing
this request, send a PUT request to the hypervisor, updating the value of
the certified attribute from I to T (Listing 2). This PUT request indicates
that the SSL certificate for this hypervisor resource has been accepted.
Listing 2. Accept the SSL certificate - Request
URL: https://mycloudburst.com:443/resources/hypervisors/5
HTTP Method: PUT
HTTP request headers:
Accept: application/json
Accept-Language: en
Authorization: Basic <base64encode(userid:password)>
Content-Type: application/json
X-CloudBurst-API-Version: 1.0
HTTP request body:
{
"desiredstatus_text": "Maintenance mode",
"currentstatus_text": "Maintenance mode",
"networks": [
],
"userid": "root",
"certified": "T",
"created": 1251408002475,
"name": "Functional test hypervisor - 1",
"currentstatus": "RM01025",
"desiredstatus": "RM01025",
"currentmessage": "RM03106",
"address": "https://ftchypervisor-1.com/sdk",
"cloud": null,
"type": "ESX",
"storage": [
],
"updated": 1251408002475,
"id": 5,
"password": "125140800247456",
"currentmessage_text": "Maintenance mode (must add to a cloud group to start)"
}
Now that you have accepted the SSL certificate associated with the
hypervisor and changed the state of the hypervisor resource to indicate
this acceptance, WebSphere CloudBurst will begin to automatically detect
the storage and networks for the hypervisor. Once the storage and
networks have been detected, the appropriate attributes will be
automatically updated on the hypervisor resource.
3. The next step in setting up your private cloud is to add your newly created
hypervisor to a cloud group. To do this, you will first create a resource
representing the cloud group (Listings 3a and 3b).
Listing 3a. Create a new cloud group - Request
URL: https://mycloudburst.com:443/resources/clouds
HTTP Method: POST
HTTP request headers:
Accept: application/json
Accept-Language: en
Authorization: Basic <base64encode(userid:password)>
Content-Type: application/json
X-CloudBurst-API-Version: 1.0
HTTP request body:
{
"defaultcloud": "F",
"description": "Functional Test Cloud",
"name": "FTC",
"vendor": "ESX"
}
{
"defaultcloud": "F",
"created": 1251409447905,
"vendor": "ESX",
"updated": 1251409447905,
"name": "FTC",
"id": 4,
"hypervisors": [
],
"description": "Functional Test Cloud"
}
4. Next, follow up the POST request above with a PUT request indicating
that the new hypervisor is part of this cloud group. Do this by specifying
URL: https://mycloudburst.com:443/resources/clouds/4
HTTP Method: PUT
HTTP request headers:
Accept: application/json
Accept-Language: en
Authorization: Basic <base64encode(userid:password)>
Content-Type: application/json
X-CloudBurst-API-Version: 1.0
HTTP request body:
{
"defaultcloud": "F",
"created": 1251409447905,
"vendor": "ESX",
"updated": 1251409447905,
"name": "FTC",
"id": 4,
"hypervisors": [“/resources/hypervisors/5”],
"description": "Functional Test Cloud"
}
After the above PUT request, Functional test hypervisor - 1 will belong to
the FTC cloud group.
URL: https://mycloudburst.com:443/resources/ipGroups
HTTP Method: POST
HTTP request headers:
Accept: application/json
Accept-Language: en
Authorization: Basic <base64encode(userid:password)>
Content-Type: application/json
X-CloudBurst-API-Version: 1.0
HTTP request body:
{
"gateway": "10.42.132.1",
"name": "FT IP Group",
"netmask": " 255.0.0.0",
"primarydns": " 10.16.15.253",
"secondarydns": " 10.16.15.253",
"subnetaddress": " 10.16.8.0"
}
{
"gateway": "10.42.132.1",
"networks": [
],
"secondarydns": "10.16.15.253",
"subnetaddress": "10.16.8.0",
"primarydns": "10.16.15.253",
"created": 1251410587296,
"netmask": "255.0.0.0",
"updated": 1251410587296,
"name": "FT IP Group",
"id": 2
}
6. Next, you need to add a pool of IP addresses that are associated with this
IP group. You can do this by sending a POST request containing the IP
addresses (Listing 6).
Listing 6. Add IP addresses to an IP group - Request
URL: https://mycloudburst.com:443/resources/ipGroups/2/ips
HTTP Method: POST
HTTP request headers:
Accept: application/json
Accept-Language: en
Authorization: Basic <base64encode(userid:password)>
Content-Type: application/json
X-CloudBurst-API-Version: 1.0
HTTP request body:
{
"addresses": ["10.1.2.3", "10.1.2.4"]
}
7. After the IP addresses have been added to the IP group resource, the
next step is to update the networks attribute on your IP group to point to
the relevant networks on your hypervisor. First, check the hypervisor
resource to ensure that the appropriate networks were detected after
accepting the hypervisor’s SSL certificate. You can do this by sending a
GET request for to the hypervisor resource (Listings 7a and 7b).
Listing 7a. Verify network discovery for the hypervisor - Request
URL: https://mycloudburst.com:443/resources/hypervisors/5
HTTP Method: GET
HTTP request headers:
Accept: application/json
Accept-Language: en
Authorization: Basic <base64encode(userid:password)>
Content-Type: application/json
X-CloudBurst-API-Version: 1.0
{
"desiredstatus_text": "Maintenance mode",
"currentstatus_text": "Maintenance mode",
"networks": [
"/resources/networks/5",
"/resources/networks/6"
],
"userid": "root",
"certified": "T",
"created": 1251408002475,
"name": "Functional test hypervisor - 1",
"currentstatus": "RM01025",
"desiredstatus": "RM01025",
"currentmessage": "RM03109",
"address": "https://ftchypervisor-1.com/sdk",
"cloud": "/resources/clouds/4",
"type": "ESX",
"storage": [
"/resources/storage/5",
"/resources/storage/6"
],
"updated": 1251409727403,
"id": 5,
"password": "125140800247456",
"currentmessage_text": "Maintenance mode (must set an IP group
for a network to start)"
}
Notice that the networks attribute indicates two different resource URIs. If
you need to find out more information about the network resources, a
GET request to
https://mycloudburst.com:443/resources/networks/<network_id>
would return that information. In this case, you will associate the network
resource indicated by the /resources/networks/6 URI with the IP group by
sending the PUT request shown in Listing 8.
URL: https://mycloudburst.com:443/resources/ipGroups/2
HTTP Method: PUT
HTTP request headers:
Accept: application/json
Accept-Language: en
Authorization: Basic <base64encode(userid:password)>
Content-Type: application/json
X-CloudBurst-API-Version: 1.0
HTTP request body:
{
"gateway": "10.42.132.1",
"networks": [“resources/networks/6”],
"secondarydns": "10.16.15.253",
"subnetaddress": "10.16.8.0",
"primarydns": "10.16.15.253",
"created": 1251410587296,
"netmask": "255.0.0.0",
"updated": 1251410587296,
"name": "FT IP Group",
"id": 2
}
This PUT request effectively associates the IP group with the hypervisor
containing the resources/networks/6 network resource. This means that
8. After the above PUT request, the status of Functional test hypervisor - 1
can be updated from Maintenance Mode to Started state by updating the
desiredstatus attribute on the resource (Listings 9a and 9b).
Listing 9a. Update the hypervisor state - Request
URL: https://mycloudburst.com:443/resources/hypervisors/5
HTTP Method: PUT
HTTP request headers:
Accept: application/json
Accept-Language: en
Authorization: Basic <base64encode(userid:password)>
Content-Type: application/json
X-CloudBurst-API-Version: 1.0
{
"desiredstatus_text": "Maintenance mode",
"currentstatus_text": "Maintenance mode",
"networks": [
"/resources/networks/5",
"/resources/networks/6"
],
"userid": "root",
"certified": "T",
"created": 1251408002475,
"name": "Functional test hypervisor - 1",
"currentstatus": "RM01025",
"desiredstatus": "RM01006",
"currentmessage": "RM03109",
"address": "https://ftchypervisor-1.com/sdk",
"cloud": "/resources/clouds/4",
"type": "ESX",
"storage": [
"/resources/storage/5",
"/resources/storage/6"
],
"updated": 1251409727403,
"id": 5,
"password": "125140800247456",
"currentmessage_text": "Maintenance mode (must set an IP group
for a network to start)"
}
The RM1006 code indicates the Started state, which means that the hypervisor was
started as a result of this PUT request. You can confirm this by retrieving the
resource via a GET request, or you can log into the WebSphere CloudBurst
administrative console and view the hypervisor. If you do the latter, you should see
the current status is Started state (Figure 1).
Retrieve a pattern
A pattern in the WebSphere CloudBurst Appliance is a complete representation of a
WebSphere Application Server environment. It contains parts that represent different
WebSphere Application Server nodes (such as deployment managers, custom
nodes, standalone servers, and so on), as well as script packages that enable users
to customize the middleware environment. These script packages can be used to
include any desired customization to the server’s configuration, even including the
installation of user applications into the environment. These patterns are saved on
the appliance, and can be shared and reused to produce consistent, repeatable
WebSphere Application Server deployments.
WebSphere CloudBurst provides preloaded patterns that you can use as is, or that
you can copy and customize to create new patterns more suitable to your
environment. The WebSphere Application Server cluster pattern, for example, is a
WebSphere Application Server topology for large scale development or production
environments, and consists of a deployment manager, two custom nodes, and an
IBM HTTP server. Each of these parts resides in its own virtual machine.
As with other WebSphere CloudBurst resources, you can use the REST API for
interacting with and taking actions on the patterns stored on the appliance.
Use the REST API to retrieve the cluster pattern (Listing 10a). The response in
Listing 10b represents the properties and values returned by WebSphere
CloudBurst.
URL: https://mycloudburst.com:443/resources/patterns/2
HTTP Method: GET
HTTP request headers:
Accept: application/json
Accept-Language: en
Authorization: Basic <base64encode(userid:password)>
Content-Type: application/json
X-CloudBurst-API-Version: 1.0
{
"created": 1242965377749,
"currentmessage": null,
"currentmessage_text": null,
"currentstatus": "RM01028",
"currentstatus_text": "Read-only",
"description": "Cluster is a WebSphere Application Server Network Deployment
topology for larger scale development or production environments. The IBM HTTP
Server resides in a dedicated virtual machine (in an unmanaged node).",
"id": 2,
"name": "WebSphere cluster",
"owner": "/resources/users/1",
"properties": {
"part-1.HWAttributes.numvcpus": "1",
"part-1.HWAttributes.memsize": "2048",
"part-1.ConfigWAS.cell_name": "CloudBurstCell",
"part-1.ConfigWAS.node_name": "CloudBurstNode",
"part-1.ConfigWAS.augment_list": "none",
"part-1.ConfigPWD_ROOT.password": null,
"part-1.ConfigPWD_USER.password": null,
"part-2.HWAttributes.numvcpus": "1",
"part-2.HWAttributes.memsize": "2048",
"part-2.ConfigWAS.cell_name": "CloudBurstCell",
"part-2.ConfigWAS.node_name": "CloudBurstNode",
"part-2.ConfigPWD_ROOT.password": null,
"part-2.ConfigPWD_USER.password": null,
"part-3.HWAttributes.numvcpus": "1",
"part-3.HWAttributes.memsize": "2048",
"part-3.ConfigWAS.cell_name": "CloudBurstCell",
"part-3.ConfigWAS.node_name": "CloudBurstNode",
"part-3.ConfigWAS.augment_list": "none",
"part-3.ConfigPWD_ROOT.password": null,
"part-3.ConfigPWD_USER.password": null,
"part-4.HWAttributes.numvcpus": "1",
"part-4.HWAttributes.memsize": "2048",
"part-4.ConfigWAS.cell_name": "CloudBurstCell",
"part-4.ConfigWAS.node_name": "CloudBurstNode",
"part-4.ConfigWAS.augment_list": "none",
"part-4.ConfigPWD_ROOT.password": null,
"part-4.ConfigPWD_USER.password": null,
},
"updated": 1242965394499,
"virtualsystems": [
]
}
The response in Listing 10b depicts the WebSphere Application Server cluster
topology mentioned above:
• The id, name and owner values specify the ID and display name of the
pattern, as well as the URI of the user that owns this pattern.
• The properties value specifies a map of part properties and script
parameters for this pattern. Part properties will have keys of the form
part-n.pclass.key and script parameters will have keys of the form
part-n.script-m.key. The values in the returned map will contain
default values for the properties and parameters (or null for properties and
parameters with no defaults).
• The virtualsystems value specifies the list of URIs of the virtual systems
created from this pattern. From the response, you can see that currently
there is no virtual system deployed based on this cluster pattern.
At this point, you have created a private cloud and retrieved a preloaded pattern.
The next section shows how you can use the WebSphere CloudBurst REST API to
deploy patterns into the cloud.
1. When using the REST API to deploy patterns into a private cloud, you will
first create a virtual system resource. In the POST request to create this
resource (Listing 11a) you will indicate the pattern being deployed
(pattern), the cloud that will host the virtual system (cloud), the name of
the virtual system, and other deployment information, such as password
information and WebSphere Application Server configuration data.
Listing 11a. Deploy cluster pattern to the cloud - Request
URL: https://mycloudburst.com:443/resources/virtualSystems
HTTP Method: POST
HTTP request headers:
Accept: application/json
Accept-Language: en
Authorization: Basic <base64encode(userid:password)>
Content-Type: application/json
X-CloudBurst-API-Version: 1.0
HTTP request body:
{
"cloud": "/resources/clouds/1",
"name": "Sample Virtual Systems - WebSphere cluster (1Dmgr+2nodes+1IHS)",
"pattern": "/resources/patterns/2",
"properties": {
"*.*.memsize": "1024",
"*.*.password": "password123"
}
}
{
"created": 1242965394588,
"currentmessage": null,
"currentmessage_text": null,
"currentstatus": "RM01036",
"currentstatus_text": "Queued",
"desiredstatus": "",
"desiredstatus_text": null,
"id": 14,
"name": " Sample Virtual Systems - WebSphere cluster (1Dmgr+2nodes+1IHS)",
"owner": "/resources/users/1",
"pattern": "/resources/patterns/2",
"updated": 1242965394588
}
The properties value specifies the part property and script parameter
values (if script packages have been included in the pattern) to be used
for the new virtual system. When a pattern is retrieved, it includes a map
of properties and parameters that must be specified. The map supplied
when creating a virtual system must provide values for any missing
properties and parameters, and can additionally supply values to override
the default values.
In the above example, wildcards were used for supplying property values.
The use of *.* for both the memsize and password parameters means that
those values apply to each part in the pattern. As such, each virtual
machine created during pattern deployment will be allocated 1024 MB of
virtual memory, and the password to each virtual machine will be
password123. (See the WebSphere CloudBurst Information Center for
more information on the use of wildcards when supplying property values
for virtual systems.)
After you make the POST request, log into the WebSphere CloudBurst
admin console to see your deployment (Figure 2).
You can see that four virtual machines will be created during the
deployment, one for each of the parts included in the WebSphere
Application Server cluster pattern.
2. After some period of time, a GET request for the virtual system resource
that was created in the POST request will show that all of the virtual
machines have been started, and that the WebSphere Application Server
environment is ready to use. In Listing 12a, you are issuing a GET
request for the virtual system resource with an ID of 14. That ID is used
here because it was returned in the response to the POST request issued
to create the virtual system resource (Listing 12b).
Listing 12a. Query a virtual system - Request
URL: https://mycloudburst.com:443/resources/virtualSystems/14
HTTP Method: GET
HTTP request headers:
Accept: application/json
Accept-Language: en
Authorization: Basic <base64encode(userid:password)>
X-CloudBurst-API-Version: 1.0
{
"desiredstatus_text": null,
"currentstatus_text": "Started",
"created": 1242965394588,
"name": "WebSphere Cluster",
"currentstatus": "RM01006",
"desiredstatus": "",
"currentmessage": "RM07045",
"pattern": "/resources/patterns/2",
"owner": "/resources/users/1",
"updated": 1255027495806,
"id": 2,
"currentmessage_text": "The virtual system has been deployed and is
ready to use"
}
You can further verify that the virtual system is started by viewing the
virtual system in the WebSphere CloudBurst admin console (Figure 3).
Summary
The IBM WebSphere CloudBurst Appliance provides three interfaces you can use to
manage and utilize the functions of the appliance. The HTTP REST interface
provides a language-neutral and programming model-agnostic manner with which to
interact with the appliance. This article described how you can use the REST
interface to build a private cloud, customize a WebSphere CloudBurst pattern, and
deploy that pattern to your cloud. Of course, this is just a few of the scenarios in
which the REST interface can be useful. You can explore the full interface and learn
more about how you use it to achieve maximum benefit in the WebSphere
CloudBurst REST API Reference.
Resources
Learn
• WebSphere CloudBurst Information Center
• Architectural Styles and the Design of Network-based Software Architectures,
Roy Thomas Fielding, University of California, Irvine, 2000
• WebSphere CloudBurst Appliance Rest API reference
• Videos: WebSphereCloud YouTube channel
• Managing your private cloud, Part 1: Introducing the WebSphere CloudBurst
Appliance command line interface
• Customizing with WebSphere CloudBurst (series)
• Part 1: Creating highly customized private clouds
• Part 2: Using WebSphere CloudBurst to customize a WebSphere
middleware environment
Xi Ning Wang
Xi Ning Wang is a software engineer in China in the Service-oriented Architecture
(SOA) Design Center. He is on the SOA Advanced Technologies team within the IBM
Software Group, where he develops SOA technology development. Currently, he
focuses on the areas of Web services, modeling- and policy-related technologies.