IBM Systems Director VMControl resource lifecycle management: part 2

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

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.



25 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 functionality 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 virtual appliance using the VMControl REST APIs. The lifecycle of a virtual appliance has the following major functions:

  • Create an image repository to store virtual appliances
  • Create a virtual appliance by capture
  • Create a virtual appliance by import
  • Modify a virtual appliance
  • Delete a virtual appliance

Figure 1 explains the virtual appliance lifecycle in detail with the sequence of different REST requests.

Figure 1. Virtual appliance lifecycle management
Virtual Appliance Lifecycle Management

Objectives

The main objective of this tutorial is to help users understand the virtual appliance lifecycle management 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 appliance 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

Create an image repository

The first step in managing virtual appliances and workloads in an IBM Systems Director VMControl environment is creating an image repository.

  • Kernel-based virtual machine (KVM) allows the creation of image repositories based on Network File System (NFS)-based storage or storage area network (SAN) storage.
  • On IBM AIX®, the two options are Network Installation Management (NIM) image repositories and Virtual I/O Server (VIOS) image repositories. One or a combination of both types can be set up in an AIX environment, but only the VIOS image repositories can be created through VMControl.
  • IBM i or IBM Power Systems running Linux® uses one or more VIOS image repositories.
  • NIM repositories and IBM z/VM® repositories are created outside of IBM Systems Director VMControl and included through the discovery process.

Additional set up may be required before attempting to create an image repository. Follow the setup instructions in the IBM Systems Director information center before attempting to create a repository through the VMControl REST APIs.

List known operating systems

This example creates a VIOS image repository on an IBM Power Systems™ server.

The first step is to retrieve a list of VIOS operating systems that can be used in the creation of an image repository. Select the appropriate operating system from the list and save the value of its object ID (OID) property. This value will be used in the next request.

VIOS image repositories require the IBM Systems Director Common Agent to be installed on VIOS. This means that of the operating systems in the following list, only v525400 is a valid operating system for creating an image repository.

  • URL
    • https://myserver:port/{webContext}/resources/OperatingSystem?Props=ManagementSoftware
  • HTTP method
    • GET
  • Sample request

    Get the list of all operating system resources:

    GET https://myserver:port/{webContext}/resources/OperatingSystem?Props=ManagementSoftware

    Listing 1. Sample response representation
    {
    
        "resources": [
            {
                "uri": "/ibm/director/rest/resources/OperatingSystem/3009",
                "OID": 14311,
                "ObjectType": "OperatingSystem",
                "Name": "v525400",
                "ResourceDefinition": "/ibm/director/rest/resourcedefinitions/Operating
    		System/com.ibm.usmi.systems.endpoint.SystemsManageableEndpointFactory",
                "Properties": {
                    "ManagementSoftware": [
                        "IBM-IBM Director Agent-v6.3.2",
                        "IBM-IBM Director Platform Agent-v6.3.2"
                    ]
                },
                "RelatedServices": "/ibm/director/rest/resources/OperatingSystem/3009/
    								relatedservices"
            },
            {
                "uri": "/ibm/director/rest/resources/OperatingSystem/13386",
                "OID": 13386,
                "ObjectType": "OperatingSystem",
                "Name": "rhel60pae201",
                "ResourceDefinition": "/ibm/director/rest/resourcedefinitions/Operating
    		System/com.ibm.usmi.systems.endpoint.SystemsManageableEndpointFactory",
                "Properties": {
                    "ManagementSoftware": [
                        "IBM-IBM Director Platform Agent-v6.3"
                    ]
                },
                "RelatedServices": "/ibm/director/rest/resources/OperatingSystem/13386/
    								relatedservices"
            },
            {
                "uri": "/ibm/director/rest/resources/OperatingSystem/18072",
                "OID": 18072,
                "ObjectType": "OperatingSystem",
                "Name": "rhel60e201c",
                "ResourceDefinition": "/ibm/director/rest/resourcedefinitions/Operating
    		System/com.ibm.usmi.systems.endpoint.SystemsManageableEndpointFactory",
                "Properties": {
                    "ManagementSoftware": [
                        "IBM-IBM Director Platform Agent-v6.3.1"
                    ]
                },
                "RelatedServices": "/ibm/director/rest/resources/OperatingSystem/18072/
    								relatedservices"
            }
        ]
    
    }

