Working with functions

Function limitations

• No support for subscribing to event producers.
• No support for Terraform.

How do I make my code run as a Code Engine function component?

Whether your code exists as source in a local file or in a Git repository, or your code is an existing code bundle that is located in a public or private registry, Code Engine provides a streamlined way for you to run your code as a function.

• If you are starting with source code that is located in a Git repository, you can choose to point to the location of your source, and Code Engine takes care of building the code bundle from your source and creating the function with a single operation. In this scenario, Code Engine uploads your code to IBM Cloud® Container Registry. To learn more, see Creating a function from repository source code.

• If you are starting with source code on a local workstation, you can choose to point to the location of your source, and Code Engine takes care of building the image from your source and creating the function with a single CLI command. In this scenario, Code Engine uploads your code to IBM Cloud® Container Registry. To learn more, see Creating your function from local source code with the CLI.

• If you are starting with source code, you can also run your source code inline. In this scenario, you paste in your source code when you create your function. For more information, see Creating your function with inline code.

After you create and run your function, you can also update your function by using any of the preceding ways, independent of how you created or previously updated your function.

What happens when I invoke my function?

When a function is invoked (started), the corresponding Function instance is initialized with the configured Runtime container and Resource parameters. The process of the first initialization is referred to as cold start.

To reduce the cold start latency, Code Engine optimizes the invocation by pre-warming certain runtimes with specific CPU and memory configurations. Pre-warmed combinations for functions include Node.js 18 and Python 3.11 versions as well as the default CPU and memory combination for Functions, which is 0.25 vCPU x 1 GB of memory. In addition, the system is designed to improve the reuse of Function instances that are already initialized. Therefore, a Function instance is kept alive after the invocation is finished to allow subsequent invocations by reusing the same instance and reusing the state of the instance when the last invocation completed. The reuse of a Function instance is not guaranteed.

Can I keep my function instance alive longer?

With Code Engine, your function scales up and down automatically, based on workload. When you create your function with the default CPU and memory combination, your function is injected into a "pre-warmed" container, which is optimized for use. When you create a function with a CPU and memory combination other than the default combination, then your function is injected into a new container. By default, this container is kept alive for only a short amount of time after the function completes. For more information, see Supported CPU and memory combinations for functions.

You can change the amount of time that your container is kept alive with the --scale-down-delay option in the CLI or the Scale-down delay option in the console. Note that while keeping your container alive reduces the cold start times for any subsequent run of your function, you are also billed for the amount of time that the custom function container exists.

Requests and responses

Functions are invoked with the HTTP protocol. When you invoke your function, you can specify the custom request parameters, custom request body and headers, as well as the HTTP method. The request parameters are made available to the function code as input parameters. The function code can set the response body, response headers, and response code, which are returned to the caller from the functions endpoint.

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

  module.exports.main = main;

function main(params) {
    return {
        headers: { location: 'https://cloud.ibm.com/docs/codeengine' },
        statusCode: 302
    }
}

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

Error handling and debugging

Function invocations can return system or application errors. For example, system errors indicate that the function code did not execute successfully, while application errors indicate a problem in the function code itself.

When a system error occurs, an HTTP response code similar to the following codes is returned.

If Code Engine can execute the functions code, it responds to the invocation with one of the following status codes.

As a developer of a function, you can generate any arbitrary HTTP status code, even the ones listed previously. Therefore, a response header indicates that the status code was generated by the function code.

Code Engine functions adds the following response headers to the function invocation response.

Function data input/output characteristics

To run your function in Code Engine, your code must implement a runtime contract with the following characteristics.

• Must be callable from a public web application endpoint, so that it can be embedded with web pages and then invoked from any Code Engine Eventing source, a Web Browser, or any other HTTPS capable client.
• Must implement a main procedure as entry point. The main procedure can receive input parameters in form of a JSON formatted data structure and can return output parameters, also in form of a JSON formatted data structure.
• Can receive an optional sub path, so that the function can implement different flavors, based on the specified path. The function's main procedure receives the path as a __ce_path input parameter.
• Can receive optional query parameters, which can be used to configure the function at runtime. The function's main procedure receives the parameters as key-value pairs within the JSON formatted input data structure.
• Can receive request headers, so that client code can specify accepted encodings.
• Can receive an optional content-type request header.
• Can receive an optional request payload (body), which the function processes at runtime. Depending on the selected request content-type, the data payload is passed to the function's main entry point, either in base 64 encoded form or "unfolded" as part of the JSON input data structure. Special characters in keys values pairs of application/x-www-form-urlencoded input are percent-encoded values.
• Can define an arbitrary HTTP status code (optional) that is then returned to the invoking client.
• Can set arbitrary response headers, such as a redirect location, a response encoding, or cookie values.
• Can return an arbitrary response body with a selected binary or non-binary encoding; for example, application/octet-stream, application/json, text/*, image/*, or audio/*. If no content-type response header is set, it defaults to text/plain.
• Supports the following request content-types: application/x-www-form-urlencoded (default), text/plain, application/json, application/octet-stream, image/*, audio/*
• Does not support the multipart/form-data request header.

Options for visibility for a Code Engine function

With Code Engine, you can determine the right level of visibility for your function by defining the endpoints, or system domain mappings that are available for receiving requests.

Every function has an internal system domain mapping that is visible to all components within the same Code Engine project, but not outside of the project. In addition to the internal system domain mapping, you choose to make the function visible to either the public internet or the IBM Cloud private network.

For public or private visibility, the function is exposed on an HTTPS endpoint. For details about the TLS certificate that is used, see TLS certificates for Code Engine projects.

You can deploy your function with the following visibility levels:

You can set the endpoint settings for visibility of a function from the console or with the CLI when you create and deploy, or update your function.

Options for creating functions

Learn about the options that you can specify when you create your function. Note that options can vary between the console and the CLI.

Considerations for functions quotas

When you work with applications, functions, and batch jobs, these resources run within the context of a Code Engine project. Resource quotas are defined on a per project basis, and limits apply for applications, functions, and batch jobs.

For more information about Code Engine limits, see Limits and quotas for Code Engine.

Next steps

Now that you are familiar with key concepts of working with Code Engine functions, are you ready to create and work with functions? See the following topics.

• Creating function workloads with inline code.
• Creating function workloads with repository source code.
• Creating function workloads from local source code.

For more information about working with functions, see the following topics.

• Function workloads.
• Integrating IBM Cloud services with service bindings.
• Working with environment variables, configmaps, and secrets.
• Troubleshooting functions.