Creating function workloads with repository source code

You can create your function directly from source code that is located in a Git repository from the IBM Cloud® Code Engine console or with the CLI.

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.

In this scenario, Code Engine builds a code bundle from your Git repository source, automatically uploads the code bundle to your container registry, and then creates your function to reference this built code bundle. You need to provide only a name for the function, the URL to the Git repository, and the runtime for the function. In this case, Code Engine manages the namespace for you. However, if you want to use a different container registry, then you must specify the code bundle and a registry secret for that container registry.

For information about required permissions for accessing image registries, see Setting up authorities for image registries.

Creating function workloads with repository source code from the console

Create a function with source code from the console.

Open the Code Engine console.
Select Let's go.
Select Function.
Enter a name for the function; for example, myfunction. Use a name for your function that is unique within the project.
Select a project from the list of available projects. You can also create a new one. You must select a project to create a function.
Select a Runtime image for your function code. For more information, see Runtimes.
Select to Build code bundle from source code. When you select this option, your function is created from source code and stored in container registry.
Select a source repository, for example https://github.com/IBM/CodeEngine. If you choose to use the sample source, you do not need require credentials so you can select None for the Code repo access. You can optionally provide a branch name. If you do not provide a branch name and you leave the field empty, Code Engine automatically uses the default branch of the specified repository. Click Next.
Select a strategy for your build and resources for your build. For more information about build options, see Planning your build. Click Next.
Select a container registry location, such as IBM Registry Dallas to specify where to store the image of your build output. If your registry is private, you must set up access to it.
Provide registry information about where to store the image of your build output. Select an existing Registry secret or create a new one. If you are building your image to a Container Registry instance that is in your account, you can select Code Engine managed secret and let Code Engine create and manage the secret for you.
Select a namespace, name, and a tag for your image. If you are building your image to an IBM Cloud Container Registry instance that is in your account, you can select an existing namespace or let Code Engine create and manage the namespace for you. For additional help, click Help me specify the code bundle. For more information, see Accessing container registries.
Specify your resource information, including CPU and memory combinations and Scale down delay.
Optionally, specify a custom domain or environment variables. You can add these options later.
Click Create.
After the function status changes to Ready, you can test the function. Click Test function and then click Send request. To open the function in a web page, click Function URL.
You can also change your function code in the Editor window. When you redeploy your function, the code is stored inline.

You can invoke your function by clicking Test function and then Send request.

Creating function workloads with repository source code with the CLI

Use the function create command to both build a code bundle from your Git repository source, and create your function to reference this built code bundle. For a complete listing of options, see the ibmcloud ce function create command.

Before you begin

Set up your Code Engine CLI environment.
Create and work with a project.

The following example function create command creates the myfun function, which references code that is located in https://github.com/IBM/CodeEngine. This command automatically builds the code bundle and uploads it to an IBM Cloud® Container Registry namespace in your account. The function references this built code bundle. By specifying the --build-context-dir option, the build uses the source in the helloworld-samples/function-nodejs directory.

ibmcloud ce function create --name myfun --runtime nodejs-18 --build-source https://github.com/IBM/CodeEngine --build-context-dir /helloworld-samples/function-nodejs

Example output

Preparing function 'myfun' for build push...
Creating function 'myfun'...
Submitting build run 'myfun-run-230111-111212718'...
Creating image 'icr.io/ce--abcde-glxo4kabcde/function-myfun:230111-1532-vwo4o'...
Waiting for build run to complete...
Build run status: 'Running'
Build run completed successfully.
Run 'ibmcloud ce buildrun get -n myfun-run-230111-111212718' to check the build run status.
Waiting for function 'myfun' to become ready...
Function 'myfun' is ready.
OK                                                
Run 'ibmcloud ce function get -n myfun' to see more details.

https://myfun.11a66hbi3rhz.us-south.codeengine.appdomain.cloud

Notice the output of the function create command provides information on the progression of the build run before the function is created.

In this example, the built code bundle is uploaded to the ce--abcde-4svg40kna19 namespace in Container Registry.

The following table summarizes the options that are used with the function create command in this example. For more information about the command and its options, see the ibmcloud ce function create command.

Table 1. Command description
Option	Description
`--name`	The name of the function. Use a name that is unique within the project. This value is required. The name must begin with a lowercase letter. The name must end with a lowercase alphanumeric character. The name must be 63 characters or fewer and can contain letters, numbers, and hyphens (-).
`--build-source`	The URL of the Git repository that contains your source code; for example, `https://github.com/IBM/CodeEngine`.
`--build-context-dir`	The directory in the repository that contains the code. This value is optional.
`--runtime`	The runtime for the function.

The following output shows the result of the function get command for this example, including information about the build.

Example output

Getting function 'myfun'
'...
OK

Name:          myfun  
Project Name:  sample  
Project ID:    abcdefgh-abcd-abcd-abcd-1a2b3c4d5e6f  
Age:           27m  
Created:       2023-06-27T21:07:26Z  
URL:           https://myfun.13c66hbi3rhz.us-south.codeengine.test.appdomain.cloud  
Status:        Ready  

