×

Creating functions

You can create a basic serverless function using the kn CLI.

You can specify the path, runtime, template, and repository with the template as flags on the command line, or use the -c flag to start the interactive experience in the terminal.

Prerequisites
  • The OpenShift Serverless Operator and Knative Serving are installed on the cluster.

  • You have installed the kn CLI.

Procedure
  • Create a function project:

    $ kn func create -r <repository> -l <runtime> -t <template> <path>
    • Supported runtimes include node, go, python, quarkus, and typescript.

    • Supported templates include http and events.

      Example command
      $ kn func create -l typescript -t events examplefunc
      Example output
      Project path:  /home/user/demo/examplefunc
      Function name: examplefunc
      Runtime:       typescript
      Template:      events
      Writing events to /home/user/demo/examplefunc
    • Alternatively, you can specify a repository that contains a custom template.

      Example command
      $ kn func create -r https://github.com/boson-project/templates/ -l node -t hello-world examplefunc
      Example output
      Project path:  /home/user/demo/examplefunc
      Function name: examplefunc
      Runtime:       node
      Template:      hello-world
      Writing events to /home/user/demo/examplefunc

Building functions

Before you can run a function, you must build the function project by using the kn func build command. This command creates an OCI container image that can be run locally on your computer or on an OpenShift Container Platform cluster. The build command uses the function project name and the image registry name to construct a fully qualified image name for your function.

The OpenShift Container Registry is used by default as the image registry for storing function images. You can override this by using the -r flag:

Example build command
$ kn func build -r quay.io/username
Example output
Building function image
Function image has been built, image: quay.io/username/example-function:latest

To learn more about kn func build command options, you can use the help command:

Build help command
$ kn func help build

Deploying functions

You can deploy a function to your cluster as a Knative service by using the kn func deploy command. If the targeted function is already deployed, it is updated with a new container image that is pushed to a container image registry, and the Knative service is updated.

Prerequisites
  • The OpenShift Serverless Operator and Knative Serving are installed on the cluster.

  • You have installed the Knative (kn) CLI.

  • You have created a project or have access to a project with the appropriate roles and permissions to create applications and other workloads in OpenShift Container Platform.

  • You must have already created and initialized the function that you want to deploy.

Procedure
  • Deploy a function:

    $ kn func deploy [-n <namespace> -p <path> -i <image>]
    Example output
    Function deployed at: http://func.example.com
    • If no namespace is specified, the function is deployed in the current namespace.

    • The function is deployed from the current directory, unless a path is specified.

    • The Knative service name is derived from the project name, and cannot be changed using this command.

Listing existing functions

You can list existing functions by using kn func list. If you want to list functions that have been deployed as Knative services, you can also use kn service list.

Procedure
  • List existing functions:

    $ kn func list [-n <namespace> -p <path>]
    Example output
    NAME           NAMESPACE  RUNTIME  URL                                                                                      READY
    example-function  default    node     http://example-function.default.apps.ci-ln-g9f36hb-d5d6b.origin-ci-int-aws.dev.rhcloud.com  True
  • List functions deployed as Knative services:

    $ kn service list -n <namespace>
    Example output
    NAME            URL                                                                                       LATEST                AGE   CONDITIONS   READY   REASON
    example-function   http://example-function.default.apps.ci-ln-g9f36hb-d5d6b.origin-ci-int-aws.dev.rhcloud.com   example-function-gzl4c   16m   3 OK / 3     True

Describing a function

The kn func info command prints information about a deployed function, such as the function name, image, namespace, Knative service information, route information, and event subscriptions.

Procedure
  • Describe a function:

    $ kn func info [-f <format> -n <namespace> -p <path>]
    Example command
    $ kn func info -p function/example-function
    Example output
    Function name:
      example-function
    Function is built in image:
      docker.io/user/example-function:latest
    Function is deployed as Knative Service:
      example-function
    Function is deployed in namespace:
      default
    Routes:
      http://example-function.default.apps.ci-ln-g9f36hb-d5d6b.origin-ci-int-aws.dev.rhcloud.com

Invoking a deployed function with a test event

You can use the kn func invoke CLI command to send a test request to invoke a function either locally or on your OpenShift Container Platform cluster. This command can be used to test that a function is working and able to receive events correctly.

Example command
$ kn func invoke

The kn func invoke command executes on the local directory by default, and assumes that this directory is a function project.

