IBM Systems Director VMControl resource lifecycle management: part 4

Remote server system pool 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 about server system pool 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.



04 February 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 server system pool resource using the VMControl REST APIs. The lifecycle of a server system pool has the following major functions:

  • Create a server system pool
  • List server system pool and its members
  • Modify a server system pool (modify properties and add/remove host)
  • Relocate a virtual server
  • Delete a server system pool

Figure 1 explains the server system pool lifecycle in detail with the sequence of different REST requests.

Figure 1. Server system pool lifecycle
Server System Pool Lifecycle

Objectives

The main objective of this tutorial is to help users understand the server system pool lifecycle using the VMControl REST APIs. This tutorial describes the complete lifecycle with the purview of using it with IBM System Director VMControl. Users with the basic knowledge on server system pool 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 a server system pool

List the available hosts for system pool creation

A server system pool logically groups similar hosts with the goal of better resource usage and workload resilience. A server system pool is comprised of multiple hosts and their associated virtual servers, along with an attached shared storage.

The first step in the creation of a server system pool is to list the available hosts required for creation of server system pool. Select the appropriate host from the list and save the value of its object ID (OID) property. This value will be used in the next request.

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

    Get the list of all hosts:

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

    Listing 1. Sample response representation
    {
        "hosts":[{
                "uri":"/ibm/director/rest/VMControl/hosts/13953",
                "oid":13953,
                "name":"Server-8406-70Y-SN10E59BA",
                "customization":{
                    "uri":"/ibm/director/rest/VMControl/hosts/13953/customization"
                },
                "virtualServers":{
                    "uri":"/ibm/director/rest/VMControl/hosts/13953/virtualServers"
                },
                "properties":{}
            },
            {
                "uri":"/ibm/director/rest/VMControl/hosts/16223",
                "oid":16223,
                "name":"Server-8406-70Y-SN10E5A0A",
                "customization":{
                    "uri":"/ibm/director/rest/VMControl/hosts/16223/customization"
                },
                "virtualServers":{
                    "uri":"/ibm/director/rest/VMControl/hosts/16223/virtualServers"
                },
                "properties":{}
            }
        ],
        "uri":"/ibm/director/rest/VMControl/hosts"
    }

List the storage pools attached to the host

A server system pool can be created only when there is an accessible storage that is available to the host. All hosts in the server system pool must have access to this same storage. This request lists the compatible storage pools available with a single host or can list the storage pools common to a comma-separated list of hosts. The host or list of hosts are specified using the required host-query parameter.

  • URL
    • https://myserver:port/ibm/director/rest/VMControl/storagePools?host=13953
  • HTTP method
    • GET
  • Sample request

    Get the storage pools attached to a host with a unique ID of 13953:

    GET https://myserver:port/ibm/director/rest/VMControl/storagePools?host=13953

    Listing 2. Sample response representation
    {
        "storagePools":[{
                "availableStorage":430080,
                "totalStorage":524288,
                "oid":13203,
                "name":"Storwize V7000-2076-VMC7000_1-IBM/00000200A0203BD9:9+203BD9+0",
                "uri":"/ibm/director/rest/storagePools/13203"
            },
            {
                "availableStorage":264960,
                "totalStorage":785920,
                "oid":13204,
                "name":"Storwize V7000-2076-VMC7000_1-IBM/00000200A0203BD9:8+03BD9+0",
                "uri":"/ibm/director/rest/storagePools/13204"
            },
            {
                "availableStorage":449280,
                "totalStorage":523776,
                "oid":13205,
                "name":"Storwize V7000-2076-VMC7000_1-IBM/00000200A0203BD9:7+0203BD9+0",
                "uri":"/ibm/director/rest/storagePools/13205"
            },
            {
                "availableStorage":431104,
                "totalStorage":2097152,
                "oid":13206,
                "name":"Storwize V7000-2076-VMC7000_1-IBM/00000200A0203BD9:A0203BD9+0",
                "uri":"/ibm/director/rest/storagePools/13206"
            }
        ],
        "uri":"/ibm/director/rest/VMControl/storagePools?host=13953"
    }

Create a server system pool with a single host

