Oracle Cloud Infrastructure Documentation

Updating Code-only Functions

Find out how to update code-only functions in OCI Functions, including replacing archives, changing handlers, and updating runtime settings.

Update a code-only function when you need to change the archive, configuration, runtime settings, handler, or tags.

You cannot change a code-only function into a container image-based function. You also cannot change a container image-based function into a code-only function. To change between code-only and image-based function deployment models, create a new function.

Before updating a code-only function, you need:

  • An existing code-only function.
  • Permissions to update the function.
  • An updated archive, if changing source code or dependencies.
  • If using Object Storage, access to the bucket, object, and object version, if applicable.
  • If using Object Storage, an IAM policy that allows the OCI Functions application resource principal to read the archive object.

Updating the archive

If you have changed the function code or its dependencies, first rebuild or repackage the function archive. Then, update the function definition to refer to the new function archive.

Using the Console

Having rebuilt or repackaged a function archive, you can use the Console to update the function definition to refer to the new function archive.

  1. On the Applications list page, select the application that contains the function that you want to work with. If you need help finding the list page or the application, see Listing Applications.

  2. Select the Functions tab.

    The Functions list page opens. All functions in the selected application are displayed in a table.

  3. From the Actions menu (three dots) for the function that you want to update, select Edit.
  4. Select the Change source code option, and update File Source details as follows:
    • Select from object storage: Select the Object Storage compartment and bucket that contains the archive, and specify the name and version (if applicable) of the archive. Maximum file size is 250 MB.
    • Upload from your device: Select the archive file, or drag and drop the file into the box. Maximum file size is 25 MB.
    • Runtime: Select a supported runtime to determine the managed execution environment used by OCI Functions.
    • Handler: If the runtime you select requires a handler, enter the handler. For some runtimes, a code-only function requires a handler. The handler identifies the entry point in the function archive that OCI Functions calls when the function is invoked.

      For Java, Python, and Node.js code-only functions, you must specify a handler when you create the function.

      Go code-only functions do not use a separate handler value. The archive must contain a Linux executable named func in the required location.

  5. Update other function properties if required.
  6. Select Save changes to update the function in the OCI Functions server.

Using the CLI

Using the OCI CLI

Having rebuilt or repackaged a function archive, you can use the OCI CLI to update the function definition to refer to the new function archive.

  • Update the archive in Object Storage that a code-only function uses by entering:

    oci fn function update archive-function --function-id <function-id> --bucket-name <bucket-name> --namespace <namespace> --object-name <object-name>

  • Update the uploaded archive file that a code-only function uses by entering:

    oci fn function update archive-function --function-id <function-id> --archive-file file:/<archive-file-path>

You can also change a code-only function that uses an archive in Object Storage to use an uploaded archive file, and vice versa:

  • Change a code-only function that uses an archive in Object Storage to use an uploaded archive file instead by entering:
    oci fn function update archive-function --function-id <function-id> --archive-file file:/<archive-file-path>
  • Change a code-only function that uses an uploaded archive file to use an archive in Object Storage instead by entering:
    oci fn function update archive-function --function-id <function-id> --bucket-name <bucket-name> --namespace <namespace> --object-name <object-name>

Using the Fn Project CLI

Tip

From time to time, new versions of the Fn Project CLI are released. We recommend you regularly check that the latest version is installed. For more information, see Steps to upgrade the Fn Project CLI.

Having rebuilt or repackaged a function archive, you can use the Fn Project CLI to update the function definition to refer to the new function archive.

  • Update the archive in Object Storage that a code-only function uses by entering:

    fn update function <app-name> <function-name> --code-only --source-type object-storage --bucket-name <bucket-name> --namespace <namespace> --object-name <object-name>

  • Update the uploaded archive file that a code-only function uses by entering:

    fn update function <app-name> <function-name> --code-only --source-type direct --source-file <path-to-function-source.zip>

You can also change a code-only function that uses an archive in Object Storage to use an uploaded archive file, and vice versa:

  • Change a code-only function that uses an archive in Object Storage to use an uploaded archive file instead by entering:
    fn update function <app-name> <function-name> --code-only --source-type direct --source-file <path-to-function-source.zip>
  • Change a code-only function that uses an uploaded archive file to use an archive in Object Storage instead by entering:
    fn update function <app-name> <function-name> --code-only --source-type object-storage --bucket-name <bucket-name> --namespace <namespace> --object-name <object-name>

Using the API

Having rebuilt or repackaged a function archive, run the UpdateFunction API operation to update the function definition to refer to the new function archive.

Updating the handler

For Java, Python, and Node.js code-only functions, the entry point in the archive that OCI Functions calls when the function is invoked is identified by the value of the Handler property. If the entry point in the archive changes, change the value of the Handler property accordingly.

For example, change the value of the Handler property if:

