Difficulty: beginner
Estimated Time: 30 minutes

OCI Events

INTRO

With OCI Events you can easily configure OCI Services and resources to publish events in response to actions that happened within other OCI elements, such as:

  • Identity Services
  • Functions
  • Database
  • Compute
  • Big Data Service
  • Object Storage
  • Block Volume
  • File Storage
  • Data Safe
  • Networking
  • Health Checks
  • Analytics
  • Resource Manager
  • Content and Experience
  • Digital Assistant
  • API Gateway

Pretty much most of the OCI components are candidates to trigger events.

Which type of events (you may be asking)? Let's take as an example the Object Storage Service. This Object Storage Service is capable to trigger events in the following scenarios:

  1. When a bucket is created, deleted or updated
  2. When an object is created, deleted or updated

Now, regardless the service and the type of event, you can create actions that will take place after the event happens. Those actions are of any of the following three types:

  1. Streaming
  2. Notifications
  3. Functions

That means that after a bucket is created/deleted/updated, you have the ability to send a notification (email, for instance). Or you can call a function that can execute something with the information contained in the event. Within the function boundary, you can execute pretty much whatever you want with that information. Or if you need to stream that information, you can also send it within a stream using Oracle Streams.

You also have the ability to chain events, with the alternative to use the attributes within the event information. For example:

  • A bucket is created
  • You want to create an action, everytime a bucket is created AND when the resourceName is "backups".
  • If those two things happen, you want to take action and send an Email to the backups administrator.

The format of the OCI Event is compliant with an standard defined by the CNCF for cloud based events. The envelope contains elements such as:

  • cloudEventsVersion
  • contentType
  • data
  • eventID
  • eventTime
  • eventType
  • eventTypeVersion
  • extensions
  • source

(If you want to learn more about the structure, take a look to this documentation https://docs.cloud.oracle.com/en-us/iaas/Content/Events/Reference/eventenvelopereference.htm)

For learning more about events, you can take a look to the official Oracle documentation, here: https://docs.cloud.oracle.com/en-us/iaas/Content/Events/Concepts/eventsoverview.htm

The OCI Events scenarios that you are about to go through are the following:

1.First scenario.

  • We will use the object storage as the service that will produce the events.
  • This first scenario is the simplest one. After a bucket is created and the name is bucketLab+LabID, you will receive an email with the details for the new bucket.
  • In this scenario you will learn: a) How to create a Rule b) How to associate an event c) How to create an Action d) How to create a Topic with an email Endpoint

2.Second scenario.

  • We are still going to use the object storage, but the rule will be different
  • In this second scenario, we will react after an object is created in a bucket.
  • We will create a function that will receive the event information including the object created, and it will use its contents to create a PDF and upload it to a second bucket.
  • The function code will be provided in the scenario. The recommendation is that you follow the functions scenarios before executing this.

OCI Cloud Native Events

Resources

Oracle Documentation https://docs.cloud.oracle.com/en-us/iaas/Content/Events/Concepts/eventsoverview.htm Event Envelope reference https://docs.cloud.oracle.com/en-us/iaas/Content/Events/Reference/eventenvelopereference.htm

Summary

This completes your first contact with Oracle Events. You've learned:

  • How to create a rule with conditions
  • How to associate those rules with actions
  • You've learned how an action cand send an email notification or call an Oracle Functions
  • You've learned some OCI CLI command to create rules, buckets, upload objects, list objects

Now you are ready to create your own events.

Background Resources

Oracle Events Documentation https://docs.cloud.oracle.com/en-us/iaas/Content/Events/Concepts/eventsoverview.htm

Oracle CLI Reference https://docs.cloud.oracle.com/en-us/iaas/Content/API/Concepts/cliconcepts.htm

Responding to OCI Events

Step 1 of 4

Step 1 - Introducing OCI Events

Wait for OCI CLI to be installed

