Problem
The current event structure used is rather simple, does not conform to any specification (e.g. CloudEvents) and misses the vCenter event payload (body).
type OutboundEvent struct {
Topic string `json:"topic,omitempty"`
Category string `json:"category,omitempty"`
Source string `json:"source"`
UserName string `json:"userName,omitempty"`
CreatedTime time.Time `json:"createdTime,omitempty"`
ObjectName string `json:"objectName,omitempty"`
ManagedObjectReference *vtypes.ManagedObjectReference `json:"managedObjectReference,omitempty"`
}
Solution Proposal
In order to support richer events a breaking change is required. This issue explores a potential solution using the CloudEvents v1 spec. Following the spec, data
would carry the vCenter event payload (encoded as JSON via datacontenttype
) as received (i.e. unmodified) from vCenter. type
is a combination of com.vmware.vc.event.router
and the corresponding event "class", e.g. event
(core) or eventex
. id
is a UUID which can be used for idempotency semantics (detect duplicates) by combining source
+ id
.
Source
would map to the vCenter instance which created the event. Subject
is the canonical name of the event (CamelCase syntax). time
is the event timestamp created by vcenter-connector. data.CreatedTime
is the event timestamp created by the corresponding vCenter.
// CloudEvent is the JSON object sent to subscribed functions. We follow
// CloudEvents v1.0 spec as defined in
// https://github.com/cloudevents/sdk-go/blob/6c55828dbb6915e1594e5ace8bd8a19980731867/pkg/cloudevents/eventcontext_v1.go#L22
type CloudEvent struct {
// ID of the event; must be non-empty and unique within the scope of the producer.
ID string `json:"id"`
// Source - URI of the event producer, e.g. http(s)://vcenter.domain.ext/sdk.
Source string `json:"source"`
// SpecVersion - The version of the CloudEvents specification the connector implements.
SpecVersion string `json:"specversion"`
// Type - canonicalType + vcenter event category (event, eventex, extendedevent).
Type string `json:"type"`
// Subject - vcenter event name used for topic subscriptions
Subject string `json:"subject"`
// Time - Timestamp set by vcenter connector when this message was created.
Time time.Time `json:"time"`
// Data - Event payload as received from vcenter (includes event creation timestamp set by vcenter).
Data types.BaseEvent `json:"data"`
// DataContentType - A MIME (RFC2046) string describing the media type of `data`.
DataContentType string `json:"datacontenttype"`
}
Example event emitted:
{
"id": "a458f76b-bdf1-4288-b745-2ce89ce37d56",
"source": "https://10.0.0.101:443/sdk",
"specversion": "1.0",
"type": "com.vmware.event.router/event",
"subject": "VmPoweredOffEvent",
"time": "2020-01-06T20:49:16.220303Z",
"data": {
"Key": 7134,
"ChainId": 7130,
"CreatedTime": "2020-01-06T20:48:15.158056Z",
"UserName": "VSPHERE.LOCAL\\Administrator",
"Datacenter": {
"Name": "vcqaDC",
"Datacenter": {
"Type": "Datacenter",
"Value": "datacenter-2"
}
},
"ComputeResource": {
"Name": "cls",
"ComputeResource": {
"Type": "ClusterComputeResource",
"Value": "domain-c7"
}
},
"Host": {
"Name": "10.185.16.212",
"Host": {
"Type": "HostSystem",
"Value": "host-21"
}
},
"Vm": {
"Name": "test-vm",
"Vm": {
"Type": "VirtualMachine",
"Value": "vm-48"
}
},
"Ds": null,
"Net": null,
"Dvs": null,
"FullFormattedMessage": "test-vm on 10.0.0.101 in vcqaDC is powered off",
"ChangeTag": "",
"Template": false
},
"datacontenttype": "application/json"
}
Benefits
- Reduce round trips to vCenter by providing event payload in the message body
- Support idempotency
- Conform to CloudEvents spec for standardization across different environments
Impact to existing Users
- Breaking change for consumers on the event structure