Abiquo 5.0
Outbound API
The Abiquo Outbound API (the "M" module) listens for events from Abiquo and broadcasts them to connected clients.
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 in order to update an asset management register. 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 their cloud customers can subscribe to the events they have permission to access.
Specifications
- EVENT_TYPES:
- 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
- Tracer information
- Different integration examples can be provided in major programming languages
The following diagram shows the basic architecture of the Outbound API.
Authentication
Abiquo supports OAuth authentication to the streaming API. You should sign a request to ''endpoint/api/login'' and use this header in the request to M.
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 "https://abiquo.example.com/m/stream?X-Atmosphere-tracking-id=e24de98c-6624-c552-5572-6edbffd270e3&X-Atmosphere-Framework=1.0&X-Atmosphere-Transport=sse"
data:{"action":"CREATE","context":"024c42a6-a9a2-4fd8-906f-cf7df3f02371","enterpriseName":"Abiquo","enterpriseURI":"/api/admin/enterprises/1","entity":"VIRTUAL_DATACENTER","entityEnterpriseName":"Abiquo","entityEnterpriseURI":"/api/admin/enterprises/1","entityMediaType":"application/vnd.abiquo.virtualdatacenter+json","entityName":"vmware_vdc","entityURI":"/api/cloud/virtualdatacenters/4","errorCode":null,"errorMessage":null,"exception":null,"message":"Virtual datacenter 'vmware_vdc' has been created.","severity":"INFO","tags":["virtualdatacenter:4","user:1","enterprise:1"],"timestamp":1573130105514,"userName":"admin","userURI":"/api/admin/enterprises/1/users/1"}
data:{"action":"CREATE","context":"640bada2-4dab-4d39-96da-d6f200ec4f89","enterpriseName":"Abiquo","enterpriseURI":"/api/admin/enterprises/1","entity":"VIRTUAL_APPLIANCE","entityEnterpriseName":"Abiquo","entityEnterpriseURI":"/api/admin/enterprises/1","entityMediaType":"application/vnd.abiquo.virtualappliance+json","entityName":"vmware_vapp","entityURI":"/api/cloud/virtualdatacenters/4/virtualappliances/4","errorCode":null,"errorMessage":null,"exception":null,"message":"Virtual appliance 'vmware_vapp' has been created.","severity":"INFO","tags":["virtualdatacenter:4","virtualappliance:4","user:1","enterprise:1"],"timestamp":1573130121886,"userName":"admin","userURI":"/api/admin/enterprises/1/users/1"}
data:{"action":"CREATE","context":"d33900c0-76ce-410f-92f5-b4163cadc008","enterpriseName":"Abiquo","enterpriseURI":"/api/admin/enterprises/1","entity":"VIRTUAL_MACHINE","entityEnterpriseName":"Abiquo","entityEnterpriseURI":"/api/admin/enterprises/1","entityMediaType":"application/vnd.abiquo.virtualmachine+json","entityName":"ABQ_551250b8-08d9-48ae-b384-fe4634a3bee2","entityURI":"/api/cloud/virtualdatacenters/4/virtualappliances/4/virtualmachines/177","errorCode":null,"errorMessage":null,"exception":null,"message":"The virtual machine 'ABQ_551250b8-08d9-48ae-b384-fe4634a3bee2' was created successfully.","severity":"INFO","tags":["virtualmachine:177","virtualdatacenter:4","virtualappliance:4","user:1","enterprise:1"],"timestamp":1573130133360,"userName":"admin","userURI":"/api/admin/enterprises/1/users/1"}
data:{"action":"DEPLOY","context":"a2d4e23c-b287-47f6-8e3f-cb6d382cc924","enterpriseName":"Abiquo","enterpriseURI":"/api/admin/enterprises/1","entity":"VIRTUAL_APPLIANCE","entityEnterpriseName":"Abiquo","entityEnterpriseURI":"/api/admin/enterprises/1","entityMediaType":"application/vnd.abiquo.virtualappliance+json","entityName":"vmware_vapp","entityURI":"/api/cloud/virtualdatacenters/4/virtualappliances/4","errorCode":null,"errorMessage":null,"exception":null,"message":"Virtual appliance 'vmware_vapp' is being deployed.","severity":"INFO","tags":["virtualdatacenter:4","virtualappliance:4","user:1","enterprise:1"],"timestamp":1573130145216,"userName":"admin","userURI":"/api/admin/enterprises/1/users/1"}
data:{"action":"ASSIGN","context":"a2d4e23c-b287-47f6-8e3f-cb6d382cc924","enterpriseName":"Abiquo","enterpriseURI":"/api/admin/enterprises/1","entity":"VLAN_TAG","entityEnterpriseName":"Abiquo","entityEnterpriseURI":"/api/admin/enterprises/1","entityMediaType":null,"entityName":null,"entityURI":null,"errorCode":null,"errorMessage":null,"exception":null,"message":"VLAN tag '2' has been assigned to VLAN network 'default_private_network' from virtual datacenter 'vmware_vdc'.","severity":"INFO","tags":["user:1","enterprise:1"],"timestamp":1573130147488,"userName":"admin","userURI":"/api/admin/enterprises/1/users/1"}
data:{"action":"DEPLOY_FINISH","context":"a2d4e23c-b287-47f6-8e3f-cb6d382cc924","enterpriseName":"Abiquo","enterpriseURI":"/api/admin/enterprises/1","entity":"VIRTUAL_MACHINE","entityEnterpriseName":"Abiquo","entityEnterpriseURI":"/api/admin/enterprises/1","entityMediaType":"application/vnd.abiquo.virtualmachine+json","entityName":"ABQ_551250b8-08d9-48ae-b384-fe4634a3bee2","entityURI":"/api/cloud/virtualdatacenters/4/virtualappliances/4/virtualmachines/177","errorCode":null,"errorMessage":null,"exception":null,"message":"Deploy on virtual machine 'ABQ_551250b8-08d9-48ae-b384-fe4634a3bee2' completed. Scheduled in hypervisor '10.60.2.43' ('VMware vCenter') at IP '10.60.2.43'.","severity":"INFO","tags":["virtualmachine:177","virtualdatacenter:4","virtualappliance:4","user:1","enterprise:1"],"timestamp":1573130228944,"userName":"admin","userURI":"/api/admin/enterprises/1/users/1"}
data:{"action":"ALLOCATE_NICS","context":"a2d4e23c-b287-47f6-8e3f-cb6d382cc924","enterpriseName":"Abiquo","enterpriseURI":"/api/admin/enterprises/1","entity":"VIRTUAL_MACHINE","entityEnterpriseName":"Abiquo","entityEnterpriseURI":"/api/admin/enterprises/1","entityMediaType":"application/vnd.abiquo.virtualmachine+json","entityName":"ABQ_551250b8-08d9-48ae-b384-fe4634a3bee2","entityURI":"/api/cloud/virtualdatacenters/4/virtualappliances/4/virtualmachines/177","errorCode":null,"errorMessage":null,"exception":null,"message":"Virtual machine 'ABQ_551250b8-08d9-48ae-b384-fe4634a3bee2' has attached the NIC associated with IP Address '192.168.0.2' in VLAN 'default_private_network'.","severity":"INFO","tags":["virtualmachine:177","virtualdatacenter:4","virtualappliance:4","user:1","enterprise:1"],"timestamp":1573130228948,"userName":"admin","userURI":"/api/admin/enterprises/1/users/1"}
data:{"action":"ALLOCATE_HD","context":"a2d4e23c-b287-47f6-8e3f-cb6d382cc924","enterpriseName":"Abiquo","enterpriseURI":"/api/admin/enterprises/1","entity":"VIRTUAL_MACHINE","entityEnterpriseName":"Abiquo","entityEnterpriseURI":"/api/admin/enterprises/1","entityMediaType":"application/vnd.abiquo.virtualmachine+json","entityName":"ABQ_551250b8-08d9-48ae-b384-fe4634a3bee2","entityURI":"/api/cloud/virtualdatacenters/4/virtualappliances/4/virtualmachines/177","errorCode":null,"errorMessage":null,"exception":null,"message":"The hard disk resource of '64' MB has been assigned to virtual machine 'ABQ_551250b8-08d9-48ae-b384-fe4634a3bee2'.","severity":"INFO","tags":["virtualmachine:177","virtualdatacenter:4","virtualappliance:4","user:1","enterprise:1"],"timestamp":1573130228952,"userName":"admin","userURI":"/api/admin/enterprises/1/users/1"}
data:{"action":"VSM_CHANGE_STATE","context":"b1b17027-e262-4ce5-bb93-b72176d6e5c5","enterpriseName":null,"enterpriseURI":null,"entity":"VIRTUAL_MACHINE","entityEnterpriseName":"Abiquo","entityEnterpriseURI":"/api/admin/enterprises/1","entityMediaType":"application/vnd.abiquo.virtualmachine+json","entityName":"ABQ_551250b8-08d9-48ae-b384-fe4634a3bee2","entityURI":"/api/cloud/virtualdatacenters/4/virtualappliances/4/virtualmachines/177","errorCode":null,"errorMessage":null,"exception":null,"message":"State of virtual machine 'ABQ_551250b8-08d9-48ae-b384-fe4634a3bee2' updated to 'ON'.","severity":"INFO","tags":["virtualmachine:177","virtualdatacenter:4","virtualappliance:4","enterprise:1"],"timestamp":1573130232206,"userName":null,"userURI":null}
During the subscription, a virtual datacenter was created and a VM was deployed, and all events were received in real-time on the client side.
You can refine your subscriptions to receive only the events you are interested in. The following query parameters are available:
| Name | Description | Example values |
|---|---|---|
| severity | The severity of the events | INFO, WARN, ERROR |
| entity | The entity that originated the event | DATACENTER, RACK, VIRTUAL_MACHINE, etc. |
| action | The action performed on the "entity" | CREATE, DEPLOY, DELETE, etc. |
| user | The "id" of the user who generated the event | 1, 2, 25, system, etc. |
| enterprise | The "id" of the enterprise generating the event | 1, 2, 25, etc. |
| scope | The scope of the event | VIRTUALDATACENTER, ENTERPRISE, DATACENTER, PLATFORM |
For a full list of all entities and actions that will generate events in Abiquo, see Events Table
Traces related to events on the platform can be found in the Abiquo Logs
The Events Table contains all events including the Trace column that contains the messages 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 examples to make them easier to read. Remember to configure all the parameters if you are going to test the examples, and you may also require the insecure option for test systems:
Subscription examples
# Subscribe to all info messages curl -u <user>:<password> -X GET "https://localhost/m/stream?severity=info" # Subscribe to all warn and error messages curl -u <user>:<password> -X GET "https://localhost/m/stream?severity=warn,error" # Subscribe to all info messages related to virtual machines curl -u <user>:<password> -X GET "https://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 "https://localhost/m/stream?severity=warn,enterprise=3,action=DEPLOY" # Subscribe to all error messages with virtual datacenter scope curl -u <user>:<password> -X GET "https://localhost/m/stream?scope=virtualdatacenter"
- When you combine filters, the platform separates them with an AND operator.
- To add multiple values for a filter, separate the values with a comma.
User Access to Events
A user can display the events for which their role has privileges, as listed in the Events Table. This access is combined with the User event privileges from Abiquo as described in the following table.
| Privilege and Scope | Outbound API | Default roles |
|---|---|---|
| No event privileges | User events only | |
| Display all events for current enterprise | All enterprise events, including Infrastructure events. | Cloud admin, Ent Admin, Ent User |
| Display all events + global scope | All events including SYSTEM events | Cloud admin |
| Display all events + limited scope | All 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 stream is the same as the events returned by the Abiquo API with the Event Media Type.
The format of events in the Abiquo UI is described at Events View.
Example Application
The Abiquo Events Notifier is an example of an outbound API Integration. This project is not currently maintained so it does not include the changes to the events format introduced in Abiquo 4.7.
https://github.com/abiquo/events-notifier/tree/api-outbound
Java Stream Client
The Abiquo Java Stream Client is available with the API Java Client to help developers build integrations with the Outbound API. The API Stream Client supports OAuth authentication to enable secure connections. The Java Stream Client will enable developers to build event-based integrations and it complements the API Java Client.
Overview
Content Tools
Activity