Resources:    
  CPU:                 0.25  
  Memory:              500M  
  Max Execution Time:  60 seconds  

Build Information:    
  Build Run Name:     myfun-run-230111-111212718  
  Build Type:         git  
  Build Strategy:     codebundle-nodejs-18  
  Timeout:            600  
  Source:             https://github.com/IBM/CodeEngine  
  Context Directory:  /helloworld-samples/function-nodejs    
                      
  Build Run Summary:  Succeeded  
  Build Run Status:   Succeeded  
  Build Run Reason:   All Steps have completed executing  
  Run 'ibmcloud ce buildrun get -n myfun-run-230111-111212718' for details.  

Function Code:    
  Runtime:        nodejs-18 (managed)  
  Bundle Secret:  ce-auto-icr-us-south  
  Code Bundle:    cr://icr.io/ce--abcde-glxo4kabcde/function-myfun:230111-1532-vwo4o 
  Main:           main()

Now that your function is created from repository source code, you can update the function to meet your needs 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.

When your function is created from repository source code or from local source with the CLI, the resulting build run is not based on a build configuration. Build runs that complete are ultimately automatically deleted. Build runs that are not based on a build configuration are deleted after 1 hour if the build run is successful. If the build run is not successful, this build run is deleted after 24 hours. You can only display information about this build run with the CLI. You cannot view this build run in the console.

Including dependencies for your function

You can create functions in many different programming languages. When your function code grows complex, you can add code modules as dependencies for your function. Each language has its own modules to use with your function code. For example, Node.js dependencies are usually existing npm modules, whereas Python uses Python packages. These dependencies must be declared and created in a file with your source code

Including modules for a Node.js function

Create a function that includes a dependency for a specific Node.js module by creating a package.json file. In this case, both the source code and package file are located in the same folder.

Create your source code by writing your code into a main.js file. For example, copy the following code example into a file called main.js.

/**
* The `main` function is the entry-point into the function.
* It has one optional argument, which carries all the 
* parameters the function was invoked with.
*/
function main(params /* optional */) {
  // use third-party 'lorem-ipsum' package to generate random words
  const LoremIpsum = require("lorem-ipsum").LoremIpsum;
  const lorem = new LoremIpsum();

  // Since functions are invoked through http(s), we return an HTTP response.
  return {
    headers: { "Content-Type": "text/plain;charset=utf-8" },
    body: lorem.generateWords(10),
  };
}

// This step is necessary, if you gave your main function a different name.
// We include it here for documentation purposes only.
module.exports.main = main;

Create a package.json file that contains the required dependencies for your function. For the previous code example, use the following contents for your package.json file.
```
{
  "name": "function",
  "version": "1.0.0",
  "main": "main.js",
  "dependencies" : {
		    "lorem-ipsum" : "2.0.8"
 	}
}
```
Create your files as a function in Code Engine. Both of previous files must be accessible in the repository. If they are in a private repository, create private code repository access and then provide that value with the --build-git-repo-secret option. If your files are located in a directory other than main, provide the path to the directory with the --build-context-dir option. The following example pulls the files from the https://github.com/IBM/CodeEngine public repository.
```
ibmcloud ce fn create -n nodelorem -runtime nodejs-18 --build-source https://github.com/IBM/CodeEngine --build-context-dir /helloworld-samples/function-codebundle-nodejs/
```
Run the provided fn get command to find details about your function.
Invoke your function by pasting the URL into a web browser. Your browser displays a passage of lorem ipsum.

For more information about the fn create command and its options, see Create a function.

Including modules for a Python function

Create a function that includes a dependency for a specific Python module by creating a requirements.txt file. In this case, both the source code and requirements file are located in the same folder.

Create your function by saving your code into a __main__.py file

# use third-party 'lorem-ipsum' package to generate random words
from lorem_text import lorem

# The `main` function is the entry-point into the function.
# It has one optional argument, which carries all the 
# parameters the function was invoked with.
def main(params):
    words = 10

    # since functions are invoked through http(s), we return an HTTP response
    return {
      "headers": {
        "Content-Type": "text/plain;charset=utf-8",
    },
    "body": lorem.words(words),
}
def main(params):
     words = 10

     return {
          "headers": {
              "Content-Type": "text/plain;charset=utf-8",
          },
          "body": lorem.words(words),
      }

Create a requirements.txt containing your required dependencies for your function
```
lorem-text
```
Create your files as a function in Code Engine. Both of previous files must be accessible in the repository. If they are in a private repository, create private code repository access and then provide that value with the --build-git-repo-secret option. If your files are located in a directory other than main, provide the path to the directory with the --build-context-dir option. The following example pulls the files from the https://github.com/IBM/CodeEngine public repository.
```
ibmcloud ce fn create -n pylorem -runtime python-3.11 --build-source https://github.com/IBM/CodeEngine --build-context-dir /helloworld-samples/function-codebundle-python/
```
Run the provided fn get command to find details about your function.
Invoke your function by pasting the URL into a web browser. Your browser displays a passage of lorem ipsum.

For more information about the fn create command and its options, see Create a function.

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.