Using a Sample to Create a Function with Code Editor

Find out how to use Code Editor to create a new function in OCI Functions based on a sample function.

You can use Code Editor to create a new function in OCI Functions based on a sample function. Oracle provides a number of useful sample functions written in different languages. Having created a sample function func.yaml and source code files in an unversioned directory, you use Code Editor to convert the directory into a local Git repository that you can then push to a remote Git repository. With the files in the remote Git repository, you can then use Code Editor to deploy the function to OCI Functions, and then to invoke the function.

When using Code Editor to create and update functions, note the following:

The remote Git repository must contain a valid func.yaml file at the top level.
The name of a function you create using Code Editor must match the function name specified in the func.yaml file in the remote code repository. If the names are different, you will be unable to invoke the function.
When you deploy a function to OCI Functions, you are fetching the latest commit from the remote Git repository. Uncommitted changes, and commits in the local repository, are ignored. Therefore, before you can deploy a new or updated function to OCI Functions, you must always commit new and modified files to the local Git repository, and then push the changes to the remote Git repository.

This topic explains how to use Code Editor to:

create a new function from a sample function
convert the unversioned directory containing the function's func.yaml and source code files into a local Git repository that you can then push to a remote Git repository
deploy the function to OCI Functions
invoke the function
optionally, update the function, re-deploy it, and invoke it again

Before you start:

You must have completed the steps in the Functions QuickStart on Cloud Shell.
To follow the steps in this topic, you must have access to an empty remote Git repository (for example, in GitHub), or be able to create such a repository.
For convenience and simplicity, the examples in this topic assume you create a function from the oci-list-compartments-python sample function. If you create a function from a different sample function, some of the instructions do not apply.

For more information about Code Editor features and functionality, see Code Editor.

Creating a Function From a Sample Using Code Editor

To use Code Editor to create a new function in OCI Functions based on a sample function:

Confirm that you have completed the steps in the Functions QuickStart on Cloud Shell to:
- Set up your tenancy with groups and users, create a compartment in which to create OCI Functions resources, create a VCN and subnets, and create an IAM policy.
- Set up your Cloud Shell dev environment with the Fn Project CLI context, obtain an auth token, and log in to the Docker registry specified for the Fn Project CLI context.
Sign in to the Console as a functions developer.
Use the Console to create a new application in OCI Functions:
1. Open the navigation menu and click Developer Services. Under Functions, click Applications.
2. Select the region you intend to use for OCI Functions.
  We recommend that you use the same region as the Docker registry specified in the Fn Project CLI context (see Creating an Fn Project CLI Context to Connect to Oracle Cloud Infrastructure).
3. Select the compartment specified in the Fn Project CLI context (see Creating an Fn Project CLI Context to Connect to Oracle Cloud Infrastructure).
  
  The Applications page shows the applications already defined in the compartment.
4. Click Create Application and specify:
  - A name for the new application. For example, samples-app
  - The VCN and subnet (or subnets, up to a maximum of three) in which to run the function. We recommend that subnets are in the same region as the Docker registry specified in the Fn Project CLI context (see Creating an Fn Project CLI Context to Connect to Oracle Cloud Infrastructure).
5. Click Create to create the application.
Start Code Editor in either of the following ways:
- On the Application Details page, under Resources, click Functions. On the Functions page, click the Create Function button, and select Create in Code Editor. This method opens Code Editor at the application you just created.
- Click the Code Editor button in the Console's toolbar.
Create a new function from a sample function:
1. In the Code Editor Oracle Cloud Infrastructure panel, navigate to the application you just created in the compartment specified in the Fn Project CLI context. For example, samples-app.
2. With the application name highlighted, select Create Function... from the right mouse button menu.
3. Select the Create from a sample creation method in the entry field in the Code Editor menu bar.
4. Select a function from the sample function list and press Enter. For example, select oci-list-compartments-python.
5. Enter a name for the new function in the entry field in the Code Editor menu bar and press Enter. The name you enter must be the same as the name in the sample function's func.yaml file. In most cases, this is the name in the sample functions list in the previous step. For example, oci-list-compartments-python.
  Enter a name for the new function in the entry field in the Code Editor menu bar and press Enter. The name you enter must be the same as the name of the sample function you selected form the list. For example, oci-list-compartments-python.
6. Click OK to acknowledge the dialog informing you that changes have to be committed and pushed to a remote branch before the function can be deployed.
  A directory named after the function is created in the /home/<username>/oci-ide-plugins/faas-artifacts/<app-ocid>/ directory. For example, in /home/jdoe/oci-ide-plugins/faas-artifacts/ocid1.fnapp.oc1.iad.aaaaaa______76nf/oci-list-compartments-python,
  If you have based the new function on the oci-list-compartments-python sample function, the directory contains:
  - func.yaml
  - func.py
  - README.md
  - requirments.txt
  - an /images directory
Save the function in a local Git repository:
1. Open a Code Editor terminal window by selecting New Terminal from the Terminal window in the Code Editor menu bar.
2. In the Code Editor terminal window, change directory to the newly created directory containing the func.yaml file and the function source files by entering:
```
cd /home/<oci-username>/oci-ide-plugins/faas-artifacts/<application-OCID>/<function-name>
```
  For example:
```
cd /home/jdoe/oci-ide-plugins/faas-artifacts/ocid1.fnapp.oc1.iad.aaaaaaaa______76nf/oci-list-compartments-python
```
3. Convert the unversioned directory (for example, named oci-list-compartments-python) into a local Git repository by entering:
```
git init
```
4. Add the files in the directory to the staging area by entering:
```
git add .
```
5. Store the contents of the staging area in the local Git repository by entering:
```
git commit
```
6. When prompted, enter a commit message:
  1. Press the i key on your keyboard to insert text.
  2. Enter a commit message. For example, by entering:
