Monday, September 24, 2012

vCloud Director API Extensions Part 1 of 3 - vCloud Director

Introduction

API Extensions is a new feature in vCloud Director 5.1 that provide incredible flexibility in building feature rich clouds.  In addition to telling you why you should be interested in this feature, this post will give you the details behind a complete example solution that provides availability as a service using VCO to enable and disable VMware Fault Tolerance on a vApp using API Calls against vCloud Director.  For those of you familiar with vCloud Director you are probably scratching your head right now. . . Thats right I said making an API call against a vApp object in vCloud Director that will iterate through all the Virtual Machines in the vApp and enable Fault Tolerance on those vApps.

DISCLAIMER #1 - This post is for illustrative purposes only and Fault Tolerance is not currently supported in a vCloud Director environment.

Why use API Extensions ?

API Extensions provide the capability to move from providing Cloud "products" to providing truly integrated cross-product "Cloud Services".  That may sound like a marketing claim but hopefully when you are finished reading this series of posts you will agree.
  • Next logical question - Why would you want or need to expose these features by going through vCloud Director ? 
  • Answer - By exposing these services in vCloud Director you can take advantage of object correlation, localization, and the authentication services that vCloud Director provides.

What are API Extensions ?

API Extensions provide an integrated way for a user or program to communicate through the vCloud Director API to an external system to accomplish a task.   vCloud Director exposes a URI for the Extension and associates that URI with all appropriate objects while handling authorization, authentication, localization etc.  The Extension is defined via an XML definition and created through an API call to vCloud Director.  Once registered,  the API Extension calls and responses are communicated between vCloud Director and the external system using AMQP messages.  The external system that actually provides the service just needs to be able to:
  1. Publish AMQP messages for replies to vCloud Director on the status of the Extensions call.
  2. Subscribe to an AMQP queue and process  or deserialize AMQP message body.
  3. Expose an API that can be used to control the external system and do the work of your service.
For the example used in this Post the following components were used.
  • vSphere 5.1 
    • vCenter 5.1 - Virtual Appliance
    • ESXi 5.1
  • vCloud Director 5.1 - Virtual AppliancevCenter Orchestrator 5.1 - Virtual Appliance
    • vCloud Director 5.1 Plug-in
    • AMQP Plug-in 5.1
    • vCenter 5.1 Plug-in (Built-in)
  • AMQP Server RabbitMQ 2.8.4 binariesrabbitmq_management plugin

 How to configure the solution ?

There are three high level steps to configure a complete solution to use vCloud Director API Extensions. Chris Knowles (@sugeknowles) already wrote an excellent series which describes Step 1. Registering the Extension Service and Service Links in vCloud Director in great detail,   so I will only cover this briefly to provide the specific XML used for this example.  In two subsequent posts, I will jump into the details for Step 2 and Step 3 which are configuring AMQP and creating the Extension itself using VCO. The high level steps to build this example are:
  1. vCloud Director - Create and register the Extension Service in vCloud Director 
    1.  Create XML definition for your Extension Service
    2.  Register the extension through the vCloud API using Curl or Rest Client
    3.  Register Extension Service Links for the service
    4.  Configure the AMQP server to be used in the vCloud Director GUI
  1. AMQP - Install and Configure the AMQP Server 
    1. Create the AMQP Exchange
    2. Create the AMQP Queue
    3. Configure the binding from the Exchange to the Queueu using a Routing Key
  2. VCO - Create the Extension(workflow) itself
    1. Create a subscription and processing logic for the AMQP queueCreate the work engine (What your Extension actually does)
      1. Will take the calls from the AMQP bus and do something ! ! !
      2. In this case I used vCenter Orchestrator
    2. Create the API Extension call response logic

vCloud Director - Create the Extension Service and Service Links in vCloud Director

1. Create the Extension Service

Chris Knowles (@sugeknowles) wrote an excellent series of posts on API Extensions including several one actually Registering an API Extension Service and Service Links in vCloud Director   You can use these posts to see the Rest syntax to be used for your curl or Rest Client calls. Below is the XML used for this example to create the Fault Tolerance as a Service Extension in vCloud Director.  You can copy paste this into a Rest Client of if using CURL save the file with a .xml extension.

