IBM Systems Director VMControl resource lifecycle management: part 1

Remote virtual server lifecycle management using the VMControl REST APIs

IBM® Systems Director is a platform management solution that is used to manage physical and virtual systems in a multisystem environment. It supports various virtualization technologies and multiple operating systems across IBM and non-IBM platforms. IBM Systems Director VMControl™ is an advanced manager of IBM Systems Director, a free-to-own set of platform management tools. This tutorial is part of a series on VMControl resource lifecycle management. This tutorial explains the virtual server lifecycle using the VMControl Representational State Transfer (REST) application programming interfaces (APIs).

Share:

Piyush Jain (piyushjain@in.ibm.com), Staff Software Engineer, IBM  

Piyush Jain Piyush Jain (An IBM developerWorks Contributing Author) is a Staff Software Engineer at IBM currently working on VMControl under IBM Systems Director, a critical product in IBM's product portfolio. He has an overall experience of around 7 years and holds a bachelor's degree in Information Technology Engineering from IET Alwar, Rajasthan India.


developerWorks Contributing author
        level

Nicholas Schambureck (nschambu@us.ibm.com), Advisory Software Engineer, IBM China

Photo of NickNick Schambureck is an Advisory Software Engineer and Team Leader for the IBM Systems Director VMControl command-line interface and REST API team. He has been working with the project since its inception.



Poornima Soundararajan (poornima.s@in.ibm.com), Staff Software Engineer, IBM China

Photo of PoornimaPoornima Soundararajan is working as a Staff Software Engineer for the IBM Systems Director VMControl advanced manager. Poornima has more than 7 years of experience in Java/J2EE technologies.



Aparna Khare (apakhare@in.ibm.com), System Software Engineer, IBM China

Photo of AparnaAparna Khare is working as a System Software Engineer for the IBM Systems Director VMControl advanced manager. Aparna has 4 years of experience in Java/J2EE technologies.



17 January 2013

Also available in Chinese

Before you start

Learn what to expect from this tutorial, and how to get the most out of it.

About this series

The IBM Systems Director VMControl advanced manager simplifies the management of virtual environments across multiple virtualization technologies and hardware platforms. VMControl is a leading multi-platform virtualization management solution that is included with IBM Systems Director Editions. VMControl has the support for three types of interfaces (GUI, CLI, and REST APIs). This series talks about the VMControl resources lifecycle through REST.

This series has the following lifecycles:

  • Virtual server lifecycle management through the VMControl REST APIs: This covers the lifecycle (create, view, edit, and delete) management of a virtual server. It highlights the capabilities of VMControl Express Edition, the free portion of VMControl.
  • Virtual appliance lifecycle management through the VMControl REST APIs: This covers the lifecycle management of a virtual appliance. A virtual appliance is an operating system image and metadata that is capable of being remotely installed (deployed) on a new or existing virtual server.
  • Image deployment through the VMControl REST APIs: This walks through a typical deploy process and the workload lifecycle management of the workload created using this deploy process.
  • Server system pool lifecycle management through the VMControl REST APIs: This covers the lifecycle management of a server system pool and its virtual server relocation capabilities. A server system pool is a grouping of similar physical servers (hosts) – VMControl version of a cloud. VMControl chooses which host to deploy to and allows for relocation of virtual servers within the server system pool.

This series will help all the VMControl users to understand the VMControl functionalities through REST. It will also help to understand the detailed flow of the resource lifecycle.

About this tutorial

This tutorial illustrates the life cycle of a virtual server using the VMControl REST APIs. The lifecycle of a virtual server has the following major functions:

  • Creating a virtual server
  • Modifying a virtual server (modify properties and power management)
  • Deleting a virtual server

In Figure 1, virtual server lifecycle is explained in detail with the sequence of different REST requests.

Figure 1. Virtual server lifecycle
Virtual Server Lifecycle

Objectives

The main objective of this tutorial is to help users understand the virtual server resource lifecycle using the VMControl REST APIs. The tutorial describes the complete lifecycle with the purview of using it with IBM System Director VMControl. Users with the basic knowledge about virtual servers and IBM Systems Director VMControl can walk through the tutorial easily.