Runtime Change in archive Example Handler property value
Java The class or method name changes com.example.NewFunction::handleRequest
Python The handler file or function name changes new_func.handler
Node.js The handler JavaScript file changes new_func.js

Note that Go code-only functions do not use a handler. For Go code-only functions, the archive must contain a Linux executable named func in the required location.

Before changing the value of the Handler property:

  • Confirm that the new entry point exists in the archive.
  • Confirm that the value you specify for the Handler property uses the format required by the runtime.
  • Rebuild or repackage the archive if the function code changed.

For example, having changed the handler, you can use the Console to change the value of the Handler property as follows:

  1. On the Applications list page, select the application that contains the function that you want to work with. If you need help finding the list page or the application, see Listing Applications.

  2. Select the Functions tab.

    The Functions list page opens. All functions in the selected application are displayed in a table.

  3. From the Actions menu (three dots) for the function that you want to update, select Edit.
  4. Select the Change source code option, and change the value of the Handler property as required.

    If the archive also changed, upload a different archive or select a different Object Storage object.

Managing code-only function runtimes

Find out how to manage code-only function runtimes by setting the runtime update mode.

Managed runtime updates

Code-only functions use managed runtimes. OCI Functions owns managed runtime patching and publishes updated runtime versions. You control when a code-only function moves to a newer compatible runtime version by setting the runtime update mode.

Managed runtime updates can include operating system updates, language runtime updates, Function Development Kit (FDK) updates, security fixes, and other platform-managed runtime changes. You are responsible for testing that your function code and packaged dependencies remain compatible with the runtime version that the function uses.

OCI Functions is responsible for maintaining the managed runtime (including operating system updates, language runtime updates, FDK updates, security fixes, and other platform-managed runtime changes). You are responsible for your function code, application dependencies, and validating compatibility with runtime updates.

Supported code-only function runtimes

Code-only functions support the following managed runtimes:

  • Go (for Go code-only functions, you provide a statically linked, self-contained Linux executable binary and OCI Functions provides the supported Oracle Linux runtime environment)
  • Java
  • Node.js
  • Python

Ruby and C# are not supported for code-only functions.

For the supported runtime versions, see Languages Supported by OCI Functions.

Runtime update modes

The runtime update mode controls how a code-only function adopts managed runtime updates. Specify the runtime update mode when you create a code-only function. If required, you can subsequently update the function to change the runtime update mode.

Runtime update mode Description Use when
Function update The function moves to the current supported compatible runtime version when you update the function. The function does not move to a newer runtime version until you update the function. You want the function to adopt newer compatible runtime versions as part of normal function updates.
Manual The function is pinned to a specific supported runtime version until you explicitly change the runtime version (or change the runtime update mode). You want to test and control exactly which runtime version the function uses.

Function update mode is not the same as fully automatic runtime upgrades. In Function update mode, the function moves to a newer compatible runtime version only when you update the function.

Runtime updates apply only to compatible runtime versions for the selected runtime. For Python runtimes, compatible updates include patch versions for the selected Python minor version. For Java and Node.js runtimes, compatible updates include minor and patch versions for the selected runtime family. For Go code-only functions, OCI Functions provides the supported Oracle Linux runtime environment, but you provide the compiled Go executable.

Use Manual mode when you need to keep the function on a specific runtime version. For example, use Manual mode if you want to test a newer runtime version in another environment before updating a production function.

Note

Runtime versions specified for a function must belong to the selected runtime and must be active. Fully automatic runtime upgrades are not supported. Function update mode moves the function to a newer compatible runtime version only when you update the function. Manual mode keeps the function on the selected runtime version until you change it.

Runtime lifecycle and deprecation

OCI Functions publishes managed runtime versions for supported code-only function runtimes. Runtime versions can be deprecated and decommissioned as the underlying language runtime or operating system reaches the end of the supported lifecycle.

The deprecation date is the date when OCI Functions stops providing updates, security patches, and active support for the runtime version. The decommission date is the date when the runtime version is removed from the platform and is no longer available for new deployments.

Before selecting or pinning a runtime version, review the lifecycle information for the language runtime and operating system used by the managed runtime.

  • For Java, Python, and Node.js code-only functions, review the lifecycle information for the language runtime and the Oracle Linux runtime environment (see Languages supported for code-only functions).
  • For Go code-only functions, review the lifecycle information for the Oracle Linux runtime environment. Go code-only functions use statically linked, self-contained Linux executable binaries, so OCI Functions does not provide a Go language runtime at invocation time. For Oracle Linux 9 lifecycle dates, see the Oracle Linux support lifecycle information.

Runtime lifecycle dates and the actions allowed in each lifecycle phase are subject to change. Review the supported runtime information before creating a function, updating a function, or pinning a function to a runtime version.

The following table summarizes the behavior of OCI Functions across different phases of the runtime lifecycle and shows the actions permitted or restricted during each phase across all supported runtime versions. The decommission date is planned to be six months after deprecation, with notifications provided via the OCI Console and Fn Project CLI.

