Events in Oracle Cloud Infrastructure

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.
    • eventType identifies the type of event included in the payload.
  • The payload of the event appears within the data attribute.
    • 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.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.