Prerequisites

You should have IBM Systems Director V6.x.x installed on your system before proceeding. This tutorial assumes that you are familiar with using IBM Systems Director. It also assumes that you have a reasonable understanding of JavaScript Object Notation (JSON) and how to make HTTP GET, POST, PUT, and DELETE calls using your favorite HTTP client.

System requirements

You should have the following components on your system.

  • An installed and configured copy of IBM Systems Director
  • IBM Systems Director VMControl advanced manager activated
  • HTTP Client to run remote requests

Creating a virtual server

Listing available hosts for creating a virtual server

The first step in creating a virtual server is to retrieve a list of hosts that can be used in the creation of a virtual server. A host is a physical server capable of supporting virtual computers. It is likely managed by a hypervisor. Select the appropriate host from the list and save the value of its object identifier (OID) property. This value will be used in the next request.

Note: The URLs in these examples all start with https://myserver:port. You should replace myserver with the hostname or IP address of the system where VMControl resides and replace the port number with the secure port used when installing IBM Systems Director. The default value for the secure port is 8422.

  • URL
    • https://myserver:port/ibm/director/rest/VMControl/hosts
  • HTTP method
    • GET
  • Sample request

    Get the list of all hosts:

    GET https://myserver:port/ibm/director/rest/VMControl/hosts

    Listing 1. Sample response representation
    {
        "hosts": [
            {
                "name": "Server-7998-61X-SN0689CEA",
                "customization": {
                    "uri": "/ibm/director/rest/VMControl/hosts/6649/customization"
                },
                "properties": {},
                "uri": "/ibm/director/rest/VMControl/hosts/6649",
                "oid": 6649,
                "virtualServers": {
                    "uri": "/ibm/director/rest/VMControl/hosts/6649/virtualServers"
                }
            },
            {
                "name": "Server-7998-61X-SN0689D0A",
                "customization": {
                    "uri": "/ibm/director/rest/VMControl/hosts/6838/customization"
                },
                "properties": {},
                "uri": "/ibm/director/rest/VMControl/hosts/6838",
                "oid": 6838,
                "virtualServers": {
                    "uri": "/ibm/director/rest/VMControl/hosts/6838/virtualServers"
                }
            }
        ],
        "uri": "/ibm/director/rest/VMControl/hosts"
    }

Lising the customization for creating a virtual server

Customization parameters are unique, platform-specific properties that allow a user to customize the action that the user is performing. Customization parameters are available in many different types, but are all specified in a similar fashion. Using the OID collected from the previous step, make a GET request to the URL specified below. The result will be a list of customization parameters that can be used to create a virtual server.

The following example shows customization parameters in a typical Power environment. Customization parameters for other platforms (KVM, IBM z/VM®, and so on) will be different.

Note: For more information about customization parameters, refer to the VMControl programming topics section of the IBM Systems Director 6.3.x SDK Information Center.

  • URL
    • https://myserver:port/ibm/director/rest/VMControl/hosts/{hostOID}/virtualServers/customization
  • HTTP method
    • GET
  • Sample request

    Get the virtualization properties available when creating a new virtual server on host unique ID 6649:

    GET https://myserver:port/ibm/director/rest/VMControl/hosts/6649/virtualServers/customization

    Sample response representation

    View Listing 2

Creating a virtual server

The next step is to make an HTTP request to create a new virtual server. The first step is to populate the JSON for your request. Using the above listed customization, create a JSON string containing name/value pairs of customization properties for the virtual server.