List customization for creating a repository

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 operating system OID 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 create a repository.

The following example shows the customization parameters for creating a repository in a typical Power Systems environment. Customization parameters for other platforms (KVM, 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/{webContext}/VMControl/repositories/customization?operatingSystem=14311
  • HTTP method
    • GET
  • Sample request

    Get the customization parameters available when creating a new repository using the operating system with a unique OID of 14311:

    GET https://myserver:port/{webContext}/VMControl/repositories/customization?operatingSystem=14311

    Sample response representation

    View Listing 2

Create a repository

The next step is to request an image repository to be created. Create repository is an asynchronous operation. The first step is to populate the JSON for your request. Using the above listed customization, create a JSON string with the name/value pair for the customization property named, repositorystorage in order to select the storage where the repository will be created.

The response will contain two URLs. The URL in the location header points to the temporary holding place for the repository. As the repository 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 repository task. The job activation record will contain the status of the create repository request, including percentage complete and any status or error messages.

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

    Create a new image repository using the operating system with a unique ID of 14311:

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

    Listing 2. Sample request representation
    {
        "repository":{
            "name":"createRepos",
            "description":"Newly Created Repository",
            "operatingSystem":"14311",
            "properties":[{
                    "name":"repositorystorage",
                    "value":"1"
                }
            ]
        }
    }
    Listing 3. HTTP response:
    Status Code: 201 OK
    Accept-Ranges: bytes
    Cache-Control: no-store
    Content-Language: en-US
    Content-Length: 168
    Content-Type: application/json; charset=UTF-8
    Date:  Wed, 11 Jul 2012 08:23:35 GMT
    Location: https://9.9.9.9:8422/ibm/director/rest/VMControl/repositories/createRepos
    Server: Noelios-Restlet-Engine/1.1.4
    
    {
      "MessageText": "DNZEMW429I New job activation for creating the repository was 
    	started.\nRefer to the following URI for job activation status: 
    	/ibm/director/rest/jobs/324/activations/1",
      "MessageID": "DNZEMW429I"
    }

Monitor the create repository job

The final step in creating a repository is to monitor its progress to completion. The recommended method to monitor repository creation is through the job activation record. As seen 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.


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 4. 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 5. 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

    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 6. 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 7. 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 8. 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 9. 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.


Create a virtual appliance by import

You can use the IBM Systems Director VMControl REST APIs to import a virtual appliance package from the Internet or from other sources and store its component files to create a virtual appliance. You can then deploy the virtual appliance into your data center.

It is possible to import virtual appliance packages containing the following virtual server images:

  • AIX mksysb images for IBM POWER® processor-based logical partitions
  • AIX raw disk images for IBM POWER processor-based logical partitions
  • IBM i raw disk images for IBM POWER processor-based logical partitions
  • IBM Power Systems running Linux raw disk images for IBM POWER processor-based logical partitions
  • Linux and Microsoft® Windows® images for Linux KVM
  • Linux on System z® images for z/VM

The VMControl REST APIs allow you to import either an open virtual appliance (OVA) package or an Open Virtual Machine Format (OVF) file. The OVA package is a tape archive (tar) file containing the operating system image and the OVF file.

Unless your OVA package is small or you have a fast network connection, we do not recommend using the VMControl REST APIs to import an OVA package. This is because in order to import an OVA package using REST, you must send the entire OVA package over the network in the request body.

Note: VMControl will only validate whether the OVF file is syntactically correct. It is the responsibility of the developer to ensure that the OVF file will allow for the image to be deployed successfully.

List the repositories available to store the virtual appliance

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 next request.

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

    Get the list of all repositories:

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

    Listing 10. 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"
    }

Create a virtual appliance

