Skip to main content

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

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

All information submitted is secure.

  • Close [x]

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.

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

All information submitted is secure.

  • Close [x]

developerWorks Community:

  • Close [x]

IBM Systems Director VMControl resource lifecycle management: part 2

Remote virtual appliance lifecycle management using the VMControl REST APIs

Piyush Jain (piyushjain@in.ibm.com), Staff Software Engineer, IBM  
author photo
Piyush Jain 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 6 years and holds a bachelor's degree in Information Technology Engineering from IET Alwar, Rajasthan India. You can contact him at piyushjain@in.ibm.com
(An IBM developerWorks Contributing Author)
Nicholas Schambureck (nschambu@us.ibm.com), Advisory Software Engineer, IBM
Photo of Nick
Nick 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
Photo of Poornima
Poornima 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
Photo of Aparna
Aparna 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.

Summary:  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 appliance lifecycle using the VMControl Representational State Transfer (REST) application programming interfaces (APIs).

View more content in this series

Date:  25 Jan 2013
Level:  Intermediate PDF:  A4 and Letter (491 KB | 29 pages)Get Adobe® Reader®

Activity:  20680 views
Comments:  

Create a virtual appliance by capture

You can capture from a variety of sources to create a virtual appliance. You can then deploy the resulting virtual appliance to create a new virtual server that is complete with a fully functional operating system and software applications. You can create a virtual appliance by capturing any of the following sources:

  • Virtual server
  • Workload
  • AIX mksysb image file
  • AIX mksysb resource
  • AIX lpp_source resource
  • AIX lpp_source directory

List the repositories available to store the virtual appliance

This example shows how to create a new virtual appliance by capturing a virtual server.

The first step in creating a virtual appliance is to retrieve a list of image repositories that can be used to store the virtual appliance or an image. Select the appropriate repository from the list and save the value of its OID property. This value will be used in the subsequent requests.

  • URL
    • https://myserver:port/{webContext}/VMControl/repositories
  • HTTP method
    • GET
  • Sample request

    Get the list of all the repositories:

    GET https://myserver:port/{webContext}/VMControl/repositories



    Listing 5. Sample response representation
            
    {
        "customization": {
            "uri": "/ibm/director/rest/VMControl/repositories/customization"
        },
        "repositories": [
            {
                "properties": {},
                "oid": 17621,
                "name": "Image_repo",
                "uri": "/ibm/director/rest/VMControl/repositories/17621"
            },
            {
                "properties": {},
                "oid": 27567,
                "name": "createRepos",
                "uri": "/ibm/director/rest/VMControl/repositories/27567"
            }
        ],
        "uri": "/ibm/director/rest/VMControl/repositories"
    }
    

List the candidates available for the creation of a virtual appliance by capture

After selecting a repository, the next step is to choose a virtual server to capture. The following request will return the valid virtual servers and workloads available to be captured. Select the appropriate candidate from the list and save the value of its OID property. This value will be used in the next request.

  • URL
    • https://myserver:port/{webContext}/VMControl/virtualAppliances/candidates
  • HTTP method
    • GET
  • Sample request

    Get the list of all candidates:

    GET https://myserver:port/{webContext}/VMControl/virtualAppliances/candidates



    Listing 6. Sample response representation
            
    {
        "candidates": [
            {
                "customization": {
                    "uri": "/ibm/director/rest/VMControl/virtualAppliances/candidates
    							/13025/customization"
                },
                "type": "virtualServer",
                "oid": 13025,
                "name": "IP10-32-41-53_SLES11SP1_10g_mul",
                "uri": "/ibm/director/rest/VMControl/virtualAppliances/candidates/13025",
                "system": {
                    "uri": "/ibm/director/rest/VMControl/virtualServers/13025"
                }
            },
            {
                "customization": {
                    "uri": "/ibm/director/rest/VMControl/virtualAppliances/candidates
    							/13030/customization"
                },
                "type": "virtualServer",
                "oid": 13030,
                "name": "IP10-32-41-10_AIX71D_10G_multi",
                "uri": "/ibm/director/rest/VMControl/virtualAppliances/candidates/13030",
                "system": {
                    "uri": "/ibm/director/rest/VMControl/virtualServers/13030"
                }
            },
            {
                "customization": {
                    "uri": "/ibm/director/rest/VMControl/virtualAppliances/candidates
    							/13031/customization"
                },
                "type": "virtualServer",
                "oid": 13031,
                "name": "IP10-32-41-27_RHEL61_10G_multi",
                "uri": "/ibm/director/rest/VMControl/virtualAppliances/candidates/13031",
                "system": {
                    "uri": "/ibm/director/rest/VMControl/virtualServers/13031"
                }
            },
            {
                "customization": {
                    "uri": "/ibm/director/rest/VMControl/virtualAppliances/candidates
    							/27501/customization"
                },
                "type": "virtualServer",
                "oid": 27501,
                "name": "ip-10-32-42-106",
                "uri": "/ibm/director/rest/VMControl/virtualAppliances/candidates/27501",
                "system": {
                    "uri": "/ibm/director/rest/VMControl/virtualServers/27501"
                }
            },
            {
                "customization": {
                    "uri": "/ibm/director/rest/VMControl/virtualAppliances/candidates
    							/23791/customization"
                },
                "type": "virtualServer",
                "oid": 23791,
                "name": "ip-10-32-42-101",
                "uri": "/ibm/director/rest/VMControl/virtualAppliances/candidates/23791",
                "system": {
                    "uri": "/ibm/director/rest/VMControl/virtualServers/23791"
                }
            }
        ],
        "uri": "/ibm/director/rest/VMControl/virtualAppliances/candidates"
    }
    