kn func invoke optional parameters

You can specify optional parameters for the request by using the following kn func invoke CLI command flags.

Flags Description

-t, --target

Specifies the target instance of the invoked function, for example, local or remote or https://staging.example.com/. The default target is local.

-f, --format

Specifies the format of the message, for example, cloudevent or http.

--id

Specifies a unique string identifier for the request.

-n, --namespace

Specifies the namespace on the cluster.

--source

Specifies sender name for the request. This corresponds to the CloudEvent source attribute.

--type

Specifies the type of request, for example, boson.fn. This corresponds to the CloudEvent type attribute.

--data

Specifies content for the request. For CloudEvent requests, this is the CloudEvent data attribute.

--file

Specifies path to a local file containing data to be sent.

--content-type

Specifies the MIME content type for the request.

-p, --path

Specifies path to the project directory.

-c, --confirm

Enables prompting to interactively confirm all options.

-v, --verbose

Enables printing verbose output.

-h, --help

Prints information on usage of kn func invoke.

Main parameters

The following parameters define the main properties of the kn func invoke command:

Event target (-t, --target)

The target instance of the invoked function. Accepts the local value for a locally deployed function, the remote value for a remotely deployed function, or a URL for a function deployed to an arbitrary endpoint. If a target is not specified, it defaults to local.

Event message format (-f, --format)

The message format for the event, such as http or cloudevent. This defaults to the format of the template that was used when creating the function.

Event type (--type)

The type of event that is sent. You can find information about the type parameter that is set in the documentation for each event producer. For example, the API server source might set the type parameter of produced events as dev.knative.apiserver.resource.update.

Event source (--source)

The unique event source that produced the event. This might be a URI for the event source, for example https://10.96.0.1/, or the name of the event source.

Event ID (--id)

A random, unique ID that is created by the event producer.

Event data (--data)

Allows you to specify a data value for the event sent by the kn func invoke command. For example, you can specify a --data value such as "Hello World" so that the event contains this data string. By default, no data is included in the events created by kn func invoke.

Functions that have been deployed to a cluster can respond to events from an existing event source that provides values for properties such as source and type. These events often have a data value in JSON format, which captures the domain specific context of the event. By using the CLI flags noted in this document, developers can simulate those events for local testing.

You can also send event data using the --file flag to provide a local file containing data for the event. In this case, specify the content type using --content-type.

Data content type (--content-type)

If you are using the --data flag to add data for events, you can use the --content-type flag to specify what type of data is carried by the event. In the previous example, the data is plain text, so you might specify kn func invoke --data "Hello world!" --content-type "text/plain".

Example commands

This is the general invocation of the kn func invoke command:

$ kn func invoke --type <event_type> --source <event_source> --data <event_data> --content-type <content_type> --id <event_ID> --format <format> --namespace <namespace>

For example, to send a "Hello world!" event, you can run:

$ kn func invoke --type ping --source example-ping --data "Hello world!" --content-type "text/plain" --id example-ID --format http --namespace my-ns
Specifying the file with data

To specify the file on disk that contains the event data, use the --file and --content-type flags:

$ kn func invoke --file <path> --content-type <content-type>

For example, to send JSON data stored in the test.json file, use this command:

$ kn func invoke --file ./test.json --content-type application/json
Specifying the function project

You can specify a path to the function project by using the --path flag:

$ kn func invoke --path <path_to_function>

For example, to use the function project located in the ./example/example-function directory, use this command:

$ kn func invoke --path ./example/example-function
Specifying where the target function is deployed

By default, kn func invoke targets the local deployment of the function:

$ kn func invoke

To use a different deployment, use the --target flag:

$ kn func invoke --target <target>

For example, to use the function deployed on the cluster, use the --target remote flag:

$ kn func invoke --target remote

To use the function deployed at an arbitrary URL, use the --target <URL> flag:

$ kn func invoke --target "https://my-event-broker.example.com"

You can explicitly target the local deployment. In this case, if the function is not running locally, the command fails:

$ kn func invoke --target local

Deleting a function

You can delete a function from your cluster by using the kn func delete command.

Procedure
  • Delete a function:

    $ kn func delete [<function_name> -n <namespace> -p <path>]
    • If the name or path of the function to delete is not specified, the current directory is searched for a func.yaml file that is used to determine the function to delete.

    • If the namespace is not specified, it defaults to the namespace value in the func.yaml file.