Abiquo Documentation Cookies Policy

Our Documentation website uses cookies to improve your experience. Please visit our Cookie Policy page for more information about cookies and how we use them.


Abiquo 4.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, which manages Abiquo events. The Abiquo M 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 (for the API and UI) and broadcasts them as the event stream of the Outbound API.

Configure Abiquo Events in the M Module 

The M module works with an Abiquo user, which is called “default_outbound_api_user”. This user has access to all events, with the role called OUTBOUND_API.

Configure M for events

If you do not configure M properly, no events will be available in Abiquo. 

In a fresh install, Abiquo will automatically configure M, but if you change the M user or password, you must update the M user account details in the abiquo.properties file on the server where M will run, which by default is the Abiquo Server.. 

If you are upgrading Abiquo, depending on the version, you must set the instance ID, the API location, and enter the M user account details in the abiquo.properties file on the server where M will run, which by default is the Abiquo Server. 


The instance ID must be unique for each instance of Abiquo M. The API location must be an externally accessible IP and port, and you should specify 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).

Example of manual M configuration

Here is sample of a manual M configuration.

abiquo.m.identity = default_outbound_api_user
abiquo.m.credential = AbiquoMPassword
abiquo.server.api.location = http://my.api.location:80/api
 Click here to show/hide diagram of M functionality

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.

Specifications

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

For a full ist of all entities and actions that will generate events in Abiquo, see Entity and Action Tables.

Traces related to events on the platform can be found in the Abiquo Logs 

A full table of events can be found at Events Table, and the Trace column contains the messages that are created by the tracers 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.

Integration User Account

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.

User Access to Events

A user can display the events for which their role has privileges, as listed in the Entity and Action Tables. This access is combined with the User event privileges from Abiquo as described in the following table.


Privilege and ScopeOutbound APIDefault roles
No event privilegesUser events only
Display all events for current enterprise

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

Cloud admin, Ent Admin, Ent User
Display all events + global scopeAll events including SYSTEM eventsCloud admin
Display all events + limited scopeAll events for the locations and enterprises in scope

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

The format of events in the Abiquo UI is described at 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