Functions QuickStart on an OCI Compute Instance

A. Set up your tenancy

1. Create groups and users

If suitable users and groups don't exist already:

  1. Sign in to the Console as a tenancy administrator.
  2. Open the navigation menu and click Identity & Security. Under Identity, click Groups.
  3. Create a new group by clicking Groups and then Create Group.
    This image shows the Create Group dialog, with empty Name and Description fields.
  4. Create a new user by clicking Users and then Create User.
    This image shows the Create User dialog, with empty Name, Description, Email, and Confirm Email fields.
  5. Add a user to a group by clicking Groups, then the name of the group, and then Add User to Group.
    This image shows the Add User to Group dialog, with an empty Users field.

See Configuration Notes for more information.

2. Create compartment

If a suitable compartment in which to create network resources and Oracle Functions resources doesn't exist already:

  1. Sign in to the Console as a tenancy administrator.
  2. Open the navigation menu and click Identity & Security. Under Identity, click Compartments.
  3. Click Create Compartment.
    This image shows the Create Compartment dialog, with empty Name and Description fields.

See Configuration Notes for more information.

3. Create VCN and subnets

If a suitable VCN in which to create network resources doesn't exist already:

  1. Sign in to the Console as a tenancy administrator.
  2. Open the navigation menu, click Networking, and then click Virtual Cloud Networks.
  3. Click Start VCN Wizard to create a new VCN.
  4. In the Start VCN Wizard dialog box, select VCN with Internet Connectivity and click Start VCN Wizard.
    This image shows the Start VCN Wizard dialog, with the "Create VCN with Internet Connectivity" option selected.
  5. Enter a name for the new VCN, click Next, and then click Create to create the VCN along with the related network resources.

See Configuration Notes for more information.

4. Create policy for group and service

If one or more Oracle Functions users is not a tenancy administrator:

  1. Sign in to the Console as a tenancy administrator.
  2. Open the navigation menu and click Identity & Security. Under Identity, click Policies.
  3. Click Create Policy, specify a name and description for the new policy, and select the tenancy's root compartment.

  4. Use the Policy Builder to create the policy. Select Functions from the list of Policy use cases, and base the policy on the policy template Let users create, deploy, and manage functions and applications using Cloud Shell.

    This image shows the Create Policy dialog, with empty Name, Description, and Compartment fields. The "Let users create, deploy, and manage functions and applications using Cloud Shell" template is shown in the Common policy templates field. Several of the policy statements are shown.

    The policy template includes the following policy statements:

    • Allow group <group-name> to use cloud-shell in tenancy
    • Allow group <group-name> to manage repos in tenancy
    • Allow group <group-name> to read objectstorage-namespaces in tenancy
    • Allow group <group-name> to manage logging-family in tenancy
    • Allow group <group-name> to read metrics in tenancy
    • Allow group <group-name> to manage functions-family in tenancy
    • Allow group <group-name> to use virtual-network-family in tenancy
    • Allow group <group-name> to use apm-domains in tenancy
    • Allow service faas to use apm-domains in tenancy

    If necessary, you can restrict these policy statements by compartment.

See Configuration Notes for more information.

B. Create application

1. Create your first application
  1. Sign in to the Console as a functions developer.
  2. In the Console, open the navigation menu and click Developer Services. Under Functions, click Applications.
  3. Select the region you are using with Oracle Functions.
  4. Click Create Application.
    This image shows the New Applicatoin dialog, with empty Name, VCN, and Subnets fields.
  5. Specify:
    • helloworld-app as the name for the new application. You'll deploy your first function in this application, and specify this application when invoking the function.
    • The VCN and subnet in which to run the function.
  6. Click Create.

See detailed instructions for more information.

C. Set up an OCI compute instance

1. Create instance and obtain OCID
  1. Sign in to the Console as a tenancy administrator.
  2. Open the navigation menu and click Compute. Under Compute, click Instances.
  3. Select the compartment in which to create network resources and Oracle Functions resources.
  4. If a suitable compute instance doesn't exist in the compartment already, click Create Instance and:
    • select the compartment, VCN, and subnets for use with Oracle Functions
    • specify that a public IP address is to be assigned to the new compute instance
    • select the file that contains the SSH key to access the new compute instance
  5. On the Instance Details page, copy the OCID and public IP address of the compute instance to use as the development environment.

See documentation for more information.

2. Create a dynamic group

Create a new dynamic group to include the compute instance:

  1. Open the navigation menu and click Identity & Security. Under Identity, click Dynamic Groups.
  2. Create a new dynamic group.
  3. Enter a rule that includes the compute instance's OCID:

    ANY {instance.id = '<instance-ocid>'}

See documentation for more information.

3. Create policy for dynamic group

Create a policy to give the new dynamic group access to function resources, network resources, and Oracle Cloud Infrastructure Registry:

  1. Open the navigation menu and click Identity & Security. Under Identity, click Policies.
  2. Click Create Policy and use the Policy Builder's manual editor to create a new policy with the following policy statements:

    • Allow dynamic-group <dynamic-group-name> to manage functions-family in compartment <compartment-name>
    • Allow dynamic-group <dynamic-group-name> to use virtual-network-family in compartment <compartment-name>
    • Allow dynamic-group <dynamic-group-name> to read repos in tenancy