Now that you have your host and storage selected, the next step is to request a new server system pool to be created. Using the following example as a template, create a JSON string containing information about the server system pool to be created. The following request:

  • Indicates that host 13953 and attached storage 13203 will initially make up the new server system pool.
  • Indicates that auto optimization is enabled and the automation interval is set to 60 minutes.
  • Sets the name and description for the new server system pool.

Note: Optimization enables the analysis and periodic performance improvement of all the virtual servers within your server system pool based on your specified needs. With optimization, you can configure your IBM Systems Director VMControl server system pools to relocate the virtual servers within a workload to the most efficient hosts.

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

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

    Create a new server system pool with the host with a unique ID of 13953:

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

    Listing 3. Sample request representation
    {
        "name": "SystemPool",
        "description": "This is a new Power system pool",
        "optimizationInterval": 60,
        "autoOptimization": true,
        "storageId": 13203,
        "hostIds":13953
        
    }
    Listing 4. Sample response representation
    HTTP/1.1 201 OK
    Cache-Control: no-store
    Set-Cookie: JSESSIONID_ibm_console_80=00007ID-HpF24AAYtRxUDiikVk4;Path=/; Secure; 
    									HTTPOnly
    Expires: Thu, 01 Dec 1994 16:00:00 GMT
    Content-Type: application/octet-stream; charset=UTF-8
    Content-Length: 190
    Date: Mon, 14 May 2012 02:34:13 GMT
    Location: https://9.9.9.9:8422/ibm/director/rest/VMControl/systemPools/SystemPool
    Accept-Ranges: bytes
    Server: Noelios-Restlet-Engine/1.1.4
    Content-Language: en-US
    
    {
      "MessageText": "DNZEMW066I New "Create Server System Pool" job [1] started.\nRefer 
    	to the following URI for status: /ibm/director/rest/jobs/153/activations/1 ",
      "MessageID": "DNZEMW066I"
    }

Create a server system pool with multiple hosts

While the above example allows you to set auto optimization for the server system pool, you will either need to add a second host to the server system pool or create a server system pool with two or more hosts in order to take advantage of the relocation aspects of the optimization process.

The JSON string used in creating a server system pool with multiple hosts is very similar to the above, only using a JSON array for the hostIds property.

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

    Create a new server system pool with the hosts with unique IDs of 13953 and 16223:

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

    Listing 5. Sample request representation
    {
        "name": "SystemPool2",
        "description": "This is a new Power system pool",
        "optimizationInterval": 60,
        "autoOptimization": true,
        "storageId": 13203,
        "hostIds": [
            13953,
            16223
        ]
    }
    Listing 6. Sample response representation
    HTTP/1.1 201 OK
    Cache-Control: no-store
    Set-Cookie: JSESSIONID_ibm_console_80=00007ID-HpF24AAYtRxUDiikVk4;Path=/; Secure; 
    									HTTPOnly
    Expires: Thu, 01 Dec 1994 16:00:00 GMT
    Content-Type: application/octet-stream; charset=UTF-8
    Content-Length: 190
    Date: Mon, 14 May 2012 02:34:13 GMT
    Location: https://9.9.9.9:8422/ibm/director/rest/VMControl/systemPools/SystemPool2
    Accept-Ranges: bytes
    Server: Noelios-Restlet-Engine/1.1.4
    Content-Language: en-US
    
    {
      "MessageText": "DNZEMW066I New "Create Server System Pool" job [1] started.\nRefer 
    	to the following URI for status: /ibm/director/rest/jobs/154/activations/1 ",
      "MessageID": "DNZEMW066I"
    }

Monitor the create a server system pool job

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

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

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


List server system pool and its members

List the server system pools

This request retrieves all the available server system pools and a subset of the system pool properties.

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

    Get the list of all server system pools:

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

    Listing 7. Sample response representation
    {
        "systemPools":[{
                "state":{
                    "label":"Active",
                    "id":20
                },
                "status":{
                    "label":"Healthy",
                    "id":0
                },
                "type":"KVM",
                "oid":19362,
                "name":"systempool233",
                "uri":"/ibm/director/rest/VMControl/systemPools/19362"
            }
        ],
        "uri":"/ibm/director/rest/VMControl/systemPools"
    }

