IBM Systems Director VMControl resource lifecycle management: part 3

Remote image deployment 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 image deployment 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.



29 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 image deployment using the VMControl REST APIs. Image deployment is the act of installing an operating system on a new or existing virtual server. The result of deployment is a workload that encapsulates one or more virtual servers. The lifecycle of an image deployment has the following major functions:

  • Deploy a virtual appliance
  • List the workload and its members
  • Modify a workload (modify properties and power management)
  • Delete a workload

Figure 1 explains the image deployment lifecycle in detail with the sequence of different REST requests.

Figure 1. Image deployment lifecycle
Image Deployment Lifecycle

Objectives

The main objective of this tutorial is to help users understand the image deployment 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 on image deployment 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

List the customization to deploy

List the available virtual appliances for deployment

The first step in listing the deploy customization is to retrieve a list of virtual appliances. 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. Select the appropriate virtual appliance from the list and save the value of its object ID (OID) property. This value will be used in the next request.

Note: The URLs in these examples will 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/virtualAppliances
  • HTTP method
    • GET
  • Sample request

    Get the list of all virtual appliances:

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

    Listing 1. Sample response representation
    {
      "uri": "/ibm/director/rest/VMControl/virtualAppliances",
      "candidates": {"uri": "/ibm/director/rest/VMControl/virtualAppliances/candidates"},
      "virtualAppliances": [
        {
          "name": "Capture GM",
          "properties": {},
          "uri": "/ibm/director/rest/VMControl/virtualAppliances/12927",
          "oid": 12927
        },
        {
          "name": "capture",
          "properties": {},
          "uri": "/ibm/director/rest/VMControl/virtualAppliances/18729",
          "oid": 18729
        }
      ]
    }

List the targets for deployment

The next step is to list the target for deploy using the OID of the virtual appliances from the first request. A target can be a host, a server system pool, or a virtual server.

