Functions: Get Started using the CLI

Before You Begin

To successfully perform this tutorial, you must have the following:

OCI Account Requirements

Software Requirements

1. Gather Required Information

Collect all the information you need to complete the tutorial.

Gather Region and Registry Information

Create or Select a Compartment

Create an Authorization Token

Collect your Information

2. Create your Virtual Cloud Network (VCN)

Set up a VCN to connect your Linux instance to the internet. You configure all the components needed to create your virtual network.

Run the VCN Wizard

Add a Security Rule to your VCN

3. Set up OCI Command Line Interface

To develop functions on your local machine, you must set up the OCI Command Line Interface (CLI). This section assumes you have already installed Docker and Python 3.6+ and pip3.

Complete the following three sections to enable Oracle Functions development on your local machine with the CLI. For a detailed explanation of each step, see Set up Oracle Functions in a Local Dev Environment.

Set up CLI with Python

Setting up the CLI allows you to deploy your functions and function application to OCI Registry from your machine. First, install the CLI using Python's virtual environment feature.

Install virtualenv:
With a virtual environment, you can manage dependencies for your project. Every project can be in its own virtual environment to host independent groups of Python libraries. You install virtualenv and virtualenvwrapper.
1. Ubuntu:
```
sudo pip3 install virtualenv
sudo pip3 install virtualenvwrapper
```
2. Oracle Linux: If you are using an OCI Oracle Linux 7.8 image, Python 3.6 and pip3 are included by default. In case you are using a different Oracle Linux image, the commands to install the Oracle Linux developer repo along with Python 3.6 follow. If your image already has Python 3.6 installed, skip the first two commands down to the pip3 command.
```
sudo yum install oracle-epel-release-el7
sudo yum install python36
sudo pip3 install virtualenv
sudo pip3 install virtualenvwrapper
```
3. MacOS: When you install Python 3 for MacOS, pip3 is installed, so you are ready to install modules with pip3.
```
brew install python3
pip3 install pipenv
```
Note

You might need to type "y" a few times to accept the packages that are installed to the VM.
Create a directory to store your virtual environments. For example, mkdir ~/envs creates an envs directory under your home directory.
Set up your virtual environment wrapper in .bashrc.
Update the file:
```
sudo vi .bashrc
```
Note

The path to the Python executable and virtualwrapper.sh could be different depending on the Linux distro or operating system. Ensure you use the correct path with the which command.

In the file, append the following text and save the file:
```
# set up Python env
export WORKON_HOME=~/envs
export VIRTUALENVWRAPPER_PYTHON=/usr/bin/python3
export VIRTUALENVWRAPPER_VIRTUALENV_ARGS=' -p /usr/bin/python3 '
source /usr/local/bin/virtualenvwrapper.sh
```
Activate the preceding commands in the current window.
```
source ~/.bashrc
```
Start a virtual environment.
```
mkvirtualenv cli-app
```
You see something similar to: (cli-app) ubuntu@<ubuntu-instance-name>:~$
Install the CLI.
```
pip3 install oci-cli
```

Set up CLI Connection

Set up the CLI so it can connect to OCI services.

Set up the CLI config file.
```
oci setup config
```
Enter basic information: (Get the answers from "Gather Required Information" step.)
- Location for your config [$HOME/.oci/config]: <take-default>
- User OCID: <user-ocid>
- Tenancy OCID: <tenancy-ocid>
- Region (for example, us-ashburn-1): <region-identifier>
Set up your OpenSSL API encryption keys:
- Generate a new API Signing RSA key pair? [Y/n]: Y
- Directory for your keys [$HOME/.oci]: <take-default>
- Name for your key [oci_api_key] <take-default>
Note

Your private key is oci_api_key.pem and your public key is oci_api_key_public.pem.
Copy the public key.
In the terminal, enter:
```
cat $HOME/.oci/oci_api_key_public.pem
```
Add the public key to your user account.
- In the navigation bar, select the Profile menu and then select User settings or My profile, depending on the option that you see.
- From your User Settings page, under Resources, click API Keys.
- Click Add Public Key.
- Select Paste Public Keys.
- Paste value from previous step, including the lines with BEGIN PUBLIC KEY and END PUBLIC KEY
- Click Add.
You have now set up the CLI to connect to your tenancy with your user account.
Test the installation:
```
oci os ns get
```
If everything is set up correctly, your namespace is displayed.
Deactivate the virtual environment:
```
deactivate
```
The (cli-app) prefix in your environment is not be displayed anymore.
Note
- Whenever you want to use the CLI, activate it with: workon cli-app
- If you change project names, workon deactivates the environment you are currently in. This way, you can quickly switch between environments.