The next step is to request a virtual appliance to be created. The import operation takes either an OVF descriptor file or an OVA package. When importing an OVF file, the HTTP Content-Type header must be set to application/ovf+xml. For importing the OVA package, it is set to application/x-tar.

The import operation is synchronous with one exception. That exception is import OVF when the ISDAPIVersion HTTP header is set to 6.3.2.0 or higher. This example performs this action.

When importing an OVF file, the image file referenced by the OVF file must either be available on the Systems Director server or must be referenced by a URL that is accessible from the Systems Director server.

To perform an import operation, use the repository OID from the previous step and make a POST request to the virtualAppliances resource, passing the OVF file as specified below.

The response message body and location header will contain a URL pointing to the job activation record for the create virtual server task. The job activation record contains the status of the create virtual appliance request, including percentage complete and any status or error messages.

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

    Create a new virtual appliance in the repository with a unique OID of 17621 by importing the OVF file:

    POST https://myserver:port/{webContext}/VMControl/virtualAppliances?repository=17621

    Listing 11. Sample response representation
    Status Code: 202 OK
     Cache-Control: no-store
     Content-Type: text/html; charset=UTF-8
     Set-Cookie: JSESSIONID_ibm_console_80=0000DMNZHEmiba05m3pvgMH8bZ4;Path=/; Secure; 
    								HTTPOnly
     Expires: Thu, 01 Dec 1994 16:00:00 GMT
     Content-Length:  196
     Date: Fri, 13 Jul 2012 13:43:46 GMT	
     Location: https://9.9.9.9:8422/ibm/director/rest/jobs/170/activations/1
     Accept-Ranges: bytes
     Server: Noelios-Restlet-Engine/1.1.4
     Content-Language: en-US
    
    {
        "MessageID": "DNZEMW456I",
        "MessageText": "DNZEMW456I New \"Import image \" job [1] started for [17621].
    	\nRefer to the following URI for status: /ibm/director/rest/jobs/170
    							/activations/1"
    }

Monitor the create virtual appliance job

The final step in creating a virtual appliance is to monitor its progress to completion. The recommended method to monitor virtual appliance creation is through the job activation record. As shown earlier, 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 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.


Modify a virtual appliance

List the virtual appliances available to modify

The first step in modifying a virtual appliance is to retrieve a list of available virtual appliances. This can be done by either retrieving all known virtual appliances or by retrieving a list of virtual appliances that exists on an image repository. This example retrieves all virtual appliances. Select the appropriate virtual appliances from the list and save the value of its OID property. This value can be used in the subsequent requests.

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

    Get the list of all virtual appliances:

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

    Listing 12. Sample response representation
    {
        "candidates": {
            "uri": "/ibm/director/rest/VMControl/virtualAppliances/candidates"
        },
        "virtualAppliances": [
            {
                "properties": {},
                "oid": 28912,
                "name": "Virtual Appliance 1",
                "uri": "/ibm/director/rest/VMControl/virtualAppliances/28912"
            },
            {
                "properties": {},
                "oid": 29731,
                "name": "cap_nim",
                "uri": "/ibm/director/rest/VMControl/virtualAppliances/29731"
            },
            {
                "properties": {},
                "oid": 20495,
                "name": "cap_nim_aixmobb",
                "uri": "/ibm/director/rest/VMControl/virtualAppliances/20495"
            }
        ],
        "uri": "/ibm/director/rest/VMControl/virtualAppliances"
    }

Retrieve the OVF descriptor file for the virtual appliance

You can choose your virtual appliance and fetch the OVF descriptor file currently defined for the virtual appliance that needs to be updated. Using the virtual appliance OID from the previous step, create a GET request to the URL specified below.

It is recommended that you specify the Accept-Charset HTTP header to retrieve the OVF file in the format in which it was imported. If Accept-Charset is not specified, VMControl attempts to retrieve it in the UTF-8 format.

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

    Get the OVF descriptor file of virtual appliance 28912:

    GET https://myserver:port/{webContext}/VMControl/virtualAppliances/28912.ovf

    • Sample response representation
      The actual OVF file.