Action Before runtime deprecation Between runtime deprecation and decommission After runtime decommission
New function creates or deployments Allowed Not allowed Not allowed
Updates to existing functions Allowed Allowed Not allowed, except for changing the function to use a supported runtime
Invocations of existing functions Allowed Allowed Allowed
List, read, and delete functions Allowed Allowed Allowed
Support and patches Full support, including security and bug fixes No support No support

Rolling back after a runtime update

Code-only functions can use active runtime versions that are in a supported lifecycle phase. Although OCI Functions manages runtime updates, compatibility risks can remain, as with any software update.

If a production function uses Function update mode and starts failing after it moves to a newer runtime version, you can mitigate impact by switching the function to Manual mode and selecting an active, previously published compatible runtime version, such as the most recent prior version that worked with the function.

After switching to Manual mode, open a Support request for investigation and guidance. You can continue operating the function in Manual mode while the issue is investigated. Oracle Support will assess the reported issue and provide guidance about the appropriate path forward, including assistance with adopting a newer runtime version if required.

Using the Console

To set the runtime update mode using the Console

  1. On the Applications list page, select the application that contains the function that you want to work with. If you need help finding the list page or the application, see Listing Applications.

  2. Select the Functions tab.

    The Functions list page opens. All functions in the selected application are displayed in a table.

  3. From the Actions menu (three dots) for the function that you want to update, select Edit.

  4. In Runtime version management configuration, set the function's runtime update mode:

    • Select Function update mode to move the function to the latest compatible runtime version when the function is updated.
    • Select Manual mode to pin the function to a specific runtime version. If you select Manual, select a valid runtime version for the selected runtime.
  5. Select Save changes to update the function in the OCI Functions server.

Using the CLI

Using the OCI CLI

You can use the OCI CLI to set the runtime update mode when creating a code-only function. For example:

  • To create a code-only function that uses Function update runtime update mode (and that uses an archive stored in Object Storage), enter:

    oci fn function create archive-function object-storage fn-update-runtime-config --application-id <app-id> --bucket-name <bucket-name> --display-name <display-name> --functions-runtime-name <functions-runtime-name> --memory-in-mbs <memory> --namespace <namespace> --object-name <object-name>

  • To create a code-only function that uses Manual runtime update mode (and that uses an archive stored in Object Storage), enter:

    oci fn function create archive-function object-storage manual-runtime-config --application-id <app-id> --bucket-name <bucket-name> --display-name <display-name> --functions-runtime-name <functions-runtime-name> --functions-runtime-version-id <functions-runtime-version-id> --memory-in-mbs <memory> --namespace <namespace> --object-name <object-name>

You can also use the OCI CLI to change the runtime update mode for an existing code-only function:

  • Change the runtime update mode of an existing code-only function from Manual to Function update by entering:

    oci fn function update archive-function --function-id <function-ocid> --runtime-config FUNCTION_UPDATE --functions-runtime-name <runtime-name>  --handler <handler>

  • Change the runtime update mode of an existing code-only function from Function update to Manual by entering:

    oci fn function update archive-function --function-id <function-ocid> --runtime-config MANUAL --functions-runtime-name <runtime-name> --functions-runtime-version-id <runtime-version-ocid> --handler <handler>

Using the Fn Project CLI

Tip

From time to time, new versions of the Fn Project CLI are released. We recommend you regularly check that the latest version is installed. For more information, see Steps to upgrade the Fn Project CLI.

You can use the Fn Project CLI to set the runtime update mode for a code-only function using the --runtime-config-type option when creating or updating the function. For example:

  • To update a code-only function to use Function update runtime update mode, enter:

    fn update function <app-name> <function-name> \
  --code-only \
  --runtime-config-type function-update \
  --runtime-name <runtime-name>

  • To update a code-only function to use Manual runtime update mode, enter:

    fn update function <app-name> <function-name> \
  --code-only \
  --runtime-config-type manual \
  --runtime-name <runtime-name> \
  --runtime-version-id <runtime-version-ocid>

    To find out the OCID of the runtime version, enter

    fn list runtime-versions --runtime-name <runtime-name> --output json

Using the API

Run the CreateFunction and UpdateFunction API operations to set and change the runtime update mode for code-only functions.

Troubleshooting

ProblemLikely causeRecommended fix
Function update failsArchive does not match required runtime or architecture structureRepackage the archive using the runtime-specific topic.
Object Storage archive cannot be readMissing or incorrect Object Storage read policyAdd or correct the policy for the OCI Functions application resource principal.
Handler error after updateHandler value no longer matches packaged codeUpdate the handler or repackage the archive.
Runtime version errorRuntime version does not match selected runtime or is not activeSelect a valid runtime version.
Deployment model change is not available Changing between code-only and image-based deployment models is unsupportedCreate a new function with the required deployment model.