List the customization of creating a virtual appliance

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 capturable OID from the previous step, create a GET request to the URL specified below. The result will be a list of customization properties related to capturing the specified candidate virtual server in to the specified repository.

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

Typical customization parameters used for capture include disk capturing options, network descriptions, operating system type, and virtual appliance versioning information. Our example specifies all of these, except the virtual appliance versioning information. For more information on virtual appliance versioning, refer to the virtualAppliances resource page of the IBM Systems Director 6.3.x SDK information center.

  • URL
    • https://myserver:port/{webContext}/VMControl/virtualAppliances/{candidateOID}/customization
  • HTTP method
    • GET
  • Sample request

    Get the customization properties available for the candidate with OID 27501 when creating a new virtual appliance on repository with OID 27567 :

    GET GET https://myserver:port/{webContext}/VMControl/virtualAppliances/candidates/27501/customization?repository=27567



    Listing 7. Sample response representation
    View Listing 7

Create a virtual appliance

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

The following request creates a new virtual appliance, named VirtualAppliance1 by capturing the virtual server with unique OID 27501 into repository with unique OID, 27567. The virtual server's disk and associated data on that disk are included in the capture. The expected operating system is Linux (36).

The response message body and location header will contain a URL pointing to the virtual appliance as it is being created. The next step is to monitor the asynchonous task to completion.

  • URL
    • https://myserver:port/{webContext}/VMControl/virtualAppliances
  • HTTP method
    • PUT
  • Sample request

    Create a new virtual appliance in the repository with a unique OID of 27567 by capturing virtual server with a unique OID of 27501:

    PUT https://myserver:port/{webContext}/VMControl/virtualAppliances



    Listing 8. Sample request representation
            
    {
        "virtualAppliance" : 
        {
            "capturable" : "27501",
            "name" : "VirtualAppliance1",
            "description" : "My Virtual Appliance",
            "repository" : 27567,
            "properties" : [
                {
                    "name": "capturedisks", 
                    "value": "[1]=capturedisk:true;image:true"
                },
                {
                    "name": "ostypecapture",
                    "value": "[12145]=osType:36"
                }
            ]
        }
    }
    



    Listing 9. HTTP response:
            
    Status Code: 201 OK
    Cache-Control: no-store
    Content-Type: application/json; charset=UTF-8
    Content-Length: 300
    Date: Wed, 11 Jul 2012 11:41:38 GMT
    Location: https://9.9.9.9:8422/ibm/director/rest/VMControl/virtualAppliances/28906
    Accept-Ranges: bytes
    Server: Noelios-Restlet-Engine/1.1.4
    Content-Language: en-US
    
    {
        "MessageID": "DNZEMW349I",
        "MessageText": "DNZEMW349I Virtual Appliance \"28906\" is being captured: 
    	Capture/Import 'Virtual Appliance 1': My Virtual Appliance will capture/
    	import system '27501' into repository '27567' with customization 
    	[[ capturedisks[1], capturedisk:true;image:true ]] "
    }
    


Monitor the create virtual appliance job

The final step in creating a virtual appliance is to monitor its progress to completion. The capture operation can be monitored by polling the progress resource or monitoring events created as part of capture.

You can find the progress resource at virtualAppliances/{virtualApplianceOID}/progress. It is available during the capture process to monitor progress. It is also available after the capture is complete and if the capture fails. If the capture is successful, then the progress resource is deleted.

