Abiquo 2.6


Skip to end of metadata
Go to start of metadata

Description

The Abiquo Outbound API is an event streaming feature that is part of the Abiquo M module.

Configure Abiquo Events 

Configure M

If you do not configure M properly, no events will be available in Abiquo. You will probably need to configure the M properties in the abiquo.properties file on the server where M will run. By default, M runs on the Abiquo Server. The required properties are the M user account details and the API location.

In Abiquo 2.6, there is a new module called M. This module listens for events in the Abiquo API. When it receives events, it performs requests to the Abiquo API to retrieve further details about the events. Then it writes the events to the Abiquo database and broadcasts them as the event stream of the Outbound API.

Automatic M User Account Configuration

When you install or upgrade Abiquo 2.6, it is essential to check that the M module is properly configured to ensure that your platform will record events.

  1. Fresh install of 2.6 + customer enters cloud admin password in install screens
    1. Abiquo automatically configures M is automatically configured with the admin password
    2. M user and password are NOT included in properties file
    3. If the customer changes the admin account, they must reconfigure M with user and/or password in the abiquo.properties file as described below
  2. Fresh install of 2.6 + customer does NOT enter cloud admin password in install screens
    1. Abiquo automatically configures M with the default admin account (user admin, password xabiquo)
    2. When the customer changes the admin account, they must configure M with user and/or password in the abiquo.properties file as described below
  3. Upgrade from 2.4.x to 2.6.x
    1. Abiquo automatically configures M with the default cloud admin account (user admin, password xabiquo)
    2. The customer must configure M with user and password in the abiquo.properties file as described below

Configure M Properties

You must configure the abiquo.properties file on the server where M will run. Without this configuration, no events will be available in Abiquo

  1. Abiquo M User
    • M will use this identity and credential to access the Abiquo API and retrieve information about the events
    • It will record the events in the Abiquo database and stream them through the Outbound API
    • When you modify the default cloud admin user, the hidden default values of admin and xabiquo will not function
    • This user must have permission to access all events. See the privileges defined for the Outbound API role in Privileges

  2. Abiquo API Location with Port
    • The API location must be an externally accessible IP and port
    • Use the API port to ensure that an event streaming user with a regular user role can access events
    • The API location IP address cannot be a localhost value (127.0.0.1 or localhost)
    • The Abiquo API location is also used for the Chef integration, so remember this if you have distributed platform components

Example of Manual M Configuration

Abiquo M Configuration
abiquo.m.identity = AbiquoMUser 
abiquo.m.credential = AbiquoMPassword
abiquo.server.api.location = http://my.api.location:80/api

Outbound API

The Abiquo Outbound API aims to help third-party software providers to develop software for integration with the Abiquo platform. It allows customers to drive external systems or processes based on activity on the Abiquo platform. For example you may want to be notified when a new VM is deployed so that an asset management register can be updated. Users can subscribe to a specific event, a set of events, or all events. Users will need to have access to the Abiquo API and privileges to access events. Abiquo customers and final cloud customers can subscribe to the events they have permission to access. As part of the development, we have reviewed each event and improved the information supplied as well as the event format in order to facilitate integration.

Specifications

  • Improved EVENT_TYPES are now limited to three clear categories:
    • INFO
    • WARNING
    • ERROR
  • Event scope allows you to filter by error type, etc:
    • Platform error
    • DC error
    • VDC error
  • Events published with Atmosphere streaming. See also https://github.com/Atmosphere/atmosphere/wiki
  • Extension to tracers to offer more information and to facilitate integration
  • Different integration examples will be provided in major programming languages

 

The following diagram shows the basic architecture of the Outbound API.

Consuming the streaming API

The streaming API can be used to subscribe to a set of Events, so you can receive all events that interest you in "real time".

The following example shows a subscription request using Server-Side Events as the streaming transport. The subscription does not specify any filter, so by default all Events will be received in "real time".

Note that there are also specific Atmosphere query parameters in the request. Please see the Atmosphere documentation for a complete reference of all available parameters used to configure the streaming connection.

Streaming API example
curl -u <user>:<password> -X GET "http://localhost/m/stream?X-Atmosphere-tracking-id=e24de98c-6624-c552-5572-6edbffd270e3&X-Atmosphere-Framework=1.0&X-Atmosphere-Transport=sse&X-Cache-Date=134183423411"