View the server system pool

The following example shows server system pool properties. These properties include the name, description, and current status of the server system pool as well as the number of hosts in the server system pool, a list of those hosts, resiliency and auto-optimization settings, and related storage information.

Note: Not all storage properties are applicable for each server system pool. Some are available for both kernel-based virtual machine (KVM) and IBM Power Systems™ hosts, others are for KVM or Power Systems only. An example of a KVM server system pool is given below.

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

    Get the server system pool properties with a unique ID of 19362:

    GET https://myserver:port/ibm/director/rest/VMControl/systemPools/19362

    Listing 8. Sample response representation
    {
        "systempool":{
            "hostCount":2,
            "oid":19362,
            "name":"SysPool",
            "description":"Server System Pool",
            "type":"KVM",
            "state":{
                "label":"Active",
                "id":20
            },
            "status":{
                "label":"Healthy",
                "id":0
            },
            "hostIds":[
                24545
            ],
            "platformVersion":"{ 'QEMU 0.12.1' }",
            "resilience":true,
            "autoOptimization":false,
            "optimizationInterval":30,
            "fileSystemOwner":"21862IBM 7976MC1 KQAGYT3:/nfs/kvm/images|
                                                /var/lib/libvirt/images",
            "fileSystemPath":"/nfs/kvm/images|/var/lib/libvirt/images",
            "fileSystemRoot":"/",
            "commonMountPath":"/var/lib/libvirt/images",
            "fileSystemName":"/dev/sda3",
            "fileSystemOid":21862,
            "storageOwningSubSystem":"Not Applicable",
            "storagePoolName":"Not Applicable",
            "storagePoolOid":"Not Applicable",
            "storageSystemOwningSubSystem":"Not Applicable",
            "storageSystemPoolOid":"Not Applicable",
            "storageSystemPoolPolicy":"Not Applicable",
            "storageSystemPoolName":"Not Applicable",
            "hosts":{
                "uri":"https://9.47.203.12:8422/ibm/director/rest/
                       VMControl/systemPools/30268/hosts"
            },
            "metrics":{
                "uri":"https://9.47.203.12:8422/ibm/director/rest/resources/SystemPool/
                       30268/monitorviews/VSP_METRICS_GROUP_ID/monitordata"
            },
            "virtualServers":{
                "uri":"https://9.47.203.12:8422/ibm/director/rest/
                       VMControl/systemPools/30268/virtualServers"
            },
    		"workloads":{
                "uri":"https://9.47.203.12:8422/ibm/director/rest/
                       VMControl/systemPools/30268/workloads"
            },
    		"uri":"https://9.47.203.12:8422/ibm/director/rest/
                   VMControl/systemPools/30268"
        }
    }

List the member hosts of a server system pools

This requests retrieve all the member hosts of a server system pool. This information is helpful when adding and removing hosts from a server system pool.

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

    Get the member hosts of a server system pool with a unique ID of 19362:

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

    Listing 9. Sample response representation
    {
        "hosts":[{
               "uri":"/ibm/director/rest/VMControl/hosts/13953",
               "oid":13953,
               "name":"Server-8406-70Y-SN10E59BA",
               "customization":{
                   "uri":"/ibm/director/rest/VMControl/hosts/13953/customization"
               },
               "virtualServers":{
                   "uri":"/ibm/director/rest/VMControl/hosts/13953/virtualServers"
               },
               "properties":{}
            },
            {
               "uri":"/ibm/director/rest/VMControl/hosts/16223",
               "oid":16223,
               "name":"Server-8406-70Y-SN10E5A0A",
               "customization":{
                   "uri":"/ibm/director/rest/VMControl/hosts/16223/customization"
               },
               "virtualServers":{
                   "uri":"/ibm/director/rest/VMControl/hosts/16223/virtualServers"
               },
               "properties":{}
            }
        ],
        "uri":"/ibm/director/rest/VMControl/systemPools/25607/hosts"
    }

List the member virtual servers of a server system pools

This request retrieves all the virtual servers that exist in a server system pool.

