Appendix E: Integrating with Existing Enterprise System Management : vCloud Director Notifications and Blocking Tasks Messages : Extension
   
Extension
An extension is a script or an application with the following capabilities:
*Subscribe to an AMQP queue for receiving new messages.
*Triage the received messages.
*Process messages into operations (internal or external calls).
*Call vCloud Director API back for getting more information on the objects involved in an operation and taking action on blocked task.
Subscribe to an AMQP Queue
Subscribing to queues involves declaring a queue, binding with a routing key, and then subscribing to the declared queue.
The queue routing key supports the “*” and “#” wildcard characters to match a single segment and zero or more segments. For example true.*.*.*. com.vmware.vcloud.event.vm.create or true.#.com.vmware.vcloud.event.vm.create routes a notification to the queue with this binding key every time any user from any organization successfully creates a virtual machine).
Declaring asserts the existence of the object. If the object does not exist, declaring it creates it.
Triage the Consumed Messages
When a message is consumed, the extension can use the message header that contains all the routing components to further filter and act upon. For example, some notifications may be ignored.
Separate the notifications messages from the blocking tasks because the blocking tasks must be handled differently.
Handling the Notification Messages
The notification messages contain the operation triggering the event, the object type, and identifiers and names for organization, user, and object.
These can be used as markers for applications such as audit logging, Change Management, and Incident Management. If the application cannot correlate the IDs to present the objects properties in a user-consumable form, the extension application has to call back the vCloud API to extract these.
Use notification messages to start an operation that must follow another one. For example, enabling the public IPs of a vApp in a load balancer.
Handling Blocking Tasks Messages
Blocking tasks messages have similar identifiers with the object being the blocking task. The blocking task references include 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.
Aborting a task returns a success status. It should be done only under the following conditions:
*If the requested vApp went through automatic approval logic and was disapproved.
*To replace an operation to be carried out by another one, for example, to start a pre-provisioned vApp instead of provisioning a vApp.
*When it is required that parameters for a requested task be replaced, for example, when determining a specific virtual datacenter for a vApp based on placement logic.
*When calling the same operation as the one that triggered, the notification routing and filtering must be properly configured to avoid creating a loop.
A task should be failed when the operation occurring before the task is determined to fail. An example is when an operation required before running the task failed. For example, CMDB was not reachable.
The task must be resumed for operations that must complete before the next task starts. Examples include the following:
*OVF user information must be added to a vApp before adding a vApp to catalog.
*Requested vApp goes through automatic approval logic and was approved before being added to vCloud.
*Change request must record the object state in CMDB system before making change.
Task progress should be updated to avoid having the task time out, or to log a status message to the user.
Blocking Tasks and Notifications Use Cases
This section covers the messages published during the use case: App Author adds a vApp from catalog. Notifications and blocking task for “Instantiate vApp from vApp Template” are enabled.
*Notification message: vApp creation requested. (true.#.com.vmware.vcloud.event.vapp.create_request - # is used as a placeholder)
*Notification message: VM creation requested a scaffold object is created and resources are locked (true.#.com.vmware.vcloud.event.vm.create_request)
*Notification message: A task to instantiate a vApp is created. (true.#.com.vmware.vcloud.event.task.create.vdcInstantiateVapp)
*Blocking tasks message: vApp instantiation has been blocked. (true.#.com.vmware.vcloud.event.blockingtask.create.vdcInstantiateVapp)
*vCloud Director User Interface shows the task as “Pending processing …”
Case 1: System admin calls abort on the blocked task.
*Blocking tasks message: The blocking task has been aborted. (true.#.com.vmware.vcloud.event.blockingtask.abort.vdcInstantiateVapp)
*Notification message: The vApp is modified as per the next operation. (true.#.com.vmware.vcloud.event.vapp.modify)
*Notification message: The scaffold object is deleted. Resources are unlocked. (true.#.com.vmware.vcloud.event.vm.delete)
*Notification message: The vApp instantiation is aborted. (true.#.com.vmware.vcloud.event.task.abort.vdcInstantiateVapp)
*The newly created object is no longer displayed from vCloud Director user interface. The task can be seen in Logs/Tasks.
Case 2: System admin fails the blocked task.
*Blocking tasks message: The blocking task has been failed. (true.#.com.vmware.vcloud.event.blockingtask.fail.vdcInstantiateVapp)
*Notification message: The VM is not created (false.#.com.vmware.vcloud.event.vm.create)
*Notification message: The vApp instantiation task has been failed (true.#.com.vmware.vcloud.event.task.fail.vdcInstantiateVapp)
*vCloud Director User Interface shows the task is having an error on object grid and in Logs/Tasks.
Case 3: System admin resumes the task.
*Blocking tasks message: The blocking task has been resumed. (true.#.com.vmware.vcloud.event.blockingtask.resume.vdcInstantiateVapp)
*Notification message: The vApp is instantiated. (true.#.com.vmware.vcloud.event.task.start.vdcInstantiateVapp)
*Notification message: The vApp is created. (true.#.com.vmware.vcloud.event.vapp.create)
*Notification message: The VM is created. (true.#.com.vmware.vcloud.event.vm.create)
Case 3a: The vApp instantiation is successful or aborted. (true.#.com.vmware.vcloud.event.task.complete.vdcInstantiateVapp)
Case 3b: The vApp instantiation fails. (false.#.com.vmware.vcloud.event.task.complete.vdcInstantiateVapp)
Using vCenter Orchestrator as a vCloud Director Extension
VMware vCenter Orchestrator fully supports consumption of blocked tasks and notifications messages, callbacks, and calls to external systems via the vCloud Director, AMQP, and other product plug-ins.
Figure 35. vCenter Orchestrator as a vCloud Director Extension
Screen shot 2011-07-19 at 11.09.00 AM.png
The AMQP plug-ins comes with workflows, and requires a one-time setup.
1. Add a brokerAdd an AMQP broker with providing hostname and credentials.
2. Declare an exchangeDeclare an exchange for the configured broker.
3. Declare a queueDeclare a queue.
4. Bind – Bind a queue to an exchange by providing a routing key.
5. Subscribe to queues – Enables message updates on new messages.
This configuration is saved and reloaded automatically when the vCenter Orchestrator server is restarted.
The plug-in supports adding a policy element of type subscription having an OnMessage trigger event. A policy can be set up to start a workflow that processes new messages.
Workflows are provided to triage and process the message to output vCloud Director objects. These can provide all of the information necessary for audit purposes and for designing custom logic before calling external systems. External systems are called using specific vCenter Orchestrator plug-in adapters such as vCloud Director, vCenter, Update Manager, Active Directory or generic plug-ins adapters such as REST, SOAP, XML, SSH, and JDBC. Blocked tasks objects can then be aborted, resumed, or failed by calling vCloud Director Workflows.
vCenter Orchestrator as an Extension Example
This section shows a simple example leveraging the blocked tasks as a trigger mechanism for starting extension workflows using different vCenter Orchestrator plug-ins.
As a prerequisite, a subscription to an AMQP queue, bound to the exchange used by vCloud director, was created using the workflows listed in the previous section. As part of this, the routing key is set to filter on vApp creation (#.blockingtask.create.vdcInstantiateVapp).
Next an Approve new vApp policy is created to listen on new messages. It is set to start the Approve a vApp workflow.
The Approve a vApp workflow is designed as shown in the following table.
Table 18. Approve a vApp Workflow
Workflow
Description
Plug-in in use
Important information is extracted from the subscription message such as the name of the vApp requester and the scaffold object of the vApp being requested.
AMQP
The detailed properties of the requested vApp are gathered.
vCloud Director
The vApp requester’s manager name and email is found in Active Directory, an email is sent to approve the vApp. It contains all the details gathered before.
Active Directory and mail
The workflow is stopped until the approver follows the link in his email, authenticates using his Active Directory credential, and approves or rejects the vApp.
 
Depending on if the vApp was approved or not, the aborted task is resumed or aborted. An email message is sent to the requester.
vCloud Director and mail