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.
  • Functions
    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.

  • OCIR
    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 ServicesRegistry (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] 
  • Functions
    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
  • Email Delivery
    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 DeliveryEmail 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.
  • Email Delivery
    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 IdentityUsers
    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
  • Functions
    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...."]'
  • Email Delivery
    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

  • Email Delivery
    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
  • API Gateway
    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.
  • API Gateway
    You will be using OCI Console to create and configure the API Gateway

    1. Click Developer ServicesAPI 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
  • API Gateway
    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
  • API Gateway
    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.

Version: 1.8.0
Build: 2022-02-17T05:02:17Z
© 2022, Oracle and/or its affiliates. All rights reserved.