data:{"timestamp":"1370255429105","user":"/admin/enterprises/1/users/1","enterprise":"/admin/enterprises/1","severity":"INFO","source":"ABIQUO_SERVER","action":"CREATE","type":"DATACENTER","entityIdentifier":"/admin/datacenters/2","details":null}
data:{"timestamp":"1370255429435","user":"/admin/enterprises/1/users/1","enterprise":"/admin/enterprises/1","severity":"INFO","source":"ABIQUO_SERVER","action":"REMOTE_SERVICES_CREATE","type":"DATACENTER","entityIdentifier":"","details":null}
data:{"timestamp":"1370255429150","user":"/admin/enterprises/1/users/1","enterprise":"/admin/enterprises/1","severity":"INFO","source":"ABIQUO_SERVER","action":"CREATE","type":"REMOTE_SERVICE","entityIdentifier":"/admin/datacenters/2/remoteservices/VIRTUALFACTORY","details":null}
data:{"timestamp":"1370255429251","user":"/admin/enterprises/1/users/1","enterprise":"/admin/enterprises/1","severity":"INFO","source":"ABIQUO_SERVER","action":"CREATE","type":"REMOTE_SERVICE","entityIdentifier":"/admin/datacenters/2/remoteservices/VIRTUALSYSTEMMONITOR","details":null}
data:{"timestamp":"1370255429363","user":"/admin/enterprises/1/users/1","enterprise":"/admin/enterprises/1","severity":"INFO","source":"ABIQUO_SERVER","action":"CREATE","type":"REMOTE_SERVICE","entityIdentifier":"/admin/datacenters/2/remoteservices/APPLIANCEMANAGER","details":null}
data:{"timestamp":"1370255429386","user":"/admin/enterprises/1/users/1","enterprise":"/admin/enterprises/1","severity":"INFO","source":"ABIQUO_SERVER","action":"CREATE","type":"REMOTE_SERVICE","entityIdentifier":"/admin/datacenters/2/remoteservices/NODECOLLECTOR","details":null}
data:{"timestamp":"1370255429399","user":"/admin/enterprises/1/users/1","enterprise":"/admin/enterprises/1","severity":"INFO","source":"ABIQUO_SERVER","action":"CREATE","type":"REMOTE_SERVICE","entityIdentifier":"/admin/datacenters/2/remoteservices/STORAGESYSTEMMONITOR","details":null}
data:{"timestamp":"1370255429409","user":"/admin/enterprises/1/users/1","enterprise":"/admin/enterprises/1","severity":"INFO","source":"ABIQUO_SERVER","action":"CREATE","type":"REMOTE_SERVICE","entityIdentifier":"/admin/datacenters/2/remoteservices/DHCPSERVICE","details":null}
data:{"timestamp":"1370255429432","user":"/admin/enterprises/1/users/1","enterprise":"/admin/enterprises/1","severity":"INFO","source":"ABIQUO_SERVER","action":"CREATE","type":"REMOTE_SERVICE","entityIdentifier":"/admin/datacenters/2/remoteservices/BPMSERVICE","details":null}

During the subscription, a datacenter was created and the remote services were configured, and all events were received in real-time on the client side.

More fine-grained subscriptions can be made, in order to receive in real-time only the events you are interested in. The following query parameters are available:

NameDescriptionExample values
severityThe severity of the eventsINFO, WARN, ERROR
entityThe entity that originated the eventDATACENTER, RACK, VIRTUAL_MACHINE, etc.
actionThe action performed on the "entity"CREATE, DEPLOY, DELETE, etc.
userThe "id" of the user who generated the event1, 2, 25, system, etc.
enterpriseThe "id" of the enterprise generating the event

1, 2, 25, etc. 

scopeThe scope of the eventVIRTUALDATACENTER, ENTERPRISE, DATACENTER, PLATFORM

A full list of entity and action values is at Entity and Action Tables. These are all the entities and the actions that will generate events in Abiquo. 

A full list of all the messages that are created by the tracers is at Abiquo Logs#MessagesinCatalina.outandEventsView. When the corresponding events occur, these messages will be displayed in the Trace column in Events view and registered in the catalina.out log.

The following examples show several subscriptions to receive a subset of events in real time. Atmosphere query parameters are needed but have been removed from the example to make it easier to read. Remember to configure all the parameters if you are going to test the examples:

Subscription examples
# Subscribe to all info messages
curl -u <user>:<password> -X GET "http://localhost/m/stream?severity=info"

# Subscribe to all warn and error messages
curl -u <user>:<password> -X GET "http://localhost/m/stream?severity=warn,error"

# Subscribe to all info messages related to virtual machines
curl -u <user>:<password> -X GET "http://localhost/m/stream?severity=info,entity=VIRTUAL_MACHINE"

# Subscribe to all warning and error messages originated by deploy actions in enterprise 3
curl -u <user>:<password> -X GET "http://localhost/m/stream?severity=warn,enterprise=3,action=DEPLOY"

# Subscribe to all error messages with virtual datacenter scope
curl -u <user>:<password> -X GET "http://localhost/m/stream?scope=virtualdatacenter"

Filters can be combined, in which case they will be joined with an AND operator.

Filters can have multiple values separated by commas.

User Accounts

For an integration, an Abiquo user should be created that will access the streaming API and the password should not expire. Otherwise, when the password changes, your integration will stop receiving events. Therefore, customers with LDAP and password change rules will need to ensure the password for accessing the Abiquo account is always correct.

The events that are accessible to each user role ARE NOT related to the Abiquo Events privileges as seen in the Abiquo GUI.

User RoleAbiquo GUIOutbound API
UserEnterprise eventsUser events only
Enterprise AdminEnterprise events

All enterprise events, including Infrastructure events.
For example, if cloud admin creates a rack while using (impersonating)
this enterprise, then the enterprise admin will see this event

Cloud AdminAll events including SYSTEM eventsAll events including SYSTEM events

Recovering Missed Events


If the third-party system goes down, customers can recover any events lost during downtime by retrieving events using the REST API and filtering them by time stamp. See EventsResource

Event Format

This feature is an extension of the existing system, so the events displayed in the Abiquo GUI and stored in the database still follow the same format as in earlier versions. See Events View#TheEventList

Example Application

The Abiquo Events Notifier is an example of an outbound API Integration.

https://github.com/abiquo/events-notifier/tree/api-outbound