```
Adds sample files.
```
  3. Press the Esc key, then type : w q and then press Enter.
Create a new remote Git repository. For example, in GitHub as https://github.com/jdoe/list-compartments-sample-repo.
Push the function to the remote Git repository:
1. In the Code Editor terminal window, in the directory containing the func.yaml file and the function source files, connect the local Git repository to the remote Git repository you just created by entering:
```
git remote add origin <remote-repository-url>
```
  For example:
```
git remote add origin https://github.com/jdoe/list-compartments-sample-repo.git
```
2. Create a new branch named main in the local Git repository by entering:
```
git branch -M main
```
3. Push files to the main branch in the remote Git repository by entering:
```
git push -u origin main
```
4. If prompted, enter the Git username and password for the remote Git repository.
  In the case of GitHub, note that the password is the GitHub Personal Access Token.
Deploy the function to OCI Functions:
1. In the Code Editor terminal window, in the directory containing the func.yaml file and the function source files, log in to the Docker registry specified in the Fn Project CLI context. Assuming the Docker registry is Oracle Cloud Infrastructure Registry, use the following command:
```
docker login -u '<tenancy-namespace>/<user-name>' <region-key>.ocir.io
```
  For example:
```
docker login -u 'ansh81vru1zp/jdoe@acme.com' phx.ocir.io
```
2. When prompted for a password, enter your OCI auth token.
3. In the Code Editor terminal window, deploy the function to OCI Functions by running:
```
fn -v deploy --app <application-name>
```
  For example:
```
fn -v deploy --app samples-app
```
Some sample functions have specific prerequisites, such as particular IAM policies. These prerequisites are described in the sample function's README.md file. For example, for a function based on the oci-list-compartments-python sample function, the README.md file states the only pre-requisite is that the function is a member of a dynamic group.

If you have based the new function on the oci-list-compartments-python sample function, follow the instructions below to add the function to a dynamic group:
1. Open the navigation menu and click Identity & Security. Under Identity, click Domains. Under Identity domain, click Dynamic groups.
2. Follow the instructions in To create a dynamic group, and give the dynamic group a name (for example, sample-func-dyn-grp).
3. When specifying a rule for the dynamic group, enter a rule similar to the following to add all functions in the compartment in which you created the new function to the dynamic group:
```
ALL {resource.type = 'fnfunc', resource.compartment.id = '<compartment-ocid>'}
```
  where <compartment-ocid> is the OCID of the compartment in which you created the application.
  
  For example:
```
ALL {resource.type = 'fnfunc', resource.compartment.id = 'ocid1.compartment.oc1..aaaaaaaa23______smwa'}
```
4. Click Create Dynamic Group.
Invoke the function you've just deployed:
1. In the Code Editor terminal window, in the directory containing the func.yaml file and the function source files, invoke the function by running:
```
fn invoke <application-name> <function-name>
```
  For example:
```
fn invoke samples-app oci-list-compartments-python
```
  If a message is returned showing the function is not found, one likely cause is a mismatch between the name of the function you created in Code Editor, and the name of the function specified in the func.yaml. Repeat the previous steps to create a function in Code Editor that has the same name as specified in the func.yaml file in the remote Git repository.
  Provided you have met the prerequisites identified in the function's README.md file, the function returns a response.
  For example, if you have based the new function on the oci-list-compartments-python sample function and added the function to a dynamic group (as described earlier), the function returns a list of all compartments within the tenancy as follows:
```
{"compartments": [["<compartment-ocid>", "<compartment-name>"], ["<compartment-ocid>", "<compartment-name>"]… }
```
(Optional) If you have based the new function on the oci-list-compartments-python sample function in the previous steps, this optional step describes how to customize the sample function by changing some of the text of the message that is displayed when the function is invoked. You update the message text in the local Git repository, push the update to the remote Git repository, and then deploy and invoke the function.
1. In the Code Editor Oracle Cloud Infrastructure panel, under the oci-list-compartments-python function that you just created, click on the func.py file and change the line:
```
resp = {"compartments": compartments}
```
  to read:
```
resp = {"compartments in tenancy": compartments}
```
2. In the Code Editor navigator, select the Source Control panel, click the More Actions button, and select Commit from the Commit menu.
3. When prompted to stage changes, click Yes.
4. Enter a commit message (for example, Adds-in-tenancy) and press Enter.
5. Click the More Actions button, and select Push from the Pull, Push menu
6. If prompted, enter the Git username and password for the remote Git repository.
  In the case of GitHub, note that the password is the GitHub Personal Access Token.
7. If a dialog is displayed with the message "Would you like Code Editor to periodically run 'git fetch'?", click Ask Me Later.
8. In the Code Editor terminal window, in the directory containing the func.yaml file and the function source files, deploy the function to OCI Functions by entering:
```
fn -v deploy --app <application-name>
```
  For example:
```
fn -v deploy --app samples-app
```
9. In the Code Editor terminal window, invoke the function by entering:
```
fn invoke <application-name> <function-name>
```
  For example:
```
fn invoke samples-app oci-list-compartments-python
```
  The following message is displayed:
```
{"compartments in tenancy": [["<compartment-ocid>", "<compartment-name>"], ["<compartment-ocid>", "<compartment-name>"]… }
```
The updated message confirms you have successfully modified function source code in the local Git repository, pushed the update to the remote Git repository, and then deployed and invoked the function.

Oracle Cloud Infrastructure Documentation

Using a Sample to Create a Function with Code Editor

Creating a Function From a Sample Using Code Editor