diff --git a/docs/en-US/event-framework.xml b/docs/en-US/event-framework.xml new file mode 100644 index 00000000000..88c45c9033d --- /dev/null +++ b/docs/en-US/event-framework.xml @@ -0,0 +1,110 @@ + + +%BOOK_ENTITIES; +]> + + +
+ Event Notification + 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. + 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. + + Use Cases + The following are some of the use cases: + + + + 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. + + + 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. + + + 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. + + + + Configuration + As a &PRODUCT; administrator, perform the following one-time configuration to enable event + notification framework. At run time no changes can control the behaviour. + + + + Open 'componentContext.xml. + + + Define a bean named eventNotificationBus as follows: + + + name : Specify a name for the bean. + + + server : The name or the IP address of the RabbitMQ AMQP server. + + + port : The port on which RabbitMQ server is running. + + + username : The username associated with the account to access the RabbitMQ + server. + + + password : The password associated with the username of the account to access the + RabbitMQ server. + + + exchange : The exchange name on the RabbitMQ server where &PRODUCT; events are + published. + A sample bean is given below: + <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> + The eventNotificationBus bean represents the + org.apache.cloudstack.mom.rabbitmq.RabbitMQEventBus class. + + + + + Restart the Management Server. + + +
diff --git a/docs/en-US/events.xml b/docs/en-US/events.xml index 242ff4511ff..49ef86e62b5 100644 --- a/docs/en-US/events.xml +++ b/docs/en-US/events.xml @@ -21,11 +21,17 @@ specific language governing permissions and limitations under the License. --> -
- Events - - - - + Events + An event is essentially a significant or meaningful change in the state of both virtual and + physical resources associated with a cloud environment. Events are used by monitoring systems, + usage and billing systems, or any other event-driven workflow systems to discern a pattern and + make the right business decision. In &PRODUCT; an event could be a state change of virtual or + psychical resources, an action performed by an user (action events), or policy based events + (alerts). + + + + +