1. Automate loading a data mart for line-of-business analytics
  2. Prepare the Local Development Environment

Prepare the Local Development Environment

Before you can start using Oracle Functions to create and deploy functions, you have to set up your local environment for function development.

Although it is possible to use Cloud Shell or an Oracle Cloud Infrastructure compute instance as the development environment, this document assumes you will use a local Linux environment for function development.

Before You Begin

In addition to the tasks presented in this section for setting up a local Linux instance for function development, you must also perform the following tasks:

  • To develop functions locally, install the Fn Project development platform from GitHub.

  • Make sure that you have Docker version 17.10.0 or later installed on your local instance.

    For information about installing or upgrading Docker on Linux, see Oracle Container Runtime for Docker User's Guide.

Create a Signing Key

Before using Oracle Functions, you have to set up an Oracle Cloud Infrastructure API signing key.

  1. Log in to your local machine development environment as a functions developer.
  2. Generate a private key encrypted with a passphrase that you provide by entering:
    $ openssl genrsa -out ~/.oci/<private-key-file-name>.pem -aes128 2048

    where <private-key-file-name> is a name of your choice for the private key file.

  3. When prompted, enter a passphrase to encrypt the private key file. Be sure to make a note of the passphrase you enter, as you will need it later.
  4. When prompted, re-enter the passphrase to confirm it.
  5. Change permissions on the file to ensure that only you can read it.
    $ chmod go-rwx ~/.oci/<private-key-file-name>.pem

    where <private-key-file-name> is a name of the private key file.

  6. Generate a public key (encrypted with the same passphrase that you provided when creating the private key, and in the same location as the private key file) by entering:
    $ openssl rsa -pubout -in ~/.oci/<private-key-file-name>.pem -out ~/.oci/<public-key-file-name>.pem

    where <private-key-file-name> is a name of the private key file and <public-key-file-name> is a name of your choice for the public key file.

  7. When prompted, enter the same passphrase you previously entered to encrypt the private key file.
  8. Copy the contents of the public key file you just created, by entering:
    $ cat ~/.oci/<public-key-file-name>.pem | pbcopy

    where <public-key-file-name> is a name of your choice for the public key file.

  9. Log in to the Console as a functions developer, open the User menu in the upper right corner and select to User Settings.
  10. On the API Keys page, click Add Public Key. Paste the public key's value into the window and click Add. The key is uploaded and its fingerprint is displayed.

Create a Command Line Interface (CLI) Profile

Before using Oracle Functions, you must have an Oracle Cloud Infrastructure CLI configuration file that contains the credentials profile of the user account that you will be using to create and deploy functions.

