8. vCloud Integration Examples : 8.2 AMQP Messages : 8.2.2 Example
8.2.2 Example
The Enterprise vCloud administrator wants to collect all events generated by vCloud Director to store them for searching later to support troubleshooting or audit activities within the environment.
A non-blocking messages or notifications configuration consists of the following components:
*vCloud Director cell (message producer).
*AMQP 0.9 or later message bus (message queue).
*AMQP client (message consumer).
Figure 69. Non-Blocking Messages or Notifications Configuration
The producer (vCloud Director) sends messages to the events queue. The client (consumer) receives messages from the queue.
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). AMQP Server Exchange Configuration
For detailed AMQP configuration with Rabbit MQ, see Downloading and Installing RabbitMQ (http://www.rabbitmq.com/download.html).
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.
Table 34. RabbitMQ Server Exchange Configuration
Configuration Item
Exchange Type
Auto Delete
vcd AMQP Server Queue Configuration
This example creates a queue bound to this exchange for the messages to be routed into.
Table 35. RabbitMQ Server Queue Configuration
Configuration Item
Auto Delete
Routing Key
# 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. For example, a public vCloud provider can filter messages based on organization and send each customers notifications to a separate queue for isolation of logging information. The vCloud Director routing key syntax is as follows:
For example, to route only VM create messages to a queue, the routing key would be:
vCloud Director sets sane routing keys in the messages that are generated. This example uses 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 a 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. vCloud Director Configuration
To configure vCloud Director
1. Under the System > Administration > Extensibility section of the admin user interface, enter the appropriate configuration details for your AMQP message bus.
2. Select Enable Notifications.
3. Configure vCloud Director with the message bus settings so that it knows where to send event messages. This is a system task and must be done by a vCloud provider administrator user.
4. Click Apply.
vCloud Director begins to send non-blocking notification events to the configured exchange. Regardless of whether the notification message is delivered successfully or acknowledged, the task within vCloud Director that generated the message continues uninterrupted. AMQP Client Configuration
Because AMQP messaging is a polyglot messaging system, the client configuration is implementation specific. Several options exist for consuming the AMQP Exchange for non-blocking messages including using the AMQP plug-in for vCenter Orchestrator or the vCloud Director API. When consuming messages, if your queue is not configured for auto-delete, you must acknowledge the messages sent to the queue when consuming them. The payload of the message is an XML document as a UTF-8 encoded string.
The following simple (Java) example loops over a queue, waiting on the delivery of the next message. ackMessage is a Boolean variable setting whether to acknowledge the message when it is retrieved from the queue.
This example performs the basic steps to acknowledge and process the AMQP messages to obtain the Message Headers and Message Body from a single Message Queue and set the Message Body to a String for subsequent processing. Additional logic could be used to take action based on the Message Header or Message Body.