Note: This lists all virtual servers on all hosts in the server system pool. A virtual server in this list may not be managed by the server system pool. Virtual servers must be managed by the server system pool in order to be eligible for relocation within the server system pool.

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

    Get the member virtual servers of a server system pool with a unique ID of 19362:

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

    Listing 10. Sample response representation
    {
        "virtualServers":[{
                "uri":"/ibm/director/rest/VMControl/virtualServers/20517",
                "oid":20517,
                "name":"pva8132_stg_vios#1",
                "state":{
                    "label":"Started",
                    "id":8
                },
                "customization":{
                  "uri":"/ibm/director/rest/VMControl/virtualServers/20517/customization"
                },
                "properties":{}
            },
            {
                "uri":"/ibm/director/rest/VMControl/virtualServers/20518",
                "oid":20518,
                "name":"IP10-32-41-27_RHEL62_10G_multi",
                "state":{
                    "label":"Started",
                    "id":8
                },
                "customization":{
                  "uri":"/ibm/director/rest/VMControl/virtualServers/20518/customization"
                },
                "properties":{}
            },
            {
                "uri":"/ibm/director/rest/VMControl/virtualServers/25555",
                "oid":25555,
                "name":"ip-10-32-42-105",
                "state":{
                    "label":"Started",
                    "id":8
                },
                "customization":{
                  "uri":"/ibm/director/rest/VMControl/virtualServers/25555/customization"
                },
                "properties":{}
            },
            {
                "uri":"/ibm/director/rest/VMControl/virtualServers/20519",
                "oid":20519,
                "name":"pva8069_network_vios",
                "state":{
                    "label":"Started",
                    "id":8
                },
                "customization":{
                  "uri":"/ibm/director/rest/VMControl/virtualServers/20519/customization"
                },
                "properties":{}
            }
        ],
        "uri":"/ibm/director/rest/VMControl/systemPools/19362/virtualServers"
    }

List the member workloads of server system pools

This request retrieves all the member workloads of a server system pool. A workload is a member of the server system pool if it was created through deploying to a server system pool or if it was manually created with a virtual server that is a part of the server system pool, but was not managed by the server system pool. For more information on these actions, refer to the workloads resource page of the IBM Systems Director 6.3.x SDK information center.

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

    Get the member workloads of a server system pool with a unique ID of 19362:

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

    Listing 11. Sample response representation
    {
        {
            "workloads": [
                {
                    "state": {
                        "label": "Started",
                        "id": 8
                    },
                    "oid": 25623,
                    "name": "Workload 1",
                    "uri": "/ibm/director/rest/VMControl/workloads/25623"
                },
                {
                    "state": {
                        "label": "Started",
                        "id": 8
                    },
                    "oid": 25625,
                    "name": "Workload 2",
                    "uri": "/ibm/director/rest/VMControl/workloads/25625"
                }
            ],
            "uri": "/ibm/director/rest/VMControl/systemPools/25607/workloads",
            "candidateServers": {
                "uri": "/ibm/director/rest/VMControl/systemPools/25607/workloads/
    							candidateServers"
            }
        }
    }

Modify a server system pool

Modifying a server system pool allows you to add a host, remove a host, or change the server system pools properties. A list of the properties that can be changed can be found in the systemPools/{systemPoolOID} resource page in the IBM Systems Director 6.3.x SDK information center.

Adding or removing a host from a server system pool is performed by specifying the hostIds JSON array. The contents of this array contain the list of hosts you want to exist in the server system pool at the end of the request. More than one host is allowed to be added to a server system pool with a single request, but only one host is allowed to be removed per request. Similarly, you cannot add and remove hosts with a single request. You cannot change system pool properties and add or remove a host in a single request.

Modify server system pool properties

The following request changes the auto-optimization and optimization interval for a server system pool. The optimization interval is in minutes.

The response contains two copies of the same URL. The URL in the location header and in the response message will point to the job activation record for the modify server system pool task. The job activation record contains the status of the modify server system pool request, including percentage complete and any status or error messages. You can find more information on the recommended method for monitoring this job in the Monitor the modify server system pool job section at the bottom of this page.

  • URL
    • https://myserver:port/ibm/director/rest/VMControl/systemPools/{systemPoolOID}
  • HTTP method
    • PUT
  • Sample request

    Modify the server system pool with a unique ID of 19362:

    PUT https://myserver:port/ibm/director/rest/VMControl/systemPools/19362

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

