Oracle Cloud Infrastructure Documentation

Functions QuickStart on Cloud Shell

Find out how to get set up and running quickly on Cloud Shell using this OCI Functions QuickStart.

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 select Identity & Security. Under Identity, select Domains.
  3. Select a domain, and select the User management tab.
  4. Create a new group by selecting Create group in the Groups section.
  5. Create a new user by selecting Create in the Users section.
  6. Add a user to a group by selecting the name of the group, and then Assign user to group on the Users tab.

See Configuration Notes for more information.

2. Create compartment

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

  1. Sign in to the Console as a tenancy administrator.
  2. Open the navigation menu  and select Identity & Security. Under Identity, select Compartments.
  3. Select Create Compartment.

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 , select Networking, and then select Virtual cloud networks.
  3. Select Start VCN Wizard from the Actions menu to create a new VCN.
  4. In the Start VCN Wizard panel, select Create VCN with Internet Connectivity and select Start VCN Wizard.
  5. Enter a name for the new VCN, select Next, and then select 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 OCI Functions users is not a tenancy administrator:

  1. Sign in to the Console as a tenancy administrator.
  2. Open the navigation menu  and select Identity & Security. Under Identity, select Policies.

  3. Select 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.

    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 group <group-name> to read vaults in tenancy
    • Allow group <group-name> to use keys in tenancy
    • Allow service faas to use apm-domains in tenancy
    • Allow service faas to read repos in tenancy where request.operation='ListContainerImageSignatures'
    • Allow service faas to {KEY_READ} in tenancy where request.operation='GetKeyVersion'
    • Allow service faas to {KEY_VERIFY} in tenancy where request.operation='Verify'

    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. Open the navigation menu  and select Developer Services. Under Functions, select Applications.
  3. Select the region you're using with OCI Functions.
  4. Select Create application.
  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. Note that a public subnet requires an internet gateway in the VCN, and a private subnet requires a service gateway in the VCN.
  6. Select Create.

See detailed instructions for more information.

C. Set up your Cloud Shell dev environment

1. Display the Cloud shell setup panel and the Cloud Shell window

On the Applications list page in the Console:

  1. Select the helloworld-app application you just created to display the application details page.

  2. Go to the Getting Started section, and then select View Guide beside Cloud Shell Setup.

    Tip: The Cloud shell setup panel now displays commands tailored specifically for you. You copy and paste these commands to configure your Cloud Shell environment for functions development.

  3. Select Launch cloud shell to display the Cloud Shell terminal window.
2. Set up Fn Project CLI context

Copy and paste commands from the Cloud shell setup panel into the Cloud Shell terminal window to configure your environment, as follows:

  1. Find the name of the pre-created Fn Project context for the current region in which you created the application:

    fn list context

    At least two Fn Project contexts are returned, a default context and a context for the current region (for example, named us-phoenix-1).

  2. Set the Fn Project context to use the region context:

    fn use context <region-context>

    where <region-context> is the context for the current region. For example:

    fn use context us-phoenix-1

  3. Configure the Fn Project context with the OCID of the current compartment that will own deployed functions:

    fn update context oracle.compartment-id <compartment-ocid>

    For example:

    fn update context oracle.compartment-id ocid1.compartment.oc1..aaaaaaaarvdfa72n...

  4. Configure the Fn Project context with the Oracle Cloud Infrastructure Registry address in the current region and tenancy that you want to use with OCI Functions:

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

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

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

  5. Configure the Fn Project context with the OCID of the compartment for repositories to and from which you want OCI Functions to push and pull function images, by entering:

    fn update context oracle.image-compartment-id <compartment-ocid>

    For example:

    fn update context oracle.image-compartment-id ocid1.compartment.oc1..aaaaaaaaquqe______z2q

    If you do not specify a value for oracle.image-compartment-id, OCI Functions pushes and pulls images to and from repositories in the root compartment.

See Configuration Notes for more information.

3. Generate auth token

On the Cloud shell setup panel in the Console:

  1. Select Generate an auth token to display the Auth Tokens page, and select Generate Token.
  2. Enter a meaningful description for the auth token in the Generate Token dialog, and select Generate Token. The new auth token is displayed (for example, 6aN...6MqX).
  3. 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.
  4. Close the Generate Token dialog.

See Configuration Notes for more information.

4. Log in to Registry

On the Cloud shell setup panel in the Console:

  1. Copy 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. In the terminal window, paste the command you just copied and run it.

  3. 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.

D. 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 OCI 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 OCI Functions by selecting the Functions tab (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 OCI 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!