The Oracle Cloud Infrastructure CLI configuration file can contain several profiles. If you already have a configuration file containing one or more profiles, you have to add a new profile to the existing file for the user who will be using Oracle Functions to create and deploy functions

  1. Log in to your local machine development environment as a functions developer.
  2. Open the file ~/.oci/config in a text editor. (If the directory and/or the file don't already exist, create them).
  3. Add a new profile to the ~.oci/config file as follows:
    [<profile-name>]
user=<user-ocid>
fingerprint=<public-key-fingerprint>
key_file=<full-path-to-private-key-pem-file>
tenancy=<tenancy-ocid>
region=<region-name>
pass_phrase=<passphrase>

    where:

    • <profile-name> is a name of your choosing for the profile.
    • <user-ocid> is the OCID of the Oracle Cloud Infrastructure user account you will use to create and deploy functions.
    • <public-key-fingerprint> is the fingerprint of the public API key value that you uploaded in the Console earlier.
    • <full-path-to-private-key-pem-file> is the full path to the private key file that you created earlier.
    • <tenancy-ocid> is the OCID of the tenancy in which you will be creating and deploying functions.
    • <region-identifier> is the identifier of the Oracle Cloud Infrastructure region in which you will be creating and deploying functions. For example, us-phoenix-1.
    • <passphrase> is the passphrase you specified when creating public/private keys.
  4. Save and close the file.

Copy and Configure the oci-curl Script

You can use a script to invoke a function. The oci-curl script creates a signed request based on credentials you provide in the body of the script.

To use oci-curl to invoke a function, you must provide the credentials of an Oracle Cloud Infrastructure user that has been granted access to resources in the same tenancy and belonging to the same compartment as the function.

Typically you'll want to invoke a function as the functions developer that's configured for your development environment. The instructions below assume that is the case.

  1. Sign in to your development environment.
  2. Create a copy of the oci-curl script file in your development environment and add your credentials to the file as follows:
    1. In a browser, navigate to https://docs.cloud.oracle.com/iaas/Content/Resources/Assets/signing_sample_bash.txt to see the oci-curl code as raw text.
    2. Select all the text and copy it.
    3. In a text editor, open a new file in a convenient location.

      For example, in a terminal window, you might create a new subdirectory in your home directory and open a new file in that directory by entering:

      $ cd ~

$ mkdir oci-curl

$ vim ~/oci-curl/oci-curl.sh

      The name and location of the new file is up to you, but the following instructions assume ~/oci-curl/oci-curl.sh.

    4. Paste the oci-curl script code that you copied earlier into the new file.
    5. Save the file but leave it open so you can add your credentials.
  3. Replace the sample credentials in the oci-curl.sh file with those of the user account that you want to invoke functions:
    local tenancyId="<tenancy_id>";
local authUserId="<user_id>";
local keyFingerprint="<public_fingerprint>";
local privateKeyPath="<private_key_path>";

    Where:

    • <tenancy_id> is the OCID of the tenancy in which the function has been deployed.
    • <user_id> is the OCID of the user account that you want to run the function. The user account must have access to resources in the same tenancy and belonging to the same compartment as the function.
    • <public_fingerprint> is the fingerprint of the user's public key uploaded to Oracle Cloud Infrastructure.
    • <private_key_path> is the full path to the private key file that is paired with the public key for which you provided the fingerprint. For example:
      local privateKeyPath="/Users/johndoe/.oci/john_api_key_private.pem";
  4. Save and close the oci-curl.sh file.

Install the Fn Project Command Line Interface (CLI)

Before using Oracle Functions, the Fn Project command line interface (CLI) must be installed in your development environment.

This procedure uses curl to install the CLI on a Linux instance. Instructions for other operating systems are provided in the readme file for the Fn Project on GitHub.

  1. Log in to your development environment as a functions developer.
  2. Use the following command to retrieve and run the installation script:
    $ curl -LSs https://raw.githubusercontent.com/fnproject/cli/master/install | sh

    If prompted for a password, enter the superuser's password.

  3. In a terminal window, confirm that the CLI has been installed by entering:
    $ fn version

    If the CLI has been correctly installed, the version is displayed.

Create an Fn Command Line Interface Context

When the Fn Project command line interface (CLI) is initially installed, it's configured for local development. To configure Fn Project CLI to connect to your Oracle Cloud Infrastructure tenancy, you have to create a new context.

The context specifies Oracle Functions endpoints, the OCID of the compartment to which deployed functions will belong, and the address of the Docker registry to and from which to push and pull images. You can define multiple contexts, each stored in a different context file in .yaml format.

  1. Log in to your development environment as a function developer.
  2. In a terminal window, create the new Fn Project CLI context for Oracle Cloud Infrastructure:
    $ fn create context <my-context> --provider oracle

    where <my-context> is a name you choose.

  3. Specify that the Fn Project CLI is to use the new context:
    $ fn use context <my-context>

    where <my-context> is the context name that you specified.

  4. Specify the name of the command line interface profile to use:
    $ fn update context oracle.profile <profile-name>
  5. Specify the compartment OCID where the deployed functions will be deployed:
    $ fn update context oracle.compartment-id <compartment-ocid>
  6. Specify the endpoint to use when calling the API:
    $ fn update context api-url <api-endpoint>
    Where <api-endpoint> is one of the endpoints in the format: 
    https://functions.<region-identifier>.oci.oraclecloud.com
    Where <region-identifier> is the identifier of the Oracle Cloud Infrastructure region in which you'll be creating and deploying functions. For example:
    us-phoenix-1
  7. Configure the new context with the address of the Docker registry that you want to use with Oracle Functions:
    $ fn update context registry <region-key>.ocir.io/<tenancy-namespace>/<repo-name>
    Where:

    • <region-key> is the key of the Oracle Cloud Infrastructure Registry region. For example, phx for Phoenix.

      Oracle recommends that the Docker registry you specify is in the same region as the subnet on which you intend functions to run.

    • <tenancy-namespace> is the auto-generated Oracle Cloud Infrastructure Object Storage namespace string of the tenancy in which to create repositories (as shown on the Tenancy Information page).
    • <repo-name> is a repository name to pre-pend to the names of functions that you deploy.

    For example:

    $ fn update context registry phx.ocir.io/ansh81vru1zp/my-repo

Create an Auth Token

To deploy functions in Oracle Cloud Infrastructure, you must create an auth token to use as the password when signing Docker in to Oracle Cloud Infrastructure Registry.

  1. Sign in to the Oracle Cloud Infrastructure console, click the User icon, and select User Settings.
  2. To create a new auth token, click Auth Tokens in the Resources section and then click Generate Token.
  3. Provide a description for the Auth Token and click Generate Token. Copy the token when it is displayed.
  4. Click the Copy link and store the token information in a secure location because when you close the dialog, you will not be able see the token in the console again.
  5. Click Close.

Sign In to Oracle Cloud Infrastructure Registry

Before you can use Oracle Functions, you must sign Docker in to the Docker registry in which you are going to store your functions as Docker images. This is the Docker registry you specified earlier in the Fn Project command line interface (CLI) context.

Before you can sign in to the registry, you must first have done the following:
  • Installed and started Docker on the development environment
  • Created an Oracle Cloud Infrastructure context for the Fn command line interface (CLI)
  • Created an Oracle Cloud Infrastructure auth token for the user

You can store functions in public and private repositories in Oracle Cloud Infrastructure Registry, an Oracle-managed registry built on top of Oracle Cloud Infrastructure.

To complete the steps below, you must provide the tenancy namespace for Oracle Cloud Infrastructure Object Storage, the user name, and the user's auth token.

To sign Docker into Oracle Cloud Infrastructure Registry:

  1. Sign in to your development environment as a function developer.
  2. In a terminal window, sign in to Oracle Cloud Infrastructure Registry:
    $ docker login <region-key>.ocir.io

    Where <region-key> is the key for the Oracle Cloud Infrastructure Registry region specified in the Fn Project CLI context. For example, phx for Phoenix.

  3. When prompted, enter the Username of the user who will create and deploy functions:
    <tenancy-namespace>/<username>
    Where:
    • <tenancy-namespace> is the auto-generated Oracle Cloud Infrastructure Object Storage namespace string of the tenancy in which to create repositories (as shown on the Tenancy Information page).
    • <username> is the user who will create and deploy functions.
    If your tenancy is federated with Oracle Identity Cloud Service, use the format:
    <tenancy-namespace>/oracleidentitycloudservice/<username>
  4. When prompted for a Password, enter the user's Oracle Cloud Infrastructure auth token.