Function's specification

Serverless in Kyma allows you to create Functions in both Node.js (v14 & v16) and Python (v3.9). Although the Function's interface is unified, its specification differs depending on the runtime used to run the Function.

Signature

Function's code is represented by a handler that is a method that processes events. When your Function is invoked, it runs this handler method to process a given request and return a response.

All Functions have a predefined signature with elements common for all available runtimes:

  • Functions' code must be introduced by the main handler name.
  • Functions must accept two arguments that are passed to the Function handler:
    • event
    • context

See these signatures for each runtime:

  • Node.js
  • Python

Event object

The event object contains information about the event the Function refers to. For example, an API request event holds the HTTP request object.

Functions in Kyma accept CloudEvents (ce) with the following specification:

  • Node.js
  • Python

See the detailed descriptions of these fields:

FieldDescription
ce-typeType of the CloudEvent data related to the originating occurrence
ce-sourceUnique context in which an event happened and can relate to an organization or a process
ce-eventtypeversionVersion of the CloudEvent type
ce-specversionVersion of the CloudEvent specification used for this event
ce-idUnique identifier of the event
ce-timeTime at which the event was sent
dataEither JSON or a string, depending on the request type. Read more about Buffer in Node.js and bytes literals in Python.
tracerFully configured OpenTelemetry tracer object that allows you to communicate with the user-defined Jaeger service to share tracing data. For more information on how to use the tracer object see Use the OpenTelemetry standard
extensionsJSON object that can contain event payload, a Function's incoming request, or an outgoing response

Event object SDK

The event object is extended by methods making some operations easier. You can use every method by providing event.{FUNCTION_NAME(ARGUMENTS...)}.

  • Node.js
  • Python

Context object

The context object contains information about the Function's invocation, such as runtime details, execution timeout, or memory limits.

See sample context details:

Click to copy
...
{ "function-name": "main",
"timeout": 180,
"runtime": "nodejs14",
"memory-limit": 200Mi }

See the detailed descriptions of these fields:

FieldDescription
function-nameName of the invoked Function
timeoutTime, in seconds, after which the system cancels the request to invoke the Function
runtimeEnvironment used to run the Function. You can use nodejs14, nodejs16, or python39.
memory-limitMaximum amount of memory assigned to run a Function

HTTP requests

You can use the event.extensions.request object to access properties and methods of a given request that vary depending on the runtime. For more information, read the API documentation for Node.js Express and Python.

Custom HTTP responses in Node.js

By default, a failing Function simply throws an error to tell the Event Service to reinject the event at a later point. Such an HTTP-based Function returns the HTTP status code 500. On the contrary, if you manage to invoke a Function successfully, the system returns the default HTTP status code 200.

Apart from these two default codes, you can define custom responses in all Node.js runtimes using the event.extensions.response object.

This object is created by the Express framework and can be customized. For more information, read Node.js API documentation.

This example shows how to set such a custom response in Node.js for the HTTP status code 400:

Click to copy
module.exports = {
main: function (event, context) {
if (event.extensions.request.query.id === undefined) {
res = event.extensions.response;
res.status(400)
return
}
return "42"
}
}

/metrics endpoint

You can use the /metrics endpoint to return the Function metrics. All the information is gathered using Prometheus and can be displayed using the Grafana dashboard (see Kyma observability for more information on how to use Grafana dashboard in Kyma). As this endpoint is provided by Kubeless, it cannot be customized.
For more information, see Kubeless monitoring and Kubeless runtime variants pages.

Override runtime image

You can use a custom runtime image to override the existing one. Your image must meet all the following requirements:

  • Expose the workload endpoint on the right port
  • Provide liveness and readiness check endpoints at /healthz
  • Fetch sources from the path under the KUBELESS_INSTALL_VOLUME environment
  • Security support. Kyma runtimes are secure by default. You only need to protect your images.

Note: For better understanding you can look at main dockerfiles which are responsible for building the final image based on the base_image argument which you as an user can override and what we are doing in this tutorial.

Every Function's Pods container have the same system environments which helps you configure the Functions server. For more information, read the Environment variables page.