Alternatively, there is an event created against the virtual server object being captured that signals the capture completion and specifies whether it was successful or not. This event can be retrieved using one of the following two methods:

  1. /ibm/director/rest/resources/Server/{serverOID}/events
  2. /ibm/director/rest/events?ComponentType=Server&ComponentCategory=ManagedElement.ManagedSystemElement.LogicalElement.System.ComputerSystem
  • URL
    • https://myserver:port/ibm/director/rest/resources/Server/{vsoid}/events
  • HTTP method
    • GET
  • Sample request

    Listing all the successful and unsuccessful capture events for a server with a unique ID of 55047:

    GET https://myserver:port/ibm/director/rest/resources/Server/24920/events



    Listing 10. Sample request representation
            
    {"events": [
      {
        "EventID": 10260,
        "ComponentCategory": "ManagedElement.ManagedSystemElement.LogicalElement.
    						System.ComputerSystem",
        "Severity": "Critical",
        "Mode": "ALERT",
        "EventText": "A Capture has failed for Virtual Server bt_nfsr1.\ncom.ibm.
    	director.im.common.exceptions.CaptureException: DNZVMK243E Unable to 
    	capture the virtual server to repository image_repos. The repository 
    	controller IBM 7870AC1 06N6242 does not have access to source disk 
    	location 9.12.29.159:/nfs/kvm/images/bt_nfsr2.dsk.",
        "uri": "/ibm/director/rest/events/10260",
        "ComponentInstance": null,
        "ComponentType": "Server"
      },
      {
        "EventID": 8273,
        "ComponentCategory": "ManagedElement.ManagedSystemElement.LogicalElement.
    						System.ComputerSystem",
        "Severity": "Harmless",
        "Mode": "RESOLUTION",
        "EventText": "A capture has been successful creating VirtualAppliance bt_sanr2.",
        "uri": "/ibm/director/rest/events/8273",
        "ComponentInstance": null,
        "ComponentType": "Server"
      }
    ]}
    

  • URL
    • https://myserver:port/ibm/director/rest/events?ComponentType=Server&ComponentCategory=ManagedElement.ManagedSystemElement.LogicalElement.System.ComputerSystem
  • HTTP method
    • GET
  • Sample request

    Listing all the successful and unsuccessful capture events for all the servers where component type is Server and category is ManagedElement.ManagedSystemElement.LogicalElement.System.ComputerSystem:

    GET https://myserver:port/ibm/director/rest/events?ComponentType=Server&ComponentCategory=ManagedElement.ManagedSystemElement.LogicalElement.System.ComputerSystem



    Listing 11. Sample request representation
            
    {"events": [
      {
        "EventID": 10260,
        "ComponentCategory": "ManagedElement.ManagedSystemElement.LogicalElement.
    							System.ComputerSystem",
        "Severity": "Critical",
        "Mode": "ALERT",
        "EventText": "A Capture has failed for Virtual Server bt_nfsr1.\ncom.ibm.
    	director.im.common.exceptions.CaptureException: DNZVMK243E Unable to capture
    	 the virtual server to repository image_repos. The repository controller 
    	IBM 7870AC1 06N6242 does not have access to source disk location 9.22.22.22:
    	/nfs/kvm/images/bt_nfsr2.dsk.",
        "uri": "/ibm/director/rest/events/10260",
        "ComponentInstance": null,
        "ComponentType": "Server"
      },
      {
        "EventID": 8273,
        "ComponentCategory": "ManagedElement.ManagedSystemElement.LogicalElement.
    							System.ComputerSystem",
        "Severity": "Harmless",
        "Mode": "RESOLUTION",
        "EventText": "A capture has been successful creating VirtualAppliance bt_sanr2.",
        "uri": "/ibm/director/rest/events/8273",
        "ComponentInstance": null,
        "ComponentType": "Server"
      },
      {
        "EventID": 1684,
        "ComponentCategory": "ManagedElement.ManagedSystemElement.LogicalElement.
    							System.ComputerSystem",
        "Severity": "Harmless",
        "Mode": "RESOLUTION",
        "EventText": "A capture has been successful creating VirtualAppliance 
    			vs-18-05-2nd.",
        "uri": "/ibm/director/rest/events/1684",
        "ComponentInstance": null,
        "ComponentType": "Server"
      },
      {
        "EventID": 1629,
        "ComponentCategory": "ManagedElement.ManagedSystemElement.LogicalElement.
    							System.ComputerSystem",
        "Severity": "Critical",
        "Mode": "ALERT",
        "EventText": "A Capture has failed for Virtual Server VS_check-18-05.\ncom.ibm.
    	director.im.common.exceptions.CaptureException: DNZVMK209E Unable to store the
    	 virtual appliance in the repository.",
        "uri": "/ibm/director/rest/events/1629",
        "ComponentInstance": null,
        "ComponentType": "Server"
      }
    ]}

These URL can be polled, but the recommended method is to use the JMS provider to subscribe to the event.

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.

3 of 8 | Previous | Next

Comments



static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=AIX and UNIX, Linux
ArticleID=855964
TutorialTitle=IBM Systems Director VMControl resource lifecycle management: part 2
publish-date=01252013
author1-email=piyushjain@in.ibm.com
author1-email-cc=nissler@us.ibm.com
author2-email=nschambu@us.ibm.com
author2-email-cc=
author3-email=poornima.s@in.ibm.com
author3-email-cc=nissler@us.ibm.com
author4-email=apakhare@in.ibm.com
author4-email-cc=nissler@us.ibm.com