Running a function from local source

With this tutorial, run a function with the Code Engine CLI from code on your local system

A function is a stateless code snippet that performs tasks as it is invoked by HTTP requests. With IBM Code Engine functions, you can run your business logic in a scalable and serverless way. IBM Code Engine functions provide an optimized runtime environment to support low latency and rapid scale-out scenarios. Your function code can be written in a managed runtime that includes specific Node.js or Python versions.

A code bundle is a collection of files that represents your function code. This code bundle is injected into the runtime container. Your code bundle is created by Code Engine and is stored in container registry or inline with the function. A code bundle is not a Open Container Initiative (OCI) standard container image.

Before you begin

All Code Engine users are required to have a Pay-as-you-Go account. Tutorials might incur costs. Use the Cost Estimator to generate a cost estimate based on your projected usage. For more information, see Code Engine pricing.

Set up your environment

Log in to the IBM Cloud CLI.
```
ibmcloud login -r us-south
```
Target a resource group by running the following command. To see a list of your resource groups, run ibmcloud resource groups.
```
ibmcloud target -g <resource_group>
```
Example output
```
Targeted resource group default
```

Create a project in Code Engine called sample.

ibmcloud ce project create --name sample

Example output

Creating project 'sample'...
ID for project 'sample' is 'abcdabcd-abcd-abcd-abcd-abcd12e3456f7'.
Waiting for project 'sample' to be active...
Now selecting project 'sample'.
OK

Notice that your project is also selected for context, so all subsequent application-related commands are within the scope of this new sample project.

Become familiar with functions commands by viewing the command options.
```
ibmcloud ce fn --help
```

Create the source code

Create a Node.js source file called funhello.js with the following sample code.

  function main(params) {
      var msg = 'You did not tell me who you are.';
      if (params.name) {
          msg = `Hello, ${params.name}!`
       } else {
          msg = `Hello, Functions on CodeEngine!`
      }
      return {
          headers: { 'Content-Type': 'text/html; charset=utf-8' },
          body: `<html><body><h3>${msg}</h3></body></html>`
       }
  }

  module.exports.main = main;

Create your function

Create the function from the funhello.js file.

ibmcloud ce fn create --name funhello --runtime nodejs-18 --build-source funhello.js

Command output

Preparing function 'funhello' for build push...
Creating function 'funhello'...
Packaging files to upload from source path 'hello.js'...
Submitting build run 'funhello-run-230623-090738611'...
Creating image 'private.stg.icr.io/ce--8a6a0-13c66hbi3rhz/function-funhello:230623-1407-s8kzr'...
Waiting for build run to complete...
Build run status: 'Running'
Build run completed successfully.
Run 'ibmcloud ce buildrun get -n funhello-run-230623-090738611' to check the build run status.
Waiting for function 'funhello' to become ready...
Function 'funhello' is ready.
OK
Run 'ibmcloud ce function get -n funhello' to see more details.

https://funhello.13c66hbi3rhz.us-south.codeengine.appdomain.cloud

After the function invocation URL becomes available, use the following command to find information about the function.

ibmcloud ce fn get -n funhello

Let's take a deeper look at the previous function create command. Notice that the output of the function create command provides information about the progression of the build run before the function is created and deployed.

Code Engine receives a request to create an function from source code.
Code Engine checks for an IAM service ID and API key that is associated with the selected project. This service ID must be authorized to read and write to IBM Cloud Container Registry. If no service ID exists, Code Engine creates one for you. Note that this service ID is used for subsequent Code Engine build requests that are run from the same project.
This example builds code from a local source (--build-source). The source code (hello.js) is packed into a code-bundle file and uploaded to a managed namespace within the IBM Cloud Container Registry instance in your account. Note that you can target only IBM Cloud Container Registry for your local builds. For more information about IBM Container Registry, including information about quota limits and access, see Getting started with IBM Cloud Container Registry.
Code Engine builds your source code into a code bundle. The source code bundle is created in the same namespace as your source archive file.
After the build completes, your function is deployed. You can access your function from the provided URL.

Invoke your function

Invoke the function URL by pasting it into a browser window. You can also use the curl command in your command line.

Hello, Functions on CodeEngine!

You successfully created and invoked a Code Engine function!

Provide parameters for your function

Invoke the function URL with a parameter by adding ?name=Sunshine to the end of the URL and pasting it into a browser window.

https://funhello.13c66hbi3rhz.us-south.codeengine.appdomain.cloud?name=Sunshine

Hello, Sunshine!

Clean up

You can delete your function with the following command.

ibmcloud ce fn delete -n funhello

When you delete your function, the associated build files are also deleted.

Lastly, delete the code bundle that the build created from IBM Cloud Container Registry.

Navigate to Container Registry > Images in the IBM Cloud console.
Select the region in the Location drop-down menu which you selected when you logged on to IBM Cloud.
Find the image (which represents your code bundle) that is associated with your function by searching for your function name (for example, funhello).
Select the image (for example, au.icr.io/ce--27b98-1jp42v8n9n3o/function-funhello@sha256:b53683f47e0e548b4fa1d3fc93404399fdc4008b54ccecc0852794ea88d01538) and select Delete from the ellipses (...) menu.

Next steps

After your function is created, you can access your function by clicking Test function in the console or finding the URL for your function with the function get command.
You can create a custom domain mapping and assign it to your function.
After your function is created and deployed, you can update the function to meet your needs from the console or by using the ibmcloud ce function update command. If you want to update your source to use with your function, you must provide the --build-source option on the function update command.

After your function is created, you can update your function and its referenced code by using any of the following ways, independent of how you created or previously updated your function:

If you have an existing code bundle, then you need to provide only a reference to the image, which points to the location of your container registry when you deploy your app. For more information, see Creating function workloads from existing code bundles.

If you created your function by using the function create command and you specified the --build-source option to build the code bundle from local or repository source, and you want to change your function to point to a different code bundle, you must first remove the association of the build from your function. For example, run ibmcloud ce function update -n FUN_NAME --build-clear. After you remove the association of the build from your function, you can update the function to reference a different image.
If you are starting with source code that resides in a Git repository, you can choose to let Code Engine to build the code bundle from your source and create your function with a single operation. In this scenario, Code Engine uploads your code bundle to IBM Cloud® Container Registry. To learn more, see Creating your function from repository source code.
If you are starting with source code that resides on a local workstation, you can choose for Code Engine to build the code bundle from your source and create your function with a single CLI command. In this scenario, Code Engine uploads your source code and code bundle to IBM Cloud® Container Registry.

For example, you might choose for Code Engine to build your local source while you evolve the development of your source for the function. Then, after the code bundle is matured, you can update your function to reference the specific code bundle that you want. You can repeat this process as needed.

Looking for more code examples? Check out the Samples for IBM Cloud Code Engine GitHub repo.