Set up the Fn Client

To do function development on your local machine, you need to install the Fn client. Fn allows you to create functions, create applications, and deploy functions to the OCI Registry.

Install the Fn client.
The Fn client is used to create, manage, and deploy Oracle Functions. To install the client:

Command line option for Linux, MacOS, and Windows 10 Update 2004 (WSL 2.0):

Enter:
```
curl -LSs https://raw.githubusercontent.com/fnproject/cli/master/install | sh
                    
```
Note

Regularly, rerun the installation command to upgrade to the latest version of Fn.

MacOS using Homebrew:

Enter:
```
brew install fn
```
Note

Fn is updated as part of normal Homebrew upgrades: brew upgrade.
Test your Fn installation.
Enter: fn version

The command returns text similar to:
```
Client version is latest version: 0.6.3
Server version: ?    
                    
```
Note

The response indicates you have installed the current version and do not have the Fn Project server running on your local machine.

4. Prepare the OCI Registry for Functions

Next, you log Docker into the OCI Registry (OCIR).

Log your Docker into OCIR

Get the information you gathered earlier.
Open a terminal window.
Log in to OCIR:
```
docker login <region-key>.ocir.io
```
You are prompted for your login name and password.
- Username: <tenancy-name>/<user-name>
- Password: <auth-token>

You have logged your instance into OCIR.

5. Configure Functions

To use Oracle Functions, you must configure the Fn application context. The context stores the values needed to connect to the Oracle Functions service.

Configure the Fn Context

Use the information you gathered previously for your configuration values.

Open a terminal instance.
Get a list of Fn contexts.

fn list context

You see the default context selected.
Create a Fn context for Oracle Functions. Your <region-identifier> is a good name for your context.

Sample command: fn create context <region-identifier> --provider oracle

Example: fn create context us-phoenix-1 --provider oracle
Use the context you created.

Example: fn use context us-phoenix-1
Set the compartment for Oracle Functions.

Example: fn update context oracle.compartment-id ocid1.compartment.oc1..aaaaaa...
Set the API URL for your Oracle Functions region.

Example: fn update context api-url https://functions.us-phoenix-1.oci.oraclecloud.com

Note

You can find the API endpoints here: Oracle Functions API Endpoints
Set the URL for your Registry repository.

Sample command: fn update context registry <region-key>.ocir.io/<tenancy-namespace>/<repo-name>

Example: fn update context registry phx.ocir.io/my-tenancy/myproject/repo

Note

If you use multiple profiles for the CLI, you need to set a oracle.profile value.

Example: fn update context oracle.profile <profile-name>

You have configured Fn to connect to the Oracle Functions service.

Note

View/Edit your Context

Your Fn context files are in the ~/.fn/contexts directory. Each context is stored in a .yaml file. For example, your us-phoenix-1.yaml file might look similar to:

api-url: https://functions.us-phoenix-1.oci.oraclecloud.com
oracle.compartment-id: ocid1.compartment.oc1..aaaaaaa...
provider: oracle
registry: phx.ocir.io/my-tenancy/myproject/repo

You can edit the file directly with an editor if necessary.

For a detailed explanation of each step, see: Oracle Functions in a Local Dev Environment Quickstart

6. Create and Deploy a Function

With your configuration complete, create and deploy a function.

Create an Application

Create and Deploy your Function

Select one of the following languages to create and deploy a function. If you want, you can do all three.

Create and Deploy a Java Function

With your application created, deploy a Java function. Follow these steps to create a Java "Hello World" function.

Note

Ensure Java 8+ is installed to perform these steps.

Open a terminal.

Create a directory to store your functions and change into that directory.

mkdir my-dir-name
cd my-dir-name