See documentation for more information.

D. Set up your OCI compute instance dev environment

1. Install and start Docker

In a terminal window in your development environment:

  1. Confirm that Docker is installed by entering:
    docker version

    If you see an error message indicating that Docker is not installed, you have to install Docker before proceeding. See the Docker documentation for your platform (for Oracle Linux, see here).

    Assuming Docker is installed, go to the Prerequisites section of the Fn Project home page on GitHub and confirm that the installed version of Docker is at least the minimum version specified there. If not, re-install Docker before proceeding.

  2. Launch the standard hello-world Docker image as a container to confirm that Docker is running by entering:
    docker run hello-world

    If you see an error message indicating that Docker is not running, you have to start the Docker daemon before proceeding. See the Docker documentation.

See Configuration Notes for more information.

2. Install Fn Project CLI

In a terminal window in your development environment:

  1. Install the Fn Project CLI using the appropriate instructions below for your environment:
  2. Confirm that the Fn Project CLI has been installed by entering:
    fn version

See Configuration Notes for more information.

3. Set up Fn Project CLI context provider --oracle-ip

In a terminal window in your development environment:

  1. Create a new Fn Project CLI context by entering:
    fn create context <my-context> --provider oracle-ip

    Note that you specify --provider oracle-ip to enable authentication and authorization using instance OCIDs, dynamic groups, and policies granting permissions to those dynamic groups.

  2. Specify that the Fn Project CLI is to use the new context by entering:
    fn use context <my-context>

See Configuration Notes for more information.

4. Complete Fn Project CLI context configuration

In a terminal window in your development environment:

  1. Configure the new Fn Project CLI context with the OCID of the compartment you want to own deployed functions
    fn update context oracle.compartment-id <compartment-ocid>
  2. Configure the new context with the api-url endpoint to use when calling the OCI API by entering:
    fn update context api-url <api-endpoint>

    where <api-endpoint> is one of the endpoints in the list of Functions endpoints in Functions API, in the format https://functions.<region-identifier>.oci.oraclecloud.com. For example:

    fn update context api-url https://functions.us-phoenix-1.oci.oraclecloud.com
  3. Configure the Fn Project CLI context with the Oracle Cloud Infrastructure Registry address in the current region and tenancy that you want to use with Oracle Functions:

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

    where <repo-name> is a name of your choosing for the Oracle Cloud Infrastructure Registry repository in which to store containers for the function. For example:

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

See Configuration Notes for more information.

5. Generate auth token
  1. Sign in to the Console as a functions developer.
  2. Open the User menu and go to User Settings. On the Auth Tokens page, click Generate Token.
  3. Enter a meaningful description for the auth token in the Generate Token dialog, and click Generate Token. The new auth token is displayed.
  4. Copy the auth token immediately to a secure location from where you can retrieve it later, because you won't see the auth token again in the Console.
  5. Close the Generate Token dialog.

See Configuration Notes for more information.

6. Log in to Registry

In a terminal window in your development environment:

  1. Enter 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

    If your tenancy is federated with Oracle Identity Cloud Service, the format will be slightly different. For example:

    docker login -u 'ansh81vru1zp/oracleidentitycloudservice/jdoe@acme.com' phx.ocir.io
  2. When prompted for a password, enter the Oracle Cloud Infrastructure auth token that you created and copied earlier. For example, 6aN...6MqX

    You're now ready to start creating, deploying, and invoking functions.

See Configuration Notes for more information.

E. Create, deploy, and invoke your function

1. Create your first function

In the terminal window:

  1. Create a helloworld java function by entering:

    fn init --runtime java hello-java

    A directory called hello-java is created, containing:

    • a function definition file called func.yaml
    • a /src directory containing source files and directories for the helloworld function
    • a Maven configuration file called pom.xml that specifies the dependencies required to compile the function

    Java is just one of several supported languages.

    See detailed instructions for more information.

2. Deploy your first function

In the terminal window:

  1. Change directory to the hello-java directory created in the previous step:
    cd hello-java
  2. Enter the following single Fn Project command to build the function and its dependencies as a Docker image called hello-java, push the image to the specified Docker registry, and deploy the function to Oracle Functions in the helloworld-app application that you created earlier:
    fn -v deploy --app helloworld-app
  3. (Optional) Confirm that the function has been deployed to Oracle Functions by clicking Functions (under Resources on the details page for the helloworld-app application) and noting that the hello-java function now appears.

See detailed instructions for more information.

3. Invoke your first function

In the terminal window:

  1. Invoke the hello-java function by entering:

    fn invoke helloworld-app hello-java

    The 'Hello world!' message is displayed.

  2. Invoke the hello-java function with the parameter 'John' by entering:

    echo -n 'John' | fn invoke helloworld-app hello-java

    The 'Hello John!' message is displayed.

Congratulations! You've just created, deployed, and invoked your first function using Oracle Functions!

See detailed instructions for more information.

4. Next steps

Now that you've created, deployed, and invoked a function, learn how to:

You're done!