Using this JSON string, create an HTTP POST request to the URL below. Creating a virtual server is an asynchronous operation, meaning that you will receive a response stating that the operation has begun and will need to monitor it to completion. The response will contain two URLs. The URL in the location header points to the temporary holding place for the virtual server. As the virtual server is not yet created, the name chosen in the request is used as a placeholder for ID. The URL in the message points to the job activation record for the create virtual server task. The job activation record contains the status of the create virtual server request, including percentage complete and any status or error messages.

  • URL
    • https://myserver:port/ibm/director/rest/VMControl/hosts/{hostOID}/virtualServers
  • HTTP method
    • POST
  • Sample request

    Create a new virtual server on host with unique ID of 6649:

    POST https://myserver:port/ibm/director/rest/VMControl/hosts/6649/virtualServers

    Listing 2. Sample response representation
    {
        "virtualServer":{
            "properties":[{
                    "name":"name",
                    "value":"NEW_VS1"
                },
                {
                    "name":"gos",
                    "value":"IBM Power - AIXLINUX"
                },
                {
                    "name":"cpumode",
                    "value":"SHARED"
                },
                {
                    "name":"cpushared",
                    "value":1
                },
                {
                    "name":"memsize",
                    "value":128
                },
                {
                    "name":"networks",
                    "value":"Discovered-1014-0"
                }
            ]
        }
    }
    Listing 3. HTTP response:
    HTTP/1.1 201 OK
    Cache-Control: no-store
    Set-Cookie: JSESSIONID_ibm_console_80=00007ID-HpF24AAYtRxUDiikVk4;Path=/; Secure; 
    									HTTPOnly
    Expires: Thu, 01 Dec 1994 16:00:00 GMT
    Content-Type: application/octet-stream; charset=UTF-8
    Content-Length: 190
    Date: Mon, 14 May 2012 02:34:13 GMT
    Location: https://9.9.9.9:8422/ibm/director/rest/VMControl/hosts/6649
    							/virtualServers/NEW_VS1
    Accept-Ranges: bytes
    Server: Noelios-Restlet-Engine/1.1.4
    Content-Language: en-US
    
    {
      "MessageText": "DNZEMW066I New "Create Virtual Server" job [1] started.\nRefer 
    	to the following URI for status: /ibm/director/rest/jobs/153/activations/1 ",
      "MessageID": "DNZEMW066I"
    }
    }

Monitoring the create virtual server job

The final step in creating a virtual server is to monitor its progress to completion. The recommended method to monitor virtual server creation is through the job activation record. As shown above, this URL is returned in the message text in the response from the POST request. The job activation record can be monitored by polling the URL, but the recommended method is to use the Java Message Service (JMS) provider.

IBM Systems Director server includes a JMS provider to communicate events and other important messages with interested client applications. It allows for asynchronous communication between two or more applications. Job activation records can be monitored asynchronously through the Director.jobs.activation JMS topic.

For more information on JMS, refer to the JMS Messaging Overview page of the IBM Systems Director 6.3.x SDK information center.


Modifying a virtual server

Listing the available virtual servers to modify

The first step in modifying a virtual server is to retrieve a list of existing virtual servers. This can be done by either retrieving all known virtual servers or by retrieving a list of virtual servers that exist on a host. This example retrieves all virtual servers.

