8.3.2 Example
In this example, the private cloud provider wants to configure approvals for the Instantiation of vApps by cloud consumers in their private clouds. When a user attempts to Instantiate a vApp from a template, vCloud Director sends a notification of the request to the appropriate AMQP exchange, and waits on acknowledgement and approval of the request before continuing.
The blocking task example
configuration shown in Figure 70 consists of the following components:
vCloud Director 5.1 cell (message producer).
AMQP 0.9
or later message bus (message queue).
AMQP client (message consumer).
REST client or vCloud SDK.
Figure 70. AMQP Blocking Task Architecture
The producer (vCloud Director) sends messages to the events queue. The client (consumer) receives messages from the queue. The client triggers the approval process. The result of the approval step (resume, abort, cancel) is submitted to vCloud Director for completion of the task within vCloud Director. At this point the task completes its processing or is terminated with the appropriate state.
There are several ways of defining the queue type based on the use case for the messages being delivered. Message queues can be defined as direct, topic, fan out, system or header.
For information on the exchange types and how to configure binding/routing of messages see
the RabbitMQ Tutorials (http://www.rabbitmq.com/getstarted.html).
8.3.2.1. Exchange Configuration
vCloud Director requires an AMQP 0.9 or later compatible message bus. This example uses Rabbit MQ as the message bus. Rabbit MQ provides a polyglot messaging infrastructure, with clients for all of the latest development languages as well as generic APIs like HTTP.
For detailed AMQP configuration with Rabbit MQ, see
Downloading and Installing RabbitMQ (
http://www.rabbitmq.com/download.html).
Table 36. RabbitMQ Server Exchange Configuration
Configuration Item | Value |
AMQP Host | 192.168.1.100 |
AMQP Port | 5672 |
Exchange | vcdExchange |
Exchange Type | topic |
Durability | durable |
Auto Delete | no |
Internal | no |
vHost | / |
Prefix | vcd |
8.3.2.2. RabbitMQ Queue Configuration
This example creates a queue bound to this exchange for the messages to be routed into.
Table 37. AMQP Queue Configuration
Configuration Item | Value |
Queue | notificationQueue |
Durability | Durable |
Auto Delete | No |
Exchange | vcdExchange |
Routing Key | # |
8.3.2.3. Exchange Routing
The AMQP broker uses routing as a way to filter vCloud Director notification messages and send them to the appropriate queue for multiple consumers. The vCloud Director routing key syntax is as follows:
<operationSuccess>.<entityUUID>.<orgUUID>.<userUUID>.<subType1>.<subType2>….<subtypeN>.taskName
For example, to route only VM create messages to a queue, the routing key would be as follows
true.#.com.vmware.vcloud.event.vm.create
vCloud Director sets sane routing keys in the messages that are generated. This example using the # (hash) routing key because this is a wildcard match on one or more segments of a routing key. This effectively routes all messages generated by vCloud Director of type vm.create to the notificationQueue. If you are interested in specific messages being routed to the appropriate queue, a non-wildcard or selective wildcard (*) routing key can be used.
Blocking tasks messages have similar identifier with the object being the blocking task. The blocking task references the following:
Its parent task – The suspended task referencing the object and the task parameters attributes it was
set with in the original request.
TaskOwner – The object on which the task operates.
The actions that can be taken on this blocking task (resume, abort,
fail, updateProgress).Receiving and acting upon on the blockings task is accomplished with the vCloud director API callbacks.System admin privileges are required to perform these operations.
8.3.2.4. vCloud Director Configuration
Under the System > Administration > Extensibility section of the admin user interface, enter the appropriate configuration details for your AMQP message bus.
8.3.2.5. Enable Blocking Tasks
Select the Blocking Tasks Tab, and from the folder tree, select the blocking tasks you want to enable. In this example, select the Instantiate vApp from Template option and click Apply, as shown in the following figure.
Figure 71. Enable a Task for Blocking in vCloud Director
8.3.2.6. Message Bus Configuration
Configure vCloud Director with the message bus settings so that it knows where to send event messages, and click Apply. This is a system task and must be done by a cloud system administrator.
Figure 72. vCloud Director AMQP Configuration
8.3.2.7. Blocking Message
The blocking message contains a reference to the task submitted so that the approver process can locate the task to interact with it.
<vmext:Link rel="entityResolver" href="https://192.168.1.44/api/entity/"/>
<vmext:EntityLink rel="entity" type="vcloud:blockingTask" name="vdcInstantiateVapp" id="urn:vcloud:blockingTask:9f4b1051-7c44-40e7-b0da-49e611b551be"/>
<vmext:EntityLink rel="down" type="vcloud:user" name="system" id="urn:vcloud:user:8b209f7f-052f-41e0-bba3-063aab1d7b04"/>
<vmext:EntityLink rel="up" type="vcloud:org" name="nuvemo" id="urn:vcloud:org:1f6de3ed-aad9-418e-95ef-ac93bcf2b774"/>
<vmext:EntityLink rel="task" type="vcloud:task" name="vdcInstantiateVapp" id="urn:vcloud:task:5f1a2884-fac0-4b3d-ae50-8cd8bd7090e7"/>
<vmext:EntityLink rel="task:owner" type="vcloud:vapp" id="urn:vcloud:vapp:f12509a8-71d1-4484-8062-b444c7aae6e2"/>
8.3.2.8. Approval Process Implementation
The approval process consists of sending a blocking message, performing the approval action such as sending an email or creating a webform, and based on the result of that action resume or fail the task that was blocked.
8.3.2.9. Deploying a vApp
When the vApp is initially deployed, because we have configured a blocking task for Instantiate vApp from Template, upon deployment the vApp enters into a Pending processing state.
Figure 73. vApp Pending Processing Status
8.3.2.10. Resuming a Blocked Task
Blocked tasks can be resumed either via the vCloud Director UI as a cloud provider administrator, or programmatically using the vCloud API.
8.3.2.11. Administrator Resume
In the System > Blocking Tasks window, the vCloud administrator has a list of blocking tasks and their statuses.
1. Right-click the task, or highlight the task and click the options icon, to give the administrator the options to resume, abort, or fail the blocked task.
2. Enter a reason for the status change to the blocked task.
3. After being resumed, the vApp continues deployment and will complete unless any additional blocked tasks relevant to other deployment steps halt the process.
8.3.2.12. vCloud API Resume
To use the API
1. Find the blocked task from the message with the entity resolver using the following command:
GET https://vcd51-01.corp.nuvemo.com/api/entity/urn:vcloud:blockingTask:9f4b1051-7c44-40e7-b0da-49e611b551be
The data returned is the blocking task entity:
<Entity xmlns="http://www.vmware.com/vcloud/v1.5" name="urn:vcloud:blockingTask:9f4b1051-7c44-40e7-b0da-49e611b551be" id="urn:vcloud:blockingTask:9f4b1051-7c44-40e7-b0da-49e611b551be" type="application/vnd.vmware.vcloud.entity+xml" href="https://vcd51-01.corp.nuvemo.com/api/entity/urn:vcloud:blockingTask:9f4b1051-7c44-40e7-b0da-49e611b551be" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.vmware.com/vcloud/v1.5 http://192.168.1.44/api/v1.5/schema/master.xsd">
<Link rel="alternate" type="application/vnd.vmware.admin.blockingTask+xml" href="https://vcd51-01.corp.nuvemo.com/api/admin/extension/blockingTask/9f4b1051-7c44-40e7-b0da-49e611b551be"/>
</Entity>
2. Get the blocking task from the resolved entity
This returns the blocking task and methods that can be performed against it:
HTTP/1.1 200 OK
Date: Tue, 03 Jul 2012 16:30:33 GMT
Date: Tue, 03 Jul 2012 16:30:33 GMT
Content-Type: application/vnd.vmware.admin.blockingtask+xml;version=1.5
Content-Length: 2428
<?xml version="1.0" encoding="UTF-8"?>
<vmext:BlockingTask xmlns:vmext="http://www.vmware.com/vcloud/extension/v1.5" xmlns:vcloud="http://www.vmware.com/vcloud/v1.5" status="active" timeoutDate="2012-07-08T09:06:33.757-07:00" timeoutAction="abort" createdTime="2012-07-03T09:06:33.757-07:00" name="vdcInstantiateVapp" id="urn:vcloud:blockingTask:9f4b1051-7c44-40e7-b0da-49e611b551be" type="application/vnd.vmware.admin.blockingTask+xml" href="https://vcd51-01.corp.nuvemo.com/api/admin/extension/blockingTask/9f4b1051-7c44-40e7-b0da-49e611b551be" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.vmware.com/vcloud/extension/v1.5 http://192.168.1.44/api/v1.5/schema/vmwextensions.xsd http://www.vmware.com/vcloud/v1.5 http://192.168.1.44/api/v1.5/schema/master.xsd">
<vcloud:Link rel="resume" type="application/vnd.vmware.admin.blockingTaskOperationParams+xml" href="https://vcd51-01.corp.nuvemo.com/api/admin/extension/blockingTask/9f4b1051-7c44-40e7-b0da-49e611b551be/action/resume"/>
<vcloud:Link rel="abort" type="application/vnd.vmware.admin.blockingTaskOperationParams+xml" href="https://vcd51-01.corp.nuvemo.com/api/admin/extension/blockingTask/9f4b1051-7c44-40e7-b0da-49e611b551be/action/abort"/>
<vcloud:Link rel="fail" type="application/vnd.vmware.admin.blockingTaskOperationParams+xml" href="https://vcd51-01.corp.nuvemo.com/api/admin/extension/blockingTask/9f4b1051-7c44-40e7-b0da-49e611b551be/action/fail"/>
<vcloud:Link rel="updateProgress" type="application/vnd.vmware.admin.blockingTaskUpdateProgressOperationParams+xml" href="https://vcd51-01.corp.nuvemo.com/api/admin/extension/blockingTask/9f4b1051-7c44-40e7-b0da-49e611b551be/action/updateProgress"/>
<vcloud:Link rel="up" type="application/vnd.vmware.vcloud.task+xml" href="https://vcd51-01.corp.nuvemo.com/api/task/5f1a2884-fac0-4b3d-ae50-8cd8bd7090e7"/>
<vcloud:Organization type="application/vnd.vmware.admin.organization+xml" name="nuvemo" href="https://vcd51-01.corp.nuvemo.com/api/admin/org/1f6de3ed-aad9-418e-95ef-ac93bcf2b774"/>
<vcloud:User type="application/vnd.vmware.admin.user+xml" name="system" href="https://vcd51-01.corp.nuvemo.com/api/admin/user/8b209f7f-052f-41e0-bba3-063aab1d7b04"/>
<vcloud:TaskOwner type="application/vnd.vmware.vcloud.vApp+xml" name="" href="https://vcd51-01.corp.nuvemo.com/api/vApp/vapp-f12509a8-71d1-4484-8062-b444c7aae6e2"/>
</vmext:BlockingTask>
3. Resume the blocked task
POST https://vcd51-01.corp.nuvemo.com/api/admin/extension/blockingTask/9f4b1051-7c44-40e7-b0da-49e611b551be/action/resume
Content-Type: application/vnd.vmware.admin.blockingTaskOperationParams+xml
Pass in this content as the post to the resume request:
<?xml version=”1.0” encoding=”UTF-8”?>
<BlockingTaskOperationParams
xmlns=http://www.vmware.com/vcloud/extension/v1.5
<Message>Approved task. </Message>
</BlockingTaskOperationParams>
8.3.2.13. Failed/Aborted Task
The end user (tenant) is notified through the vCloud Director UI that the deployment has failed or has been aborted. Click into the details of the failure message to find the provider entered reason for failing, which is presented in the details.
Failing or aborting tasks is carried out in the same manner via the vCloud API as a resume task. Looking at the XML returned when performing a GET on the blocking task, methods are returned for Resume, Abort, and Fail, as follows:
<vcloud:Link rel="abort" type="application/vnd.vmware.admin.blockingTaskOperationParams+xml" href="https://vcd51-01.corp.nuvemo.com/api/admin/extension/blockingTask/9f4b1051-7c44-40e7-b0da-49e611b551be/action/abort"/>
You can fail or abort a task as part of a provisioning process that requires an external approval to complete. If you have a provisioning portal or workflow executing the task of deploying and approving vApps, when an approval is declined, the portal fails the blocked task with an appropriate message to the user. If a user submits a deploy request for a vApp, and then decides to cancel the deployment prior to the approval, the portal can issue an abort on the blocking task with the appropriate message. An abort and fail both result in a termination of the vApp deployment, however contextually they are different.
