Cloud Native OCI

Functions

🖨️

Created with ❤ by Oracle A-Team

Prerequisites

Configure the Tenancy
Install Fn CLI
Create OCIR Repository
Configure Fn CLI

Before you start using Oracle Functions you have to set up your tenancy. Make sure you follow the Configuring Your Tenancy for Function Development documentation to create the requird Groups, Users, Compartments and other configuration tasks.

Note: if you already have a Kubernetes cluster running in OCI, you don't need to create a separate VCN and Subnets (step #4 in the above documentation), instead you can use the OKE's VCN and subnets.
To work with Oracle Functions you will need to install the Fn CLI.

Download the installation script (Unix/Linux/MacOS)
```
curl -LSs https://raw.githubusercontent.com/fnproject/cli/master/install | sh
```
If you are using Brew (on MacOS):
```
brew update && brew install fn
```
On Windows, download the `fn.exe` from GitHub Releases page.
When deploying the function, Fn CLI automatically builds and pushes the Docker image to the OCIR. For this to work, you need to have a repository created and be logged in to the registry (OCIR).
1. From the left sidebar in OCI Console, click Developer Services → Registry (OCIR)
2. Click the Create Repository button
3. Enter mushop-functions for the repository name and click Create Repository
4. From your terminal window, log in to the registry (replace the username, password, region-key and tenancy namespace with actual values):
```
docker login --username [username] --password [password] [region-key].ocir.io/[tenancy-namespace] 
```
Before you can use the Fn CLI, you need to create a context file and configure an image registry.
1. Create a new Fn CLI context and switch to it:
```
fn create context mushop-context --provider oracle
fn use context mushop-context
```
2. Configure the context with an OCID of the compartment where you will be deploying your functions (you can use the same compartment where your OKE cluster is):
```
fn update context oracle.compartment-id [compartment-ocid]
```
3. Update the api-url endpoint (replace the [region] with an actual region name e.g. us-phoenix-1):
```
fn update context api-url https://functions.[region].oci.oraclecloud.com
```
4. Update the registry with an address of your Docker registry (e.g. phx.ocir.io/my-tenancy/my-repo)
```
fn update context registry [region-key].ocir.io/[tenancy-namespace]/[repo-name]
```

Email Delivery Setup

Approved Sender
SMTP Credentials

The function will send an email message to the provided address. In order to send the email using OCI Email Delivery you need to configure an approved sender first.
1. From the OCI Console, click Email Delivery → Email Approved Sender
2. Click the Create Approved Sender
3. Enter the email address (e.g. mushop@example.com)
4. Click Create Approved Sender
Note: if you have your own domain, you can enter a different address (e.g. mushop@[yourdomain.com]) and also configure SPF record for the sender. This involves adding a DNS record to your domain. You can follow the instructions to configure SPF.
You need to generate the SMTP credentials that will allow you to log in to the SMTP server and send the email. Go to the OCI console and follow the steps below.
1. From the left sidebar, under Governance and Administration, click Identity → Users
2. Click on your username
3. Click SMTP Credentials and the Generate SMTP Credentials button
4. Enter a description and click the Generate SMTP Credentials button
5. Copy the username and password as you will use it later, then close the dialog
The SMTP credentails (host, port, username and password) and the approved sender email address will be provided to the function as configuration values later, so make sure you save these values somewhere.

Function

Create
Deploy
Configure

Each function needs to live inside of an application. You can create a new application either through the console, API or the Fn CLI. An application has a name (e.g. mushop-app) and the VCN and a subnet in which to run the functions. Make sure you have your subnet OCID available before following the steps below.
1. Open your terminal window
2. Create an application (replace the ocid1.subnet.oc1.iad... with an actual subnet OCID):
```
fn create app mushop-app --annotation oracle.com/oci/subnetIds='["ocid1.subnet.oc1.iad...."]'
```
With the application ready, you can now deploy the newsletter-subscription function

From the /src/functions/newsletter-subscription folder, run the following command:
```
fn deploy --app mushop-app
```

As a final step you need to configure the function and provide SMTP settings and the approved sender email you created earlier.

Run the following command (replace the placeholders with actual values you stored from previous steps):

fn config function mushop-app newsletter-subscription SMTP_USER [smtp_username]
fn config function mushop-app newsletter-subscription SMTP_PASSWORD [smtp_password]
fn config function mushop-app newsletter-subscription SMTP_HOST [smtp_host]
fn config function mushop-app newsletter-subscription SMTP_PORT [smtp_port]
fn config function mushop-app newsletter-subscription APPROVED_SENDER_EMAIL [approved_sender_email>

API Gateway

Prepare
Create the Gateway
Create a Deployment
Try it out

You will be using an API Gateway to access and invoke the function.

To prepare your tenancy for using the gateway, follow the Preparing for API Gateway documentation.
You will be using OCI Console to create and configure the API Gateway
1. Click Developer Services → API Gateway from the left sidebar
2. Click the Create Gateway button
3. Enter the following values:
  - Name: mushop-gateway
  - Type: Public
  - Virtual Cloud Network: Pick VNC from the dropdown
  - Subnet: Pick the subnet from the dropdown
4. Click Create
With API Gateway created, you can start creating a deployment
1. Click the Deployments link from the sidebar on the left
2. Under the Deployments, click the Create Deployment button
3. Select the From Scratch option and enter the following values:
  - Name: newsletter-subscription
  - Path prefix: /newsletter
  - Compartment: Pick your compartment
  - Execution log: Enabled
  - Log level: Error
4. Click Next to define the route
5. Enter the following values for Route 1:
  - Path: subscribe
  - Methods: POST
  - Type: Oracle Functions
  - Application: mushop-app
  - Function name: newsletter-subscription
6. Click Show Route Logging Policies link and enable Execution Log
7. Click Next to review the deployment and Create to create it
When the deployment completes, click on it to get the URL for the gateway.

You can click the Show link next to the Endpoint label to reveal the full URL of the deployment (e.g. https://aaa.apigateway.us-ashburn-1.coi.customer-oci.com/newsletter)

To invoke the function through the gateway, you can use the command below (replace the email with your actual email address and the API gateway URL with the real value):
```
curl -X POST -d '{"email": "youremail@example.com"}'  https://aaa.apigateway.us-ashburn-1.oci.customer-oci.com/newsletter/subscribe
```
If everything succeeded, the function response will look similar to this one:
```
{"messageId":"<0cc76573-2b9b-5a22-6032-8b7e7fec8378@example.com>"}
```
You should also receive an email message to the address you provided above.