Note: The URL for the virtual servers include the host. Any action performed on virtual servers, including create, edit, and delete, are done using these URLs. The virtualServers resource is a helper URL to list all virtual servers and should only be used as such.

  • URL
    • https://myserver:port/ibm/director/rest/VMControl/virtualServers
  • HTTP method
    • GET
  • Sample request

    Get the list of all virtual servers:

    GET https://myserver:port/ibm/director/rest/VMControl/virtualServers

    Listing 4. Sample response representation
    {
       "uri":"/ibm/director/rest/VMControl/virtualServers"
       "virtualServers":[
          {
             "uri":"/ibm/director/rest/VMControl/hosts/6797/virtualServers/6798",
             "name":"myVirtualServer1",
             "oid":6798
             "customization":{
                "uri":"/ibm/director/rest/VMControl/hosts/6797/virtualServers/6798/
    								customization"
             },
             "state":{
                "label":"Started",
                "id":8
             },
          },
          {
             "uri":"/ibm/director/rest/VMControl/hosts/6797/virtualServers/7648",
             "name":"myVirtualServer2",
             "oid":7468
             "customization":{
                "uri":"/ibm/director/rest/VMControl/hosts/6797/virtualServers/7648/
    								customization"
             },
             "state":{
                "label":"Started",
                "id":8
             },
          },
          {
             "uri":"/ibm/director/rest/VMControl/hosts/6797/virtualServers/8200",
             "name":"myVirtualServer3",
             "oid":8200
             "customization":{
                "uri":"/ibm/director/rest/VMControl/hosts/6797/virtualServers/8200/
    								customization"
             },
             "state":{
                "label":"Started",
                "id":8
             },
          }
    }

Listing the customization for modifying a virtual server

Customization parameters are unique, platform-specific properties that allow a user to customize the action that the user is performing. Customization parameters are available in many different types, but are all specified in a similar fashion. Using the OIDs from the previous step, create a GET request to the URL specified below. The result will be a list of customization properties that can be used to modify a virtual server.

The following example shows customization parameters in a typical IBM Power Systems™ environment. Customization parameters for other platforms (kernel-based virtual machine [KVM], z/VM, and so on) will be different. Additionally, there are different rules for retrieving customization on different platforms. For example, KVM requires the virtual server to be stopped in order to modify it. Power Systems server allow you to modify an active virtual server, but only a subset of the properties will be available if the virtual server is stopped.

  • URL
    • https://myserver:port/ibm/director/rest/VMControl/hosts/{hostOID}/virtualServers/{vsOID}/customization
  • HTTP method
    • GET
  • Sample request

    Get the virtualization properties for modifying virtual server 6798:

    GET https://myserver:port/ibm/director/rest/VMControl/hosts/6797/virtualServers/6798/customization

    Sample response representation

    View Listing 6

Modifying a virtual server

The next step is to request a virtual server to be modified. Modifying a virtual server is an asynchronous operation. The first step is to populate the JSON for your request. Using the above listed customization, create a JSON string containing name/value pairs of customization properties for the virtual server.

The response contains two copies of the same URL. Both the URL in the location header and the URL in the response message point to the job activation record for the modify virtual server task. The job activation record contains the status of the modify virtual server request, including percentage complete and any status or error messages.

  • URL
    • https://myserver:port/ibm/director/rest/VMControl/hosts/{hostOID}/virtualServers/{vsOID}
  • HTTP method
    • PUT
  • Sample request

    Modify the virtual server with unique ID of 6798:

    PUT https://myserver:port/ibm/director/rest/VMControl/hosts/6649/virtualServers/6798

    Listing 5. Sample response representation
    {
        "virtualServer":{
            "properties":[{
                    "name":"cpu",
                    "value":2
                }
            ]
        }
    }
    Listing 6. HTTP response
    HTTP/1.1 202 OK
    Cache-Control: no-store
    Set-Cookie: JSESSIONID_ibm_console_80=0000z7DH1a8JDMo-ymu3KP38hoM;Path=/; Secure; 
    								HTTPOnly
    Expires: Thu, 01 Dec 1994 16:00:00 GMT
    Content-Type: application/octet-stream; charset=UTF-8
    Content-Length: 200
    Date: Mon, 14 May 2012 03:00:27 GMT
    Location: https://9.9.9.9:8422/ibm/director/rest/jobs/154/activations/1
    Accept-Ranges: bytes
    Server: Noelios-Restlet-Engine/1.1.4
    Content-Language: en-US
    
    {
      "MessageText": "New job activation for updating the virtual server was started.\n
    	Refer to the following URI for job activation status: 
    	/ibm/director/rest/jobs/154/activations/1",
      "MessageID": ""
    }

Monitoring the modify virtual server job

The final step in modifying a virtual server is to monitor its progress to completion. The recommended method to monitor the modify virtual server job is through the job activation record. As shown above, this URL is returned in the response from the PUT request. The job activation record can be monitored by polling the URL, but the recommended method is to use the JMS provider.

IBM Systems Director server includes a JMS provider to communicate events and other important messages with interested client applications. It allows for asynchronous communication between two or more applications. Job activation records can be monitored asynchronously through the Director.jobs.activation JMS topic.

For more information on JMS, refer to the JMS Messaging Overview page of the IBM Systems Director 6.3.x SDK information center.


Deleting a virtual server

Listing the virtual servers available to delete

The first step in deleting a virtual server is to retrieve a list of available virtual servers. This can be done by either retrieving all known virtual servers or by retrieving a list of virtual servers that exist on a host. This example retrieves all virtual servers.

Note: The URL for the virtual servers include the host. Any action performed on virtual servers, including create, edit, and delete, are done using these URLs. The virtualServers resource is a helper URL to list all virtual servers and should only be used as such.

  • URL
    • https://myserver:port/ibm/director/rest/VMControl/virtualServers
  • HTTP method
    • GET
  • Sample request

    Get the list of all virtual servers:

    GET https://myserver:port/ibm/director/rest/VMControl/virtualServers

    Listing 7. Sample response representation
    {
       "uri":"/ibm/director/rest/VMControl/virtualServers"
       "virtualServers":[
          {
             "uri":"/ibm/director/rest/VMControl/hosts/6797/virtualServers/6798",
             "name":"myVirtualServer1",
             "oid":6798
             "customization":{
                "uri":"/ibm/director/rest/VMControl/hosts/6797/virtualServers/6798/
    								customization"
             },
             "state":{
                "label":"Started",
                "id":8
             },
          },
          {
             "uri":"/ibm/director/rest/VMControl/hosts/6797/virtualServers/7648",
             "name":"myVirtualServer2",
             "oid":7468
             "customization":{
                "uri":"/ibm/director/rest/VMControl/hosts/6797/virtualServers/7648/
    								customization"
             },
             "state":{
                "label":"Started",
                "id":8
             },
          },
          {
             "uri":"/ibm/director/rest/VMControl/hosts/6797/virtualServers/8200",
             "name":"myVirtualServer3",
             "oid":8200
             "customization":{
                "uri":"/ibm/director/rest/VMControl/hosts/6797/virtualServers/8200/
    								customization"
             },
             "state":{
                "label":"Started",
                "id":8
             },
          }
    }

Deleting a virtual server

The next step is to request for the virtual server to be deleted. Deleting a virtual server is an asynchronous operation.

The location HTTP header in the response contains the URL of the job activation record for the delete virtual server task. The job activation record contains the status of the delete virtual server request, including percentage complete and any status or error messages.

  • URL
    • https://myserver:port/ibm/director/rest/VMControl/hosts/{hostOID}/virtualServers/{vsOID}
  • HTTP method
    • DELETE
  • Sample request

    Delete the virtual server with unique ID of 6798:

    DELETE https://myserver:port/ibm/director/rest/VMControl/hosts/6649/virtualServers/6798

    Listing 8. Sample response representation
    HTTP/1.1 202 OK
    Cache-Control: no-store
    Set-Cookie: JSESSIONID_ibm_console_80=0000ZdJty7E5NW6uYO97y-KlOrI;Path=/; Secure; 
    								HTTPOnly
    Expires: Thu, 01 Dec 1994 16:00:00 GMT
    Content-Type: application/octet-stream; charset=UTF-8
    Content-Length: 193
    Date: Mon, 14 May 2012 08:57:47 GMT
    Location: https://9.9.9.9:8422/ibm/director/rest/jobs/1964/activations/1
    Accept-Ranges: bytes
    Server: Noelios-Restlet-Engine/1.1.4
    Content-Language: en-US
    
    {
      "MessageText": "DNZEMW051I New \"Delete Virtual Server\" job [1] started.\nRefer 
    	to the following URI for status: /ibm/director/rest/jobs/1964/activations/1 ",
      "MessageID": "DNZEMW051I"
    }

Monitoring the delete a virtual server job

The final step in deleting a virtual server is to monitor its progress to completion. The recommended method to monitor a virtual server deletion is through the job activation record. As shown above, this URL is returned in response from the DELETE request. The job activation record can be monitored by polling the URL, but the recommended method is to use the JMS provider.

IBM Systems Director server includes a JMS provider to communicate events and other important messages with interested client applications. It allows for asynchronous communication between two or more applications. Job activation records can be monitored asynchronously through the Director.jobs.activation JMS topic.

For more information on JMS, refer to the JMS Messaging Overview page of the IBM Systems Director 6.3.x SDK information center.

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 AIX and Unix on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=AIX and UNIX, Linux
ArticleID=855006
ArticleTitle=IBM Systems Director VMControl resource lifecycle management: part 1
publish-date=01172013