![Close [x]](http://dw1.s81c.com/i/c.gif){kind=small}
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.
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 representationHTTP/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 representationHTTP/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 representationHTTP/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 representationHTTP/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]."}
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 representationHTTP/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]."}
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 ] }
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 representationHTTP/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.