<vmext:Service xmlns:vmext="http://www.vmware.com/vcloud/extension/v1.5" xmlns:vcloud="http://www.vmware.com/vcloud/v1.5"   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.vmware.com/vcloud/extension/v1.5 http://10.23.6.103/api/v1.5/schema/vmwextensions.xsd http://www.vmware.com/vcloud/v1.5 http://10.23.6.103/api/v1.5/schema/master.xsd" name="FaultTolerance" type="application/vnd.vmware.admin.service+xml" operationKey="FaultTolerance">
  <vmext:Namespace>FaultTolerance</vmext:Namespace>
  <vmext:Enabled>true</vmext:Enabled>
  <vmext:RoutingKey>faulttolerance</vmext:RoutingKey>
  <vmext:Priority>10</vmext:Priority>
  <vmext:Exchange>availability</vmext:Exchange>
  <vmext:ApiFilters>
    <vmext:ApiFilter>
      <vmext:UrlPattern>/api/vApp/.*/ft/.*</vmext:UrlPattern>
    </vmext:ApiFilter>
  </vmext:ApiFilters>
</vmext:Service>


2. Create the Service Links

While you now have an Extension Service registered that you can issue API calls to, without the service links you will not see the Rest URI for your API call as a property of an object in vCloud Director when you perform a REST get call against that object. In order to have the fton or ftoff listed as  available methods for the vApp object in vCloud Director we need to Create the API Service Links. Chris also has a very detailed post on Registering API Service Links and how to use the REST Client. Here is the XML  that was used to create the Service Links needed for our Fault Tolerance example. You can copy paste this into a Rest Client of if using CURL save the file with a .xml extension.

<?xml version="1.0" encoding="UTF-8"?>
<vmext:Service xmlns:vmext="http://www.vmware.com/vcloud/extension/v1.5" xmlns:vcloud="http://www.vmware.com/vcloud/v1.5"   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.vmware.com/vcloud/extension/v1.5 http://10.23.6.103/api/v1.5/schema/vmwextensions.xsd http://www.vmware.com/vcloud/v1.5 http://10.23.6.103/api/v1.5/schema/master.xsd" name="FaultTolerance" type="application/vnd.vmware.admin.service+xml" operationKey="FaultToleranceExtension">
    <vmext:Namespace>FaultTolerance</vmext:Namespace>
    <vmext:Enabled>true</vmext:Enabled>
    <vmext:RoutingKey>faulttolerance</vmext:RoutingKey>
    <vmext:Priority>10</vmext:Priority>
    <vmext:Exchange>availability</vmext:Exchange>
    <vmext:ServiceLinks>

        <vmext:ServiceLink>
            <vmext:LinkHref>{baseUri}vApp/vapp-{resourceId}/ft/on</vmext:LinkHref>
            <vmext:MimeType>application/xml</vmext:MimeType>
            <vmext:Rel>fton</vmext:Rel>
            <vmext:ResourceType>application/vnd.vmware.vcloud.vApp+xml</vmext:ResourceType>
        </vmext:ServiceLink>       
       
        <vmext:ServiceLink>
            <vmext:LinkHref>{baseUri}vApp/vapp-{resourceId}/ft/off</vmext:LinkHref>
            <vmext:MimeType>application/xml</vmext:MimeType>
            <vmext:Rel>ftoff</vmext:Rel>
            <vmext:ResourceType>application/vnd.vmware.vcloud.vApp+xml</vmext:ResourceType>
        </vmext:ServiceLink>               
               
    </vmext:ServiceLinks>   
</vmext:Service>



  3. Configure vCloud Director for the AMQP server

In the previous steps we configured the AMQP Exchange and Routing Key but we still have not told vCloud Director the hostname / IP address or credentials of an AMQP system.  This step is done from the vCloud Director GUI from the system context.


We now have an Extension Service created and two service links (fton and ftoff) registered for every vApp in our Cloud.  Any time this URI is called for this method (POST or GET) an AMQP message will be sent to the availability exchange with "faulttolerance" in the routing key. We now need a transport mechanism (AMQP) to move these messages to the external system, in our case VCO, that will be doing the work.  See my Part 2 of this series post on how to setup and configure AMQP to pass your API calls to the appropriate AMQP Queue.

No comments:

Post a Comment