Modify a virtual appliance

Finally, it is time to create the modify virtual appliance request. Modify the OVF descriptor file that was retrieved from the previous step to add or remove information. Pass it in as the request body of your PUT request, specifying application/ovf+xml for your Content-Type HTTP header.

Note: VMControl will only validate whether the OVF file is syntactically correct. It is the responsibility of the developer to ensure that the OVF file will allow for the image to be deployed successfully.

The response contains the status of the modify virtual appliance request, including error messages.

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

    Modify the virtual appliance with a unique ID of 28912:

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

    • Sample request representation
      The updated OVF XML and the Content-Type should be application/ovf+xml
    Listing 13. Sample response
    Status Code: 200 OK
    Accept-Ranges: bytes
    Cache-Control: no-store
    Content-Language: en-US
    Content-Length: 966
    Content-Type: application/json; charset=UTF-8
    Date: Wed, 11 Jul 2012 12:24:21 GMT
    Server: Noelios-Restlet-Engine/1.1.4
    
    {
        "MessageID": "DNZEMW440E",
        "MessageText": "DNZEMW440E Update OVF request for virtual appliance: 
    						\"28912\" succeeded."
    }

Delete a virtual appliance

List the virtual appliances available to delete

The first step in deleting a virtual appliance is to retrieve a list of available virtual appliances. This can be done by either retrieving all known virtual appliances or by retrieving a list of virtual appliances that exists on an image repository. This example can retrieve all virtual appliances. Select the appropriate virtual appliances 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/virtualAppliances
  • HTTP method
    • GET
  • Sample request

    Get the list of all virtual appliances:

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

    Listing 14. Sample response representation
    {
        "candidates": {
            "uri": "/ibm/director/rest/VMControl/virtualAppliances/candidates"
        },
        "virtualAppliances": [
            {
                "properties": {},
                "oid": 28912,
                "name": "Virtual Appliance 1",
                "uri": "/ibm/director/rest/VMControl/virtualAppliances/28912"
            },
            {
                "properties": {},
                "oid": 29731,
                "name": "cap_nim",
                "uri": "/ibm/director/rest/VMControl/virtualAppliances/29731"
            },
            {
                "properties": {},
                "oid": 20495,
                "name": "cap_nim_aixmobb",
                "uri": "/ibm/director/rest/VMControl/virtualAppliances/20495"
            }
        ],
        "uri": "/ibm/director/rest/VMControl/virtualAppliances"
    }

Delete a virtual appliance

The next step is to request the virtual appliance to be deleted. Delete virtual appliance is an asynchronous operation.

The response will contain 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 delete virtual appliance task. The job activation record contains the status of the delete virtual appliance request, including percentage complete and any status or error messages.

  • URL
    • https://myappliance:port/{webContext}/VMControl/virtualAppliances/{vaOID}
  • HTTP method
    • DELETE
  • Sample request

    Delete the virtual appliance with a unique ID of 28912:

    DELETE https://myappliance:port/{webContext}/VMControl/virtualAppliances/28912

    Listing 15. Sample response representation
    Status Code: 200 OK
    Accept-Ranges: bytes
    Cache-Control: no-store
    Content-Language: en-US
    Content-Length: 195	
    Content-Type: application/json; charset=UTF-8
    Date: Wed, 11 Jul 2012 12:34:45 GMT
    Location: https://9.9.9.9:8422/ibm/director/rest/jobs/540/activations/1
    Server: Noelios-Restlet-Engine/1.1.4
    
    {
        "MessageID": "DNZEMW299I",
        "MessageText": "DNZEMW299I New \"Delete Virtual Appliance\" job [1] 
    	started.\nRefer to the following URI for status: /ibm/director/rest/
    	jobs/540/activations/1"
    }

Monitor the delete virtual appliance job

The final step in deleting a virtual appliance is to monitor its progress to completion. The recommended way to monitor virtual appliance deletion is through the job activation record. As seen 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=855964
ArticleTitle=IBM Systems Director VMControl resource lifecycle management: part 2
publish-date=01252013