| <?xml version='1.0' encoding='utf-8' ?> |
| <!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ |
| <!ENTITY % BOOK_ENTITIES SYSTEM "cloudstack.ent"> |
| %BOOK_ENTITIES; |
| ]> |
| |
| <!-- Licensed to the Apache Software Foundation (ASF) under one |
| or more contributor license agreements. See the NOTICE file |
| distributed with this work for additional information |
| regarding copyright ownership. The ASF licenses this file |
| to you under the Apache License, Version 2.0 (the |
| "License"); you may not use this file except in compliance |
| with the License. You may obtain a copy of the License at |
| http://www.apache.org/licenses/LICENSE-2.0 |
| Unless required by applicable law or agreed to in writing, |
| software distributed under the License is distributed on an |
| "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| KIND, either express or implied. See the License for the |
| specific language governing permissions and limitations |
| under the License. |
| --> |
| <section id="event-framework"> |
| <title>Event Notification</title> |
| <para>Event notification framework provides a means for the Management Server components to |
| publish and subscribe to &PRODUCT; events. Event notification is achieved by implementing the |
| concept of event bus abstraction in the Management Server. An event bus is introduced in the |
| Management Server that allows the &PRODUCT; components and extension plug-ins to subscribe to the |
| events by using the Advanced Message Queuing Protocol (AMQP) client. In &PRODUCT;, a default |
| implementation of event bus is provided as a plug-in that uses the RabbitMQ AMQP client. The |
| AMQP client pushes the published events to a compatible AMQP server. Therefore all the &PRODUCT; |
| events are published to an exchange in the AMQP server. </para> |
| <para>A new event for state change, resource state change, is introduced as part of Event |
| notification framework. Every resource, such as user VM, volume, NIC, network, public IP, |
| snapshot, and template, is associated with a state machine and generates events as part of the |
| state change. That implies that a change in the state of a resource results in a state change |
| event, and the event is published in the corresponding state machine on the event bus. All the |
| &PRODUCT; events (alerts, action events, usage events) and the additional category of resource |
| state change events, are published on to the events bus.</para> |
| <formalpara> |
| <title>Use Cases</title> |
| <para>The following are some of the use cases:</para> |
| </formalpara> |
| <itemizedlist> |
| <listitem> |
| <para>Usage or Billing Engines: A third-party cloud usage solution can implement a plug-in |
| that can connects to &PRODUCT; to subscribe to &PRODUCT; events and generate usage data. The |
| usage data is consumed by their usage software.</para> |
| </listitem> |
| <listitem> |
| <para>AMQP plug-in can place all the events on the a message queue, then a AMQP message broker |
| can provide topic-based notification to the subscribers.</para> |
| </listitem> |
| <listitem> |
| <para>Publish and Subscribe notification service can be implemented as a pluggable service in |
| &PRODUCT; that can provide rich set of APIs for event notification, such as topics-based |
| subscription and notification. Additionally, the pluggable service can deal with |
| multi-tenancy, authentication, and authorization issues.</para> |
| </listitem> |
| </itemizedlist> |
| <formalpara> |
| <title>Configuration</title> |
| <para>As a &PRODUCT; administrator, perform the following one-time configuration to enable event |
| notification framework. At run time no changes can control the behaviour.</para> |
| </formalpara> |
| <orderedlist> |
| <listitem> |
| <para>Open <filename>'componentContext.xml</filename>.</para> |
| </listitem> |
| <listitem> |
| <para>Define a bean named <filename>eventNotificationBus</filename> as follows:</para> |
| <itemizedlist> |
| <listitem> |
| <para>name : Specify a name for the bean.</para> |
| </listitem> |
| <listitem> |
| <para>server : The name or the IP address of the RabbitMQ AMQP server.</para> |
| </listitem> |
| <listitem> |
| <para>port : The port on which RabbitMQ server is running.</para> |
| </listitem> |
| <listitem> |
| <para>username : The username associated with the account to access the RabbitMQ |
| server.</para> |
| </listitem> |
| <listitem> |
| <para>password : The password associated with the username of the account to access the |
| RabbitMQ server.</para> |
| </listitem> |
| <listitem> |
| <para>exchange : The exchange name on the RabbitMQ server where &PRODUCT; events are |
| published.</para> |
| <para>A sample bean is given below:</para> |
| <programlisting><bean id="eventNotificationBus" class="org.apache.cloudstack.mom.rabbitmq.RabbitMQEventBus"> |
| <property name="name" value="eventNotificationBus"/> |
| <property name="server" value="127.0.0.1"/> |
| <property name="port" value="5672"/> |
| <property name="username" value="guest"/> |
| <property name="password" value="guest"/> |
| <property name="exchange" value="cloudstack-events"/> |
| </bean></programlisting> |
| <para>The <filename>eventNotificationBus</filename> bean represents the |
| <filename>org.apache.cloudstack.mom.rabbitmq.RabbitMQEventBus</filename> class.</para> |
| </listitem> |
| </itemizedlist> |
| </listitem> |
| <listitem> |
| <para>Restart the Management Server.</para> |
| </listitem> |
| </orderedlist> |
| </section> |