List candidate hosts for adding a host to a server system pool

The first step in adding a new host to a server system pool is to list hosts eligible to be added to the server system pool. Hosts returned by this request are of the same type as the hosts already in the server system pool and have access to the storage pool associated with the server system pool.

  • URL
    • https://myserver:port/ibm/director/rest/VMControl/systemPools/{systemPoolOID}/candidates
  • HTTP method
    • GET
  • Sample response

    List candidates hosts that can be added to the server system pools with a unique ID of 19362:

    PUT https://myserver:port/ibm/director/rest/VMControl/systemPools/19362/candidates

    Listing 14. Sample request representation
    {
        "candidates": [
            {
                "oid": 17475,
                "name": "Server-8406-70Y-SN10E5A0A",
                "uri": "/ibm/director/rest/VMControl/hosts/17475"
            }
        ],
        "uri": "/ibm/director/rest/VMControl/systemPools/19362/candidates"
    }

Add a host to a server system pool

As stated above, adding or removing a host to or from a server system pool is performed by specifying the hostIds JSON array. The contents of this array contain the list of hosts you want to exist in the server system pool at the end of the request. The following request adds the host with a unique ID of 17475 to the server system pool.

  • URL
    • https://myserver:port/ibm/director/rest/VMControl/systemPools/{systemPoolOID}
  • HTTP method
    • PUT
  • Sample request

    Add host 17475 to the server system pools with a unique ID of 19362:

    PUT https://myserver:port/ibm/director/rest/VMControl/systemPools/19362

    Listing 15. Sample request representation
    {
        "hostIds": [
            13953,
            16223,
            17475
        ]
    }
    Listing 16. Sample response representation
    HTTP/1.1 202 OK
    Cache-Control: no-store
    Set-Cookie: JSESSIONID_ibm_console_80=0000IcvCLIria75OPe4bSOWM4pP;Path=/; Secure; 
    								HTTPOnly
    Set-Cookie: AUTH_JSESSIONID=4mdooikm2p570b7np6r2f0smoj4;Path=/; HTTPOnly
    Expires: Thu, 01 Dec 1994 16:00:00 GMT
    Content-Type: application/json; charset=UTF-8
    Content-Length: 194
    Date: Tue, 09 Oct 2012 09:02:28 GMT
    Accept-Ranges: bytes
    Server: Noelios-Restlet-Engine/1.1.4
    Content-Language: en-US
    
    {"MessageID":"DNZEMW048I","MessageText":"DNZEMW048I New \"Update Server System Pool\"
    	 job [1] started.\nRefer to the following URI for status: 
    	\/ibm\/director\/rest\/jobs\/456\/activations\/1."}

Remove a host from a server system pool

The following request removes the host with a unique ID of 16223 from the server system pool. Setting the hostEvacuation parameter to true relocates all managed virtual servers from 16223 within the server system pool.

Note: If there are not sufficient resources to support relocating all of the managed virtual servers from the host that is being removed, then the remove host action will fail.

  • URL
    • https://myserver:port/ibm/director/rest/VMControl/systemPools/{systemPoolOID}
  • HTTP method
    • PUT
  • Sample request

    Remove the host from a server system pool with a unique ID of 19362:

    PUT https://myserver:port/ibm/director/rest/VMControl/systemPools/19362

    Listing 17. Sample request representation
    {
        "hostIds": [
            13953,
            17475
        ],
        "hostEvacuation" : true
    }
    Listing 18. Sample response representation
    HTTP/1.1 200 OK
    Cache-Control: no-store
    Set-Cookie: JSESSIONID_ibm_console_80=0000pQfvCzmvUwLN9zhSnvvzNtp;Path=/; Secure; 
    								HTTPOnly
    Set-Cookie: AUTH_JSESSIONID=4ra97j010cnohlcjl0e3feotb8d;Path=/; HTTPOnly
    Expires: Thu, 01 Dec 1994 16:00:00 GMT
    Content-Type: application/json; charset=UTF-8
    Content-Length: 110
    Date: Tue, 09 Oct 2012 09:03:08 GMT
    Accept-Ranges: bytes
    Server: Noelios-Restlet-Engine/1.1.4
    Content-Language: en-US
    
    {"MessageID":"DNZEMW069I","MessageText":"DNZEMW069I Update System pool 
    		(Remove host) completed successfully."}

Monitor the modify server system pool job

The final step in modifying the server system pool is to monitor its progress to completion. The recommended method to monitor server system pool modification is through the job activation record. As shown above, this URL is returned in response to 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.


Server system pool relocation

The relocation plans web service is responsible for relocating virtual servers within a server system pool. Relocation plans can relocate a single virtual server from one host to another in a server system pool, relocate (evacuate) all virtual servers on one host to one or more other hosts in a server system pool, or evacuate a host in order to enter the host in to maintenance mode.

Relocation operations are ran as a two-step process: first the relocation plan is created, then the plan is ran. It is important to note that because of the nature of system virtualization, relocation plans are valid only for a certain amount of time after which they become invalid. This is done to try to prevent the failure of running a plan that was created when some virtualization resources were available, but no longer are. If a relocation plan is invalid, it would not be possible to run it; however, it is always possible to create a new relocation plan resource to run.

Relocate a virtual server

This request creates a new relocation plan to relocate a virtual server with a unique ID to another host of a server system pool. The virtual server was retrieved using the systemPools/{systemPoolOID}/virtualServers resource described previously in this tutorial.

The result of the request will be a URL in the location HTTP header containing a link to the relocation plan being created. The state of the relocation plan sets to Initalizing until it has been either successfully created or is aborted due to the relocation plan not being valid for the server system pool.

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

    Create a plan to relocate a virtual server with a unique ID of 20518:

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

    Listing 19. Sample request representation
    {
        "relocationPlan":{
            "virtualServer":20518
        }
    }
    Listing 20. Sample response representation
    HTTP/1.1 201 OK
    Cache-Control: no-store
    Set-Cookie: JSESSIONID_ibm_console_80=00007ID-HpF24AAYtRxUDiikVk4;Path=/; Secure; 
    									HTTPOnly
    Expires: Thu, 01 Dec 1994 16:00:00 GMT
    Content-Type: application/octet-stream; charset=UTF-8
    Content-Length: 190
    Date: Mon, 14 May 2012 02:34:13 GMT
    Location: https://9.9.9.9:8422/ibm/director/rest/VMControl/relocationPlans/8847669583
    Accept-Ranges: bytes
    Server: Noelios-Restlet-Engine/1.1.4
    Content-Language: en-US
    
    {"MessageID":"DNZEMW024I","MessageText":"DNZEMW024ICreated relocation plan
    	[/ibm/director/rest/VMControl/relocationPlans/8847669583]."}

Relocate a virtual server with destination

This request relocates the same virtual server, but specifies the host where you want the virtual server to be relocated to. The destination parameter is valid only when specifying a single virtual server for relocation. It must be a part of the server system pool and contain sufficient resources to support the virtual server to be relocated.

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

    Create a plan to relocate the virtual server to the destination host with a unique ID of 20518:

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

    Listing 21. Sample request representation
    {
        "relocationPlan":{
            "destination":14084,
            "virtualServer":17475
        }
    }
    Listing 22. Sample response representation
    HTTP/1.1 201 OK
    Cache-Control: no-store
    Set-Cookie: JSESSIONID_ibm_console_80=00007ID-HpF24AAYtRxUDiikVk4;Path=/; Secure; 
    									HTTPOnly
    Expires: Thu, 01 Dec 1994 16:00:00 GMT
    Content-Type: application/octet-stream; charset=UTF-8
    Content-Length: 190
    Date: Mon, 14 May 2012 02:35:15 GMT
    Location: https://9.9.9.9:8422/ibm/director/rest/VMControl/relocationPlans/8847669586
    Accept-Ranges: bytes
    Server: Noelios-Restlet-Engine/1.1.4
    Content-Language: en-US
    
    {"MessageID":"DNZEMW024I","MessageText":"DNZEMW024ICreated relocation plan
    	[/ibm/director/rest/VMControl/relocationPlans/8847669586]."}

Relocate all virtual servers on a host

In this example, we specify a host instead of a virtual server. This will result in all server system pool managed virtual servers that reside on that host to be relocated within the server system pool.

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

    Create a plan to relocate all the virtual server on the host with a unique ID of 14085:

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

    Listing 23. Sample request representation
    {
        "relocationPlan":{
            "host":13953
        }
    }
    Listing 24. Sample response representation
    HTTP/1.1 201 OK
    Cache-Control: no-store
    Set-Cookie: JSESSIONID_ibm_console_80=00007ID-HpF24AAYtRxUDiikVk4;Path=/; Secure; 
    									HTTPOnly
    Expires: Thu, 01 Dec 1994 16:00:00 GMT
    Content-Type: application/octet-stream; charset=UTF-8
    Content-Length: 190
    Date: Mon, 14 May 2012 02:36:18 GMT
    Location: https://9.9.9.9:8422/ibm/director/rest/VMControl/relocationPlans/8847669589
    Accept-Ranges: bytes
    Server: Noelios-Restlet-Engine/1.1.4
    Content-Language: en-US
    
    {"MessageID":"DNZEMW024I","MessageText":"DNZEMW024ICreated relocation plan
    	[/ibm/director/rest/VMControl/relocationPlans/8847669589]."}

Relocate multiple virtual servers

This example creates a relocation plan to relocate virtual servers 20519 and 25555 within the server system pool.

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

    Create a plan to relocate two virtual servers to different hosts in a server system pool:

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

    Listing 25. Sample request representation
    {
        "relocationPlan":{
            "virtualServer":[
                20519,
                25555
            ]
        }
    }
    Listing 26. Sample response representation
    HTTP/1.1 201 OK
    Cache-Control: no-store
    Set-Cookie: JSESSIONID_ibm_console_80=00007ID-HpF24AAYtRxUDiikVk4;Path=/; Secure; 
    									HTTPOnly
    Expires: Thu, 01 Dec 1994 16:00:00 GMT
    Content-Type: application/octet-stream; charset=UTF-8
    Content-Length: 190
    Date: Mon, 14 May 2012 02:38:18 GMT
    Location: https://9.9.9.9:8422/ibm/director/rest/VMControl/relocationPlans/8847669595
    Accept-Ranges: bytes
    Server: Noelios-Restlet-Engine/1.1.4
    Content-Language: en-US
    
    {"MessageID":"DNZEMW024I","MessageText":"DNZEMW024ICreated relocation plan
    	[/ibm/director/rest/VMControl/relocationPlans/8847669595]."}

Enter maintenance mode

The hostEvacuation property is used with the host property to remove all virtual servers from the specified host and put the host into the maintenance mode.

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

    Create a plan to relocate all virtual servers on a host and enter the host into the maintenance mode:

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

    Listing 27. Sample request representation
    {
        "relocationPlan":{
            "host":14085,
            "hostEvacuation":true
        }
    }
    Listing 28. Sample response representation
    HTTP/1.1 201 OK
    Cache-Control: no-store
    Set-Cookie: JSESSIONID_ibm_console_80=00007ID-HpF24AAYtRxUDiikVk4;Path=/; Secure; 
    									HTTPOnly
    Expires: Thu, 01 Dec 1994 16:00:00 GMT
    Content-Type: application/octet-stream; charset=UTF-8
    Content-Length: 190
    Date: Mon, 14 May 2012 02:39:11 GMT
    Location: https://9.9.9.9:8422/ibm/director/rest/VMControl/relocationPlans/8847669599
    Accept-Ranges: bytes
    Server: Noelios-Restlet-Engine/1.1.4
    Content-Language: en-US
    
    {"MessageID":"DNZEMW024I","MessageText":"DNZEMW024ICreated relocation plan
    	[/ibm/director/rest/VMControl/relocationPlans/8847669599]."}

Review a relocation plan

After requesting a relocation plan to be created, review the results. If the relocation plan is created successfully, then the state of the relocation plan will be stopped. If it has failed, the state will be aborted and will contain information on why the plan could not be created and recommendations on how to update your environment to make it work.

This example shows the successful path. The aborted path can be reviewed in the /relocationPlans/{relocationPlanID} resource page of the IBM Systems Director 6.3.x SDK information center.

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

    Retrieve details on relocation plan 8847669583:

    GET https://myserver:port/ibm/director/rest/VMControl/relocationPlans/8847669583

    Listing 29. Sample response representation
    {
        "state": {
            "label": "Stopped",
            "id": 5
        },
        "type": "virtualServer",
        "id": 8847669583,
        "operations": [
            {
                "toHost": "17475",
                "type": "relocateVE",
                "virtualServer": [
                    20518
                ],
                
            }
        ],
        "uri": "/ibm/director/rest/VMControl/relocationPlans/8847669583",
        "sourceOid": [
            20518
        ]
    }

Run a relocation plan

After creating a relocation plan, it must be ran. This is done by sending a PUT request and changing the state of the relocation plan to started (8).

The response contains two copies of the same URL. The URL in the location header and in the response message points to the job activation record for the run relocation plan task. The job activation record contains the status of the run relocation plan request, including percentage complete and any status or error messages.

  • URL
    • https://myserver:port/ibm/director/rest/VMControl/relocationPlans/8847669583
  • HTTP method
    • PUT
  • Sample request

    Create a plan to relocate the virtual server to the destination host with a unique ID of 14084:

    PUT https://myserver:port/ibm/director/rest/VMControl/relocationPlans/8847669583

    Listing 30. Sample request representation
    {
        "relocationPlan":{
            "state":8
        }
    }
    Listing 31. Sample response representation
    HTTP/1.1 201 OK
    Cache-Control: no-store
    Set-Cookie: JSESSIONID_ibm_console_80=00007ID-HpF24AAYtRxUDiikVk4;Path=/; Secure; 
    									HTTPOnly
    Expires: Thu, 01 Dec 1994 16:00:00 GMT
    Content-Type: application/octet-stream; charset=UTF-8
    Content-Length: 190
    Date: Mon, 14 May 2012 02:34:13 GMT
    Location: https://9.9.9.9:8422/ibm/director/rest/jobs/159/activations/1
    Accept-Ranges: bytes
    Server: Noelios-Restlet-Engine/1.1.4
    Content-Language: en-US
    
    {
      "MessageText": "DNZEMW027I New job activation for updating the relocation plan 
                      was started.\nRefer to the following URI for job activation 
                      status: /ibm/director/rest/jobs/159/activations/1",
      "MessageID": "DNZEMW027I"
    }

Monitor the create relocation plan job

The final step in relocating a virtual server is to monitor its progress to completion. The recommended method to monitor virtual server relocation is through the job activation record. As shown above, this URL is returned in response to 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.


Delete a server system pool

List server system pools

The first step in deleting a server system pool is to retrieve a list of available server system pools. From there, you can choose the server system pool that you need to delete.

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

    Get the list of all server system pools:

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

    Listing 32. Sample response representation
    {
        "systemPools":[{
                "state":{
                    "label":"Active",
                    "id":20
                },
                "status":{
                    "label":"Healthy",
                    "id":0
                },
                "type":"KVM",
                "oid":19362,
                "name":"systempool233",
                "uri":"/ibm/director/rest/VMControl/systemPools/19362"
            }
        ],
        "uri":"/ibm/director/rest/VMControl/systemPools"
    }

Delete a server system pool

The delete server system pool request deletes the server system pool, but does not delete any of its members. The member virtual servers are simply updated to state that they are no longer managed by a server system pool. Deleting a server system pool is an asynchronous operation.

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

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

    Delete the server system pool with a unique ID of 19362:

    DELETE https://myserver:port/ibm/director/rest/VMControl/systemPools/19362

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

Monitor the delete server system pool job

The final step in deleting a server system pool is to monitor its progress to completion. The recommended method to monitor server system pool deletion is through the job activation record. As shown above, this URL is returned in response to 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=856082
ArticleTitle=IBM Systems Director VMControl resource lifecycle management: part 4
publish-date=02042013