Create a Java "Hello World" function with Fn.
```
fn init --runtime java my-func-name
```
This command creates a directory named my-func-name with several files in it.
- func.yaml - Function configuration file.
- pom.xml - Maven build file.
- src/main/java/com/example/fn/HelloFunction.java - The actual function file.
Change into the directory.
Deploy the function.
```
fn -v deploy --app your-app-name
```
Various messages are displayed as the Docker images are built, pushed to OCIR, and eventually deployed to Oracle Functions.
Invoke the function.
```
fn invoke your-app-name my-func-name
```
Returns: Hello, world!
Invoke the function with a parameter.
```
echo -n "Bob" | fn invoke your-app-name my-func-name
```
Returns: Hello, Bob!
If you want to connect to your function from the net, you need to get the function's invoke endpoint. To find your invoke endpoint use the inspect command.
```
fn inspect function your-app-name my-func-name
```

Examine the results of the inspect command. Notice the invoke endpoint URL is included in the annotatins section of the returned JSON data.

{
    "annotations": {
        "fnproject.io/fn/invokeEndpoint": "https://aaaaaaaaa.us-ashburn-1.functions.oci.oraclecloud.com/1111111/functions/ocid1.fnfunc.oc1.iad.aaaaaaaaa.../actions/invoke",
        "oracle.com/oci/compartmentId": "ocid1.compartment.oc1..aaaaaaaa...",
        "__comment":"Remaining output left out for brevity",

Use the URL returned from inspect to invoke the function. Because functions require requests to be digitally signed, the

oci
                        raw-request

command is used for this example.

oci raw-request --http-method POST --request-body "" --target-uri https://https://aaaaaaaaa.us-ashburn-1.functions.oci.oraclecloud.com/1111111/functions/ocid1.fnfunc.oc1.iad.aaaaaaaaa.../actions/invoke

The command returns:

{
    "data": "Hello, world!",
    "headers": {
        "Content-Length": "13",
        "Content-Type": "text/plain",
        "Date": "Tue, 20 Oct 2020 00:53:08 GMT",
        "Fn-Call-Id": "11111111111",
        "Fn-Fdk-Version": "fdk-java/1.0.111 (jvm=OpenJDK 64-Bit Server VM, jvmv=11.0.8)",
        "Opc-Request-Id": "1111111/11111"
    },
    "status": "200 OK"
}

Note

You can connect to a Functions endpoint using tools like curl. However, because of security considerations, the script is complex. As an alternative, use the OCI CLI raw-request command. See Invoking Functions: Sending a Signed Request to a Function with raw-request.

You have successfully deployed and tested a Java function.

Create and Deploy a Python Function

With your application created, deploy a Python function. Follow these steps to create a Python "Hello World" function.

Open a terminal.

Create a directory to store your functions and change into that directory.

mkdir my-dir-name
cd my-dir-name

Create a Python "Hello World" function with Fn.
```
fn init --runtime python my-func-name
```
This command creates a directory named my-func-name with several files in it.
- func.yaml - Function configuration file.
- requirements.txt - List of required Python libraries.
- func.py - The actual function file.
Change into the directory.
Deploy the function.
```
fn -v deploy --app your-app-name
```
Various messages are displayed as the Docker images are built, pushed to OCIR, and eventually deployed to Oracle Functions.
Invoke the function.
```
fn invoke your-app-name my-func-name
```
Returns: {"message": "Hello World"}
Invoke the function with a parameter.
```
echo -n '{"name":"Bob"}' | fn invoke your-app-name my-func-name
```
Returns: {"message": "Hello Bob"}
If you want to connect to your function from the net, you need to get the function's invoke endpoint. To find your invoke endpoint use the inspect command.
```
fn inspect function your-app-name my-func-name
```

Examine the results of the inspect command. Notice the invoke endpoint URL is included in the annotatins section of the returned JSON data.

{
    "annotations": {
        "fnproject.io/fn/invokeEndpoint": "https://aaaaaaaaa.us-ashburn-1.functions.oci.oraclecloud.com/1111111/functions/ocid1.fnfunc.oc1.iad.aaaaaaaaa.../actions/invoke",
        "oracle.com/oci/compartmentId": "ocid1.compartment.oc1..aaaaaaaa...",
        "__comment":"Remaining output left out for brevity",

Use the URL returned from inspect to invoke the function. Because functions require requests to be digitally signed, the oci raw-request command is used for this example.
```
oci raw-request --http-method POST --request-body "" --target-uri https://aaaaaaaaa.us-ashburn-1.functions.oci.oraclecloud.com/1111111/functions/ocid1.fnfunc.oc1.iad.aaaaaaaaa.../actions/invoke
```
The command returns:
```
{
    "data": "Hello World",
    "headers": {
        "Content-Length": "24",
        "Content-Type": "application/json",
        "Date": "Tue, 20 Oct 2020 00:53:08 GMT",
        "Fn-Call-Id": "11111111111",
        "Fn-Fdk-Version": "fdk-python/0.1.18",
        "Opc-Request-Id": "1111111/11111"
    },
    "status": "200 OK"
}
```
Note

You can connect to a Functions endpoint using tools like curl. However, because of security considerations, the script is complex. As an alternative, use the OCI CLI raw-request command. See Invoking Functions: Sending a Signed Request to a Function with raw-request.

You have successfully deployed and tested a Python function.

Create and Deploy a Node Function

With your application created, deploy a Node function. Follow these steps to create a Node "Hello World" function.

Note

Ensure Node.js 10+ is installed to perform these steps.

Open a terminal.

Create a directory to store your functions and change into that directory.

mkdir my-dir-name
cd my-dir-name

Create a Node "Hello World" function with Fn.
```
fn init --runtime node my-func-name
```
This command creates a directory named my-func-name with several files in it.
- func.yaml - Function configuration file.
- package.json - NPM build file.
- func.js - The actual function file.
Change into the directory.
Deploy the function.
```
fn -v deploy --app your-app-name
```
Various messages are displayed as the Docker images are built, pushed to OCIR, and eventually deployed to Oracle Functions.
Invoke the function.
```
fn invoke your-app-name my-func-name
```
Returns: {"message":"Hello World"}
Invoke the function with a parameter.
```
echo -n '{"name":"Bob"}' | fn invoke your-app-name my-func-name
```
Returns: {"message":"Hello Bob"}
If you want to connect to your function from the net, you need to get the function's invoke endpoint. To find your invoke endpoint use the inspect command.
```
fn inspect function your-app-name my-func-name
```

Examine the results of the inspect command. Notice the invoke endpoint URL is included in the annotatins section of the returned JSON data.

{
    "annotations": {
        "fnproject.io/fn/invokeEndpoint": "https://aaaaaaaaa.us-ashburn-1.functions.oci.oraclecloud.com/1111111/functions/ocid1.fnfunc.oc1.iad.aaaaaaaaa.../actions/invoke",
        "oracle.com/oci/compartmentId": "ocid1.compartment.oc1..aaaaaaaa...",
        "__comment":"Remaining output left out for brevity",

Use the URL returned from inspect to invoke the function. Because functions require requests to be digitally signed, the

oci
                        raw-request

command is used for this example.

oci raw-request --http-method POST --request-body "" --target-uri https://https://aaaaaaaaa.us-ashburn-1.functions.oci.oraclecloud.com/1111111/functions/ocid1.fnfunc.oc1.iad.aaaaaaaaa.../actions/invoke

The command returns:

{
    "data": "Hello World",
    "headers": {
        "Content-Length": "23",
        "Content-Type": "application/json",
        "Date": "Tue, 22 Oct 2020 00:53:08 GMT",
        "Fn-Call-Id": "11111111111",
        "Fn-Fdk-Version": "fdk-node/0.1.18 (njsv=v11.15.0)",
        "Opc-Request-Id": "1111111/11111"
    },
    "status": "200 OK"
}

Note

You can connect to a Functions endpoint using tools like curl. However, because of security considerations, the script is complex. As an alternative, use the OCI CLI raw-request command. See Invoking Functions: Sending a Signed Request to a Function with raw-request.

You have successfully deployed and tested a Node function.

7. Review Function Information

After your functions run, information about your functions is available in the OCI Console.

View Function Images in OCIR

View Function Execution Information

Enable and View Logging Information

What's Next

You have successfully created a function and deployed it to Oracle Functions.

To explore more information about development with Oracle products, check out these sites:

Oracle Cloud Infrastructure Documentation

Functions: Get Started using the CLI

Before You Begin 🔗

1. Gather Required Information 🔗

2. Create your Virtual Cloud Network (VCN) 🔗

3. Set up OCI Command Line Interface 🔗

4. Prepare the OCI Registry for Functions 🔗

5. Configure Functions 🔗

6. Create and Deploy a Function 🔗

7. Review Function Information 🔗

What's Next 🔗

Before You Begin

1. Gather Required Information

2. Create your Virtual Cloud Network (VCN)

3. Set up OCI Command Line Interface

4. Prepare the OCI Registry for Functions

5. Configure Functions

6. Create and Deploy a Function

7. Review Function Information

What's Next