When selecting a host or a server system pool as a target, VMControl creates a new virtual server and deploys the virtual appliance to that virtual server. When selecting a virtual server, VMControl deploys the virtual appliance to that virtual server. You need to select the appropriate target from the list and save the value of its OID property. This value will be used in the next request.

  • URL
    • https://myserver:port/ibm/director/rest/VMControl/virtualAppliances/{virtualApplianceOID}/targets
  • HTTP method
    • GET
  • Sample request

    Get the list of targets for a virtual appliance with OID 18729:

    GET https://myserver:port/ibm/director/rest/VMControl/virtualAppliances/18729/targets

    Listing 2. Sample response representation
     {
      "targets": [
        {
          "name": "ip10-32-41-132_sles11SP1_10g",
          "customization": {"uri": "/ibm/director/rest/VMControl/virtualAppliances/18729
    						/targets/13952/customization"},
          "type": "virtualServer",
          "system": {"uri": "/ibm/director/rest/VMControl/virtualServers/13952"},
          "uri": "/ibm/director/rest/VMControl/virtualAppliances/18729/targets/13952",
          "oid": 13952
        },
        {
          "name": "sysPool1",
          "customization": {"uri": "/ibm/director/rest/VMControl/virtualAppliances/18729
    						/targets/18997/customization"},
          "type": "systemPool",
          "system": {"uri": "/ibm/director/rest/VMControl/systemPools/18997"},
          "uri": "/ibm/director/rest/VMControl/virtualAppliances/18729/targets/18997",
          "oid": 18997
        },
        {
          "name": "Server-8406-70Y-SN10E5A0A",
          "customization": {"uri": "/ibm/director/rest/VMControl/virtualAppliances/18729
    						/targets/16223/customization"},
          "type": "host",
          "system": {"uri": "/ibm/director/rest/VMControl/hosts/16223"},
          "uri": "/ibm/director/rest/VMControl/virtualAppliances/18729/targets/16223",
          "oid": 16223
        }
      ],
      "uri": "/ibm/director/rest/VMControl/virtualAppliances/18729/targets"
    }

Get deploy to host or existing virtual server customization

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 from the previous step, make a GET request to the URL specified below. The result will be a list of customization properties that can be used to deploy a virtual appliance.

This example shows the customization parameters when deploying to a host on the Power Systems™ server. There is an example further below for deploying to a server system pool. There is no example for deploying to an existing virtual server; it will contain a subset of the deployment to host properties related to network and storage.

These customization parameters contain all the information required for completing a deployment to host request. For a typical deployment, there are customization parameters for processor, memory, network, and storage. The customization parameters for deployment combine information from the host chosen for the deploy action and properties from the Open Virtual Machine Format (OVF) descriptor file from the virtual appliance.

The following example shows the customization parameters for deployment in a typical Power Systems environment. Customization parameters for other platforms (such as kernel-based virtual machine [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/virtualAppliances/{virtualApplianceOID}/targets/{targetOIDs}/customization
  • HTTP method
    • GET
  • Sample request

    Listing the customization properties to deploy a virtual appliance with unique ID 18729 to the host with a unique ID of 16223:

    GET https://myserver:port/ibm/director/rest/VMControl/virtualAppliances/18729/targets/16223/customization

    Sample response representation

    View listing 3

List the customization properties for deploying to server system pool

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

When deploying to a server system pool, VMControl first chooses the ideal host within the server system pool to be the target of deploy. This process uses the default values in the virtual appliance to determine the host that is best capable of supporting the deploy task. It can be influenced by using query parameters described in the virtualAppliances/{virtualApplianceOID}/targets/{targetOIDs}/customization resource. For more information about valid query parameters for this request, refer to the virtualAppliances/{virtualApplianceOID}/targets/{targetOIDs}/customization resource page in the IBM Systems Director 6.3.x SDK information center.

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.

  • URL
    • https://myserver:port/ibm/director/rest/VMControl/virtualAppliances/{virtualApplianceOID}/targets/{targetOIDs}/customization
  • HTTP method
    • GET
  • Sample request

    Listing the customization properties to deploy a virtual appliance with a unique ID of 18729 to the server system pool with a unique ID of 18997, where resulting virtual server will have remote restart capabilities enabled:

    Note: Values specified here for the query parameters cannot be overridden on the deploy request.

    GET https://myserver:port/ibm/director/rest/VMControl/ virtualAppliances/18729/targets/18997/customization?desiredCPU=3&remoteRestartCapable=true

    Sample response representation

    View listing 4

Deploy a virtual appliance

Deploy to host or to an existing virtual server

After retrieving the customization parameters from the previous step, the next step is to populate the JSON for your request. Create a JSON string with the name/value pair for the customization properties needed for deploy, including processor, memory, network, and storage parameters.

The result of the deploy request is a new workload, which is why the request is made to the workload resource. A workload represents one or more virtual servers that can be monitored and managed as a single entity. For example, you can manage a workload that might contain both: a web server and a database server. You can start and stop a workload, and thus the virtual servers it contains, as one entity.

The following request:

  • Indicates that the virtual appliance 18729 will be deployed to host 16233.
  • Indicates that the new virtual server will be attached to the Discovered/1014/0 network.
  • Assigns IP address, hostname, domain name, and other assorted network values to the virtual server.
  • Specifies to create a new disk from storage pool 13206 and assign disk 1 from the virtual appliance to that new disk.
  • Specifies to assign disk 2 from the virtual appliance to the existing disk 13599.

Request:

  • URL
    • https://myserver:port/ibm/director/rest/VMControl/workloads
  • HTTP method
    • POST
  • Sample request

    Deploying a virtual appliance with a unique ID of 18729 to the host with a unique ID of 16223:

    POST https://myserver:port/ibm/director/rest/VMControl/workloads

    Listing 3. Sample request representation
    {
        "workload":{
            "virtualAppliance":18729,
            "target":16223,
            "properties":[{
                    "name":"virtualnetworks",
                    "value":"Discovered/1014/0"
                },
    	    {
                    "name":"product.vs0.com.ibm.ovf.vmcontrol.adapter.networking.
    							ipv4addresses.5",
                    "value":"10.32.41.91"
                },
                {
                    "name":"product.vs0.com.ibm.ovf.vmcontrol.system.networking.
    							ipv4defaultgateway",
                    "value":"10.32.41.1"
                },
                {
                    "name":"product.vs0.com.ibm.ovf.vmcontrol.adapter.networking.
    							ipv4netmasks.5",
                    "value":"255.255.255.0"
                },
                {
                    "name":"product.vs0.com.ibm.ovf.vmcontrol.system.networking.
    							dnsIPaddresses",
                    "value":"10.20.0.2"
                },
                {
                    "name":"product.vs0.com.ibm.ovf.vmcontrol.system.networking.
    							hostname",
                    "value":"ip10-32-41-91"
                },
                {
                    "name":"product.vs0.com.ibm.ovf.vmcontrol.system.networking.
    							domainname",
                    "value":"pokprv.stglabs.ibm.com"
                },
                {
                    "name": "storagemapping",
                    "value": "[1]=assignedStorage:poolstorages[13206]"
                },
                {
                    "name": "storagemapping",
                    "value": "[2]=assignedStorage:existingdisks[13599]"
                }
            ]
        }
    }
    Listing 4. Sample response
    HTTP/1.1 201 OK
    Cache-Control: no-store
    Set-Cookie: JSESSIONID_ibm_console_80=0000K8fh4uUjiNXmKSJ3uwePWO_;Path=/; Secure; 
    						HTTPOnly
    Expires: Thu, 01 Dec 1994 16:00:00 GMT
    Content-Type: application/octet-stream; charset=UTF-8
    Content-Length: 46
    Date: Tue, 10 Jul 2012 09:24:32 GMT
    Location: https://9.12.181.48:8422/ibm/director/rest/VMControl/workloads/19001
    Accept-Ranges: bytes
    Server: Noelios-Restlet-Engine/1.1.4
    Content-Language: en-US
    
    DNZEMW350I Workload [19001] creation started.

Listing 6 shows a sample response from the POST request. The Location HTTP header contains a URL to the workload being created. Deploying a virtual appliance is an asynchronous operation. It must be monitored until completion.

A progress log, containing messages on the status of the deploy, is provided with the /ibm/director/rest/VMControl/workloads/{workloadOID}/progress resource. In the event of a failed deploy, this is the location to retrieve more details on why it failed. Otherwise, the progress resource is removed after a successful deployment.

You can find more information about monitoring the deployment to completion after the Deploy to a server system pool section.

Deploy to a server system pool

This request is to create a workload by deploying a virtual appliance to a server system pool. It is very similar to deploying to the host request mentioned above with the following changes:

  • The addition of the deploymentplanid property, which was retrieved from the deploy to server system pool customization request.
  • The removal of the storagemapping parameter. When deploying to a server system pool, all disks are created in the storage pool or storage system pool associated with the server system pool.
  • URL
    • https://myserver:port/ibm/director/rest/VMControl/workloads
  • HTTP method
    • POST
  • Sample request

    Refer to the List the customization to deploy section for deploying a virtual appliance with a unique ID of 18729 to the server system pool with a unique ID of 18997 to form the JSON:

    POST https://myserver:port/ibm/director/rest/VMControl/workloads

    Listing 5. Sample request representation
    {
        "workload":{
            "virtualAppliance":18729,
            "target":18997,
            "properties":[{
                    "name":"virtualnetworks",
                    "value":"Discovered/1014/0"
                },
    	    {
                    "name":"product.vs0.com.ibm.ovf.vmcontrol.adapter.networking.
    							ipv4addresses.5",
                    "value":"10.32.41.91"
                },
                {
                    "name":"product.vs0.com.ibm.ovf.vmcontrol.system.networking.
    							ipv4defaultgateway",
                    "value":"10.32.41.1"
                },
                {
                    "name":"product.vs0.com.ibm.ovf.vmcontrol.adapter.networking.
    							ipv4netmasks.5",
                    "value":"255.255.255.0"
                },
                {
                    "name":"product.vs0.com.ibm.ovf.vmcontrol.system.networking.
    							dnsIPaddresses",
                    "value":"10.20.0.2"
                },
                {
                    "name":"product.vs0.com.ibm.ovf.vmcontrol.system.networking.
    							hostname",
                    "value":"ip10-32-41-91"
                },
                {
                    "name":"product.vs0.com.ibm.ovf.vmcontrol.system.networking.
    							domainname",
                    "value":"pokprv.stglabs.ibm.com"
                },
    	    {
                    "name":"deploymentplanid",
                    "value":"-84070689234545581_00"
                }
            ]
        }
    }
    Listing 6. Sample response
    HTTP/1.1 201 OK
    Cache-Control: no-store
    Set-Cookie: JSESSIONID_ibm_console_80=0000btq85Q1wmv6RhWcipLAaP8F;Path=/; Secure; 
    							HTTPOnly
    Expires: Thu, 01 Dec 1994 16:00:00 GMT
    Content-Type: application/octet-stream; charset=UTF-8
    Content-Length: 46
    Date: Tue, 10 Jul 2012 09:19:49 GMT
    Location: https://9.12.181.48:8422/ibm/director/rest/VMControl/workloads/19000
    Accept-Ranges: bytes
    Server: Noelios-Restlet-Engine/1.1.4
    Content-Language: en-US
    
    DNZEMW350I Workload [19000] creation started.

As we saw with deploy to host, the Location HTTP header contains a URL to the workload being created. The deploy request must be monitored to completion.

Monitoring the deploy request

There are a number of ways to monitor the deploy request to completion. This section covers all of these options.

The first option is to follow the progress log returned in the Location HTTP header for the deploy request. You can find the progress log at: /ibm/director/rest/VMControl/workloads/{workloadOID}/progress and is available during the deploy process. It is available after the deployment is complete and also if the deployment fails. If the deploy is successful, then the progress resource is deleted.

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

  • GET /ibm/director/rest/resources/VirtualAppliance/{vaOID}/events
  • GET /ibm/director/rest/events?ComponentType=VirtualAppliance&ComponentCategory=ManagedElement.ManagedSystemElement.LogicalElement.SoftwarePackage

The first response returns all the events for the specified virtual appliance while the second response filters all events to find events against the VirtualAppliance resource with a category of ManagedElement.ManagedSystemElement.LogicalElement.SoftwarePackage.

  • URL
    • https://myserver:port/ibm/director/rest/resources/VirtualAppliance/{vaoid}/events
  • HTTP method
    • GET
  • Sample request

    List all the events for a virtual appliance with a unique ID of 18729:

    GET https://myserver:port/ibm/director/rest/resources/VirtualAppliance/18729/events

    Listing 7. Sample response representation
    {"events": [
      {
        "EventID": 226875,
        "ComponentCategory": "ManagedElement.ManagedSystemElement.LogicalElement.
    								SoftwarePackage",
        "Severity": "Harmless",
        "Mode": "RESOLUTION",
        "EventText": "A deploy has been successful creating WorkloadInstance 
    	05422ad6-9a93-43e7-b4cb-4fd8108c30bf and the Virtual System WL_149_59367.",
        "uri": "/ibm/director/rest/events/226875",
        "ComponentInstance": null,
        "ComponentType": "VirtualAppliance"
      },
      {
        "EventID": 224929,
        "ComponentCategory": "ManagedElement.ManagedSystemElement.LogicalElement.
    								SoftwarePackage",
        "Severity": "Critical",
        "Mode": "ALERT",
        "EventText": "A deploy has failed for Virtual Appliance 
    	79ba9e0d-5d71-4789-94fb-3c32f0d5c747.\ncom.ibm.ensemble.server.core.api.
    	EMException: DNZEMC766E A problem occurred. Exception encountered: com.ibm.
    	director.im.common.exceptions.DeployException: DNZIMN882E The deploy task 
    	is not progressing and has timed out.",
        "uri": "/ibm/director/rest/events/224929",
        "ComponentInstance": null,
        "ComponentType": "VirtualAppliance"
      }
    ]}
  • URL
    • https://myserver:port/ibm/director/rest/events?ComponentType=VirtualAppliance&ComponentCategory=ManagedElement.ManagedSystemElement.LogicalElement.SoftwarePackage
  • HTTP method
    • GET
  • Sample request

    List all the IBM Systems Director events where the component type for the event is VirtualAppliance and the category is ManagedElement.ManagedSystemElement.LogicalElement.SoftwarePackage:

    GET https://myserver:port/ibm/director/rest/events?ComponentType=VirtualAppliance&ComponentCategory=ManagedElement.ManagedSystemElement.LogicalElement.SoftwarePackage

    Listing 8. Sample response representation
    {
      "events": [
      {
        "EventID": 226875,
        "ComponentCategory": "ManagedElement.ManagedSystemElement.LogicalElement.
    								SoftwarePackage",
        "Severity": "Harmless",
        "Mode": "RESOLUTION",
        "EventText": "A deploy has been successful creating WorkloadInstance 
    	05422ad6-9a93-43e7-b4cb-4fd8108c30bf and the Virtual System WL_149_59367.",
        "uri": "/ibm/director/rest/events/226875",
        "ComponentInstance": null,
        "ComponentType": "VirtualAppliance"
      },
      {
        "EventID": 226871,
        "ComponentCategory": "ManagedElement.ManagedSystemElement.LogicalElement.
    								SoftwarePackage",
        "Severity": "Harmless",
        "Mode": "RESOLUTION",
        "EventText": "A deploy has been successful creating WorkloadInstance 
    	05422ad6-9a93-43e7-b4cb-4fd8108c30bf and the Virtual System WL_149_59367.",
        "uri": "/ibm/director/rest/events/226871",
        "ComponentInstance": null,
        "ComponentType": "VirtualAppliance"
      },
      {
        "EventID": 224929,
        "ComponentCategory": "ManagedElement.ManagedSystemElement.LogicalElement.
    								SoftwarePackage",
        "Severity": "Critical",
        "Mode": "ALERT",
        "EventText": "A deploy has failed for Virtual Appliance 
    	79ba9e0d-5d71-4789-94fb-3c32f0d5c747.\ncom.ibm.ensemble.server.core.api.
    	EMException: DNZEMC766E A problem occurred. Exception encountered: com.
    	ibm.director.im.common.exceptions.DeployException: DNZIMN882E The deploy 
    	task is not progressing and has timed out.",
        "uri": "/ibm/director/rest/events/224929",
        "ComponentInstance": null,
        "ComponentType": "VirtualAppliance"
      },
      {
        "EventID": 224924,
        "ComponentCategory": "ManagedElement.ManagedSystemElement.LogicalElement.
    								SoftwarePackage",
        "Severity": "Critical",
        "Mode": "ALERT",
        "EventText": "A deploy has failed for Virtual Appliance 
    	79ba9e0d-5d71-4789-94fb-3c32f0d5c747.\ncom.ibm.director.im.common.
    	exceptions.DeployException: DNZIMN882E The deploy task is not progressing 
    	and has timed out.",
        "uri": "/ibm/director/rest/events/224924",
        "ComponentInstance": null,
        "ComponentType": "VirtualAppliance"
      }
    ]}

These URL can be polled, but the recommended method is to use the Java™ Message Service (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.


View workload and workload members

List all the workloads

The workloads resource returns a list of all workloads known to VMControl. Query parameters are available that allow you to filter workloads (based on name, description, or state) or return additional properties for each of the workloads with a single call. For more information on these query parameters, refer to the workloads resource page of the Systems Director 6.3.x SDK information center.

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

    List all known workloads:

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

    Listing 9. Sample response representation
    {
      "candidateServers": {"uri": "/ibm/director/rest/VMControl/workloads/
    						candidateServers"},
      "uri": "/ibm/director/rest/VMControl/workloads",
      "workloads": [
        {
          "name": "workload1",
          "properties": {},
          "uri": "/ibm/director/rest/VMControl/workloads/18994",
          "oid": 18994,
          "state": {
            "label": "Started",
            "id": 8
          }
        },
        {
          "name": "workload2",
          "properties": {},
          "uri": "/ibm/director/rest/VMControl/workloads/18995",
          "oid": 18995,
          "state": {
            "label": "Started",
            "id": 8
          }
        }
      ]
    }

View workload properties

The workload resource returns detailed information about the specified workload. The items in the properties JSON object are available to be returned for all workloads in the previous request using either the Props query for individual properties or the DefaultProps query to return everything in the properties JSON object.

  • URL
    • https://myserver:port/ibm/director/rest/VMControl/workloads/{workloadOID}
  • HTTP method
    • GET
  • Sample request

    Retrieve the properties of a workload with a unique ID of 18994:

    GET https://myserver:port/ibm/director/rest/VMControl/workloads/18994

    Listing 10. Sample response representation
    {
      "oid": 18994,
      "detailedState": 0,
      "systemPools": {"uri": "/ibm/director/rest/VMControl/workloads/18994/systemPools"},
      "state": {
        "label": "Started",
        "id": 8
      },
      "approvalRequired": true,
      "uri": "/ibm/director/rest/VMControl/workloads/18994",
      "properties": {
        "Description": "First workload",
        "Vendor": {},
        "ApprovalRequired": true,
        "ChangedDate": 1341908501000,
        "Oid": 18994,
        "SpecificationVersion": 0,
        "Name": "workload1",
        "Info": {},
        "Resilient": false,
        "State": "Started"
      },
      "hosts": {"uri": "/ibm/director/rest/VMControl/workloads/18994/hosts"},
      "remoteRestart": false,
      "createdBy": "root",
      "specificationVersion": 0,
      "metrics": {"uri": "/ibm/director/rest/resources/WorkloadInstance/18994/
    				monitorviews/WORKLOAD_METRICS_GROUP_ID/monitordata"},
      "virtualServers": {"uri": "/ibm/director/rest/VMControl/workloads/18994/
    								virtualServers"},
      "description": "First workload",
      "changedDate": 1341908501000,
      "virtualServerCount": 1,
      "resilient": "None",
      "liveVirtualServerRelocation": false,
      "info": "UNDEFINED",
      "vendor": "UNDEFINED",
      "priority": 2,
      "name": "workload1"
    }

View workload members

A workload represents one or more virtual servers that can be monitored and managed as a single entity. Within the context of this tutorial, workloads will contain only a single virtual server, as that is the only result of the current deployment process. That makes this resource a little less interesting.

Manual workload creation, or the grouping of existing virtual servers, can result in a workload containing more than one member. The topic of manual workload creation is out of the scope of this tutorial. For more information on manual workload creation, refer to the workloads resource page of the Systems Director 6.3.x SDK information center.

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

    List the members of a workload with a unique ID of 18994:

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

    Listing 11. Sample response representation
    {
      "uri": "/ibm/director/rest/VMControl/workloads/18994/virtualServers",
      "virtualServers": [{
        "name": "ip10-32-41-98_rhel62_10g",
        "properties": {},
        "customization": {"uri": "/ibm/director/rest/VMControl/hosts/16223/virtualServers
    								/16220/customization"},
        "oid": 16220,
        "uri": "/ibm/director/rest/VMControl/hosts/16223/virtualServers/16220",
        "state": {
          "label": "Started",
          "id": 8
        }
      }]
    }

Modify a workload

This next section describes about updating an existing workload. Workload updates are simple property updates, such as: name, description, state, and, if the workload was created through the deploy to server system pool, a number of properties dealing with high availability and resiliency of the workload.

Depending on the operation, the modify workload task can be a synchronous or an asynchronous operation. Property changes are synchronous while state changes are asynchronous.

Successful running of the request will respond with a HTTP status code of 200 (OK) for a property change or 202 (Accepted) for a state change. In the case of the 202 (Accepted) status code, the Location HTTP header will include the Uniform Resource Identifier (URI) of the job that was created for this action.

There are two examples given below. The first example shows a property change and the second example shows a state change.

  • URL
    • https://myserver:port/ibm/director/rest/VMControl/workloads/{workloadOID}
  • HTTP method
    • PUT
  • Sample request 1

    Modify the name of the workload with a unique ID of 6798:

    PUT https://myserver:port/ibm/director/rest/VMControl/workloads/6798

    Listing 12. Sample request representation
    {
        "workload": {
            "name": "myUpdatedWorkload"
        }
    }
    Listing 13. Sample response
    HTTP/1.1 200 OK
    Cache-Control: no-store
    Set-Cookie: JSESSIONID_ibm_console_80=0000pF3CdRrz4WwSv4LsNiwI4jJ;Path=/; Secure; 
    							HTTPOnly
    Expires: Thu, 01 Dec 1994 16:00:00 GMT
    Content-Type: application/json; charset=UTF-8
    Content-Length: 97
    Date: Tue, 10 Jul 2012 08:50:33 GMT
    Accept-Ranges: bytes
    Server: Noelios-Restlet-Engine/1.1.4
    Content-Language: en-US
    
    {
      "MessageText": "DNZEMW308I The workload update completed successfully.",
      "MessageID": "DNZEMW308I"
    }
  • Sample request 2

    Modify the state of the workload with a unique ID of 6798:

    PUT https://myserver:port/ibm/director/rest/VMControl/workloads/6798

    Listing 14. Sample request representation
    {
        "workload": {
            "state": 5
        }
    }
    Listing 15. Sample response
    HTTP/1.1 202 OK
    Cache-Control: no-store
    Set-Cookie: JSESSIONID_ibm_console_80=0000xxKiy8AAgbCQUgRuA5bQvDk;Path=/; Secure; 
    							HTTPOnly
    Expires: Thu, 01 Dec 1994 16:00:00 GMT
    Content-Type: application/json; charset=UTF-8
    Content-Length: 216
    Date: Fri, 20 Jul 2012 18:42:02 GMT
    Location: https://9.12.183.62:8422/ibm/director/rest/jobs/224/activations/1
    Accept-Ranges: bytes
    Server: Noelios-Restlet-Engine/1.1.4
    Content-Language: en-US
    
    {
      "MessageText": "DNZEMW307I New job activation for updating the workload was 
    	started.\nRefer to the following URI for job activation status: 
    	/ibm/director/rest/jobs/224/activations/1 ",
      "MessageID": "DNZEMW307I"
    }

Monitor the modify workload job

The final step in modifying a workload is to monitor its progress to completion. The recommended method to monitor the modify workload 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.


Delete workloads

Delete a workload

The next step is to request the workload to be deleted. Deleting a workload can be a synchronous or asynchronous operation depending on the query parameters and the value of the ISDAPIVersion HTTP header included in the request.

Deleting a workload without deleting the included virtual servers is synchronous. Deleting the included virtual servers and storage associated with the virtual servers is also synchronous unless the ISDAPIVersion HTTP header is set to 6.3.2.0 or higher.

  • URL
    • https://myserver:port/ibm/director/rest/VMControl/workloads/{workloadOID}
  • HTTP method
    • DELETE
  • Sample request

    Delete the workload with a unique ID of 6798:

    DELETE https://myserver:port/ibm/director/rest/VMControl/workloads/6798

    Listing 16. Sample response representation
    HTTP/1.1 202 OK
    Cache-Control: no-store
    Set-Cookie: JSESSIONID_ibm_console_80=0000FfgRXo3ew2Q6dd0ndxPnYIC;Path=/; Secure; 
    							HTTPOnly
    Expires: Thu, 01 Dec 1994 16:00:00 GMT
    Content-Type: application/json; charset=UTF-8
    Content-Length: 92
    Date: Tue, 10 Jul 2012 08:43:39 GMT
    Accept-Ranges: bytes
    Server: Noelios-Restlet-Engine/1.1.4
    Content-Language: en-US
    
    {"MessageID":"DNZEMW389I","MessageText":"DNZEMW389I New Delete workload operation 
    							started."}

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=855728
ArticleTitle=IBM Systems Director VMControl resource lifecycle management: part 3
publish-date=01292013