OCI Events enables you to create automation based on the state changes of resources throughout your tenancy. Examples:
- Send a notification to a DevOps team when a database backup completes.
- Convert files of one format to another when files are uploaded to an Object Storage bucket.
How Events Works
- OCI services emit events.
- Events are structured messages that indicate changes in resources.
- Events follow the CNCF CloudEvents industry standard format.
- This standard allows for interoperability between various cloud providers or on-prem systems & cloud providers.
- An event could be a CRUD op, a resource lifecycle state change, or a system event impacting a resource.
- Services emit events for resources or data.
- e.g. Object Storage emits events for buckets & objects.
Rules
- You work with events by creating rules.
- Rules include a filter you define to specify events produced by the resources in your tenancy.
- You can define filters that match only certain events or all events.
- You can define filters based on the way resources are tagged or the presence of specific values in attributes from the event itself.
- Rules must also specify an action to trigger when the filter finds a matching event.
- Actions are responses you define for event matches.
- You set up select OCI services that the Events service has established as actions.
- The resources for these services act as destinations for matching events.
- When the filter in the rule finds a match, the Events service delivers the matching event to one or more of the destinations you identified in the rule.
- The destination service that receives the event then processes the event in whatever manner you defined.
- This delivery provides the automation in your environment.
- Only the following services can be used to create actions:
- Notifications
- Functions
- Streaming
Events Concepts
- Events — An automatic notification of a state change as reported by an event-emitting OCI resource.
- Event Types — A distinction between the different types of events.
- Rules — A JSON object you create to subscribe to an event type and trigger an action should that event occur.
- Actions — Responses you define for event matches.
Structure of an Event Message
{
"cloudEventsVersion": "0.1",
"eventID": "<unique_ID>",
"eventType": "com.oraclecloud.objectstorage.deletebucket",
"source": "objectstorage",
"eventTypeVersion": "1.0",
"eventTime": "2020-07-03T21:21:21Z",
"contentType": "application/json",
"extensions": {
"compartmentId": "ocid1.compartment.oc1..<unique_ID>"
},
"data": {
"compartmentId": "ocid1.compartment.oc1..<unique_ID>",
"compartmentName": "example_name",
"resourceName": "my_bucket",
"resourceId": "ocid1.compartment.oc1..<unique_ID>",
"availabilityDomain": "GtBU:PHX-AD-1",
"freeFormTags": {
"Department": "Finance"
},
"definedTags": {
"Operations": {
"CostCenter": "37"
}
},
"additionalDetails": {
"namespace": "example_namespace",
"publicAccessType": "NoPublicAccess",
"eTag": "f8ffb6e9-f602-460f-a6c0-00b5abfa24c7"
}
}
}
- Events all have the same set of top-level attributes, which are known as the event envelope.
eventTypeidentifies the type of event included in the payload.
- The payload of the event appears within the
dataattribute.- The information in this field depends on which service produced the event & the event type requested.
- The information in the payload is useful for isolating one event from another with a filter.
- More details here.
Event Matching with Filters
- Rules use filters to select events and route them for delivery to action resources.
- A rule is represented as a JSON object, similar to an event.
- The filter is an attribute of the rule, & the attribute is named
condition. - A filter either matches an event or it does not.
- Fields not mentioned in a filter are ignored.
- You can create a valid filter that matches all event messages with two curly brackets.
- For a filter to match an event, the event must contain all the field names listed in the filter.
- Field names must appear in the filter with the same nesting structure used in the event.
- Rules apply to events in the compartment in which you create them & any child compartments.
- This means that a filter specified by a rule only matches events emitted from resources in the same compartment or any child compartments.
- Wildcard matching is supported with the asterisk (*) character.
- Use the wildcard only in attribute values.
- You cannot use the asterisk for matching in keys.
- An attribute value with only an asterisk matches all values for the associated attribute name, but not null.
- The period character has no special meaning in a filter.
- You can add the asterisk at the start of a string, in the middle, or at the end.
Typical Workflow for Setting up a Rule
Step 1 — Identify Action Resources
- Set up or identify whatever action resources you intend to use with the rule.
- e.g. you might set up a Notifications topic & create subscriptions for the DevOps team so that they are notified when backups complete.
- If a topic already exists, you can use it instead of creating a topic.
- The resources you specify for actions do not have to be in the same compartment as the rule.
Step 2 — Plan Filtering
- Ensure the resources that you want to monitor emit events to the Events service & plan your pattern matching strategy.
- e.g. you might want to monitor backups on ADW instances in the ABC compartment.
- Ensure ADW instances emit an event type you can use to create the automation you require.
- Review the example JSON event to determine the best way to identify those resources in filters.
Step 3 — Create the Rule
- Rules apply to events in the compartment in which you create them & any child compartments.
- Create a rule in the compartment with the resource you want to monitor & specify where to deliver matching events.
- e.g. in the ABC compartment, you might create a rule that filters for ADW backup events.
- Since Events has no requirement about the location of action resources, you could specify a topic in the XYZ compartment as the resource to deliver any matching events.
Harish KM 