You need to provide details on the OCI tenancy you will work in and the OCI user you will work as. Please edit these two files:

  • ~/.oci/config
  • ~/.oci/oci_api_key.pem

Paste the contents provided by the workshop instructor into these two files.

Do not continue until you see the file /root/allSetInBackground appear. If it appears, then the OCI CLI has been installed and you can continue.

Try out the following command to get a list of all namespaces you currently have access to - based on the OCI Configuration defined above.

oci os ns get

If you get a proper response, the OCI is configured correctly and you can proceed. If you run into an error, ask for help from your instructor.

You need to perform one more edit action on file ~/.oci/config. Open this file in the editor. Copy the entire contents and paste it below the current contents. Now change [DEFAULT] to [FN] in the duplicate block. The file will now look something like:

[DEFAULT]
user=ocid1.user.oc1..aaaaaaaazr7eselv5q
fingerprint=fd:db:13:bd:31
tenancy=ocid1.tenancy.oc1..aaaaaaaaggg6okq
region=us-ashburn-1
key_file=/root/.oci/oci_api_key.pem
[FN]
user=ocid1.user.oc1..aaaaaaaazr7eselv5q
fingerprint=fd:db:13:bd:31
tenancy=ocid1.tenancy.oc1..aaaaaaaaggg6okq
region=us-ashburn-1
key_file=/root/.oci/oci_api_key.pem

Now please set the Region environment variable using this command:

export REGION=$(oci iam region-subscription list | jq -r '.data[0]."region-name"')
export REGION_KEY_UPPER=$(oci iam region-subscription list | jq -r '.data[0]."region-key"')
export REGION_KEY=$(echo $REGION_KEY_UPPER | tr '[:upper:]' '[:lower:]')

Set the environment variable LAB_ID to the number provided to you by the workshop instructor.

export LAB_ID=1

Now let's set the following environment variables. Note: the assumptions here are a compartment called lab-compartment, a VCN called vcn-lab and a subnet in that VCN called Public Subnet-vcn-lab. We need to get references to these resources in order to create the Functions that we will use in step 3.

export CS=$(oci iam compartment list)
export COMPARTMENT_OCID=$(echo $CS | jq -r --arg display_name "lab-compartment" '.data | map(select(."name" == $display_name)) | .[0] | .id')
export VCNS=$(oci network vcn list -c $COMPARTMENT_OCID)
export VCNID=$(echo $VCNS | jq -r --arg display_name "vcn-lab" '.data | map(select(."display-name" == $display_name)) | .[0] | .id')
export SUBNETS=$(oci network subnet list  -c $COMPARTMENT_OCID --vcn-id $VCNID)
export SUBNETID=$(echo $SUBNETS | jq -r --arg display_name "Public Subnet-vcn-lab" '.data | map(select(."display-name" == $display_name)) | .[0] | .id')
export NSS=$(oci os ns get)
export NAMESPACE=$(echo $NSS | jq -r '.data')
export REGION=us-ashburn-1
export MY_BUCKET=$(echo myBucket$LAB_ID)

The following variables will be set using the information contained in the OCI config file ($HOME/.oci/config)

export TENANT_OCID=$(grep -i 'tenancy' $HOME/.oci/config  | cut -f2 -d'=' | head -1)
export USER_OCID=$(grep -i 'user' $HOME/.oci/config  | cut -f2 -d'=' | head -1)
export FINGERPRINT=$(grep -i 'fingerprint' $HOME/.oci/config  | cut -f2 -d'=' | head -1)
export PASSPHRASE=$(grep -i 'pass_phrase' $HOME/.oci/config  | cut -f2 -d'=' | head -1)

(Note. If you do not have a passphrase, it is not necessary to set that environment variable)

Oracle Events Configuration

In the tenant that you are using, there are a set of policies already in place, but if you are curious or if you are using your own environment you need to create a set of polices that will allow users to create and manage rules.

As we already mentioned, in the tenant you are using, those policies are already in place. If you want to learn more about those policies take a look here.