Creating functions

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

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

Procedure
  • Create a function project:

    $ kn func create <path> -l <runtime> -t <template>
    • 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

Building functions

Before you can run a function, you must build the function project by using the kn func build command. The build command reads the func.yaml file from the function project directory to determine the image name and registry.

Example func.yaml
name: example-function
namespace: default
runtime: node
image: <image_from_registry>
imageDigest: ""
trigger: http
builder: default
builderMap:
  default: quay.io/boson/faas-nodejs-builder
envs: {}

If the image name and registry are not set in the func.yaml file, you must either specify the registry flag, -r when using the kn func build command, or you are prompted to provide a registry value in the terminal when building a function. An image name is then derived from the registry value that you have provided.

Example command using the -r registry flag
$ kn func build [-i <image> -r <registry> -p <path>]
Example output
Building function image
Function image has been built, image: quay.io/username/example-function:latest

This command creates an OCI container image that can be run locally on your computer, or on a Kubernetes cluster.

Example using the registy prompt
$ kn func build
A registry for function images is required (e.g. 'quay.io/boson').

Registry for function images: quay.io/username
Building function image
Function image has been built, image: quay.io/username/example-function:latest

The values for image and registry are persisted to the func.yaml file, so that subsequent invocations do not require the user to specify these again.

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
  • You must have already initialized the function that you want to deploy.

Procedure
  • Deploy a function:

    $ kn func deploy [-n <namespace> -p <path> -i <image> -r <registry>]
    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

Emitting a test event to a deployed function

You can use the kn func emit CLI command to emit a CloudEvent to a function that is either deployed locally or deployed to 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 emit

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

kn func emit optional parameters

You can specify optional parameters for the emitted CloudEvent by using the kn func emit CLI command flags.

List of flags from --help command output
Flags:
  -c, --content-type string   The MIME Content-Type for the CloudEvent data  (Env: $FUNC_CONTENT_TYPE) (default "application/json")
  -d, --data string           Any arbitrary string to be sent as the CloudEvent data. Ignored if --file is provided  (Env: $FUNC_DATA)
  -f, --file string           Path to a local file containing CloudEvent data to be sent  (Env: $FUNC_FILE)
  -h, --help                  help for emit
  -i, --id string             CloudEvent ID (Env: $FUNC_ID) (default "306bd6a0-0b0a-48ba-b187-b633571d072a")
  -p, --path string           Path to the project directory. Ignored when --sink is provided (Env: $FUNC_PATH) (default "/home/lanceball/src/github.com/nodeshift/opossum")
  -k, --sink string           Send the CloudEvent to the function running at [sink]. The special value "local" can be used to send the event to a function running on the local host. When provided, the --path flag is ignored  (Env: $FUNC_SINK)
  -s, --source string         CloudEvent source (Env: $FUNC_SOURCE) (default "/boson/fn")
  -t, --type string           CloudEvent type  (Env: $FUNC_TYPE) (default "boson.fn")

In particular, you might find it useful to specify the following parameters:

Event type

The type of event being emitted. You can find information about the type parameter that is set for events from a certain event producer in the documentation for that event producer. For example, the API server source may set the type parameter of produced events as dev.knative.apiserver.resource.update.

Event source

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

Event ID

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

Event data

Allows you to specify a data value for the event sent by the kn func emit 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 emit.

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 form, which captures the domain specific context of the event. 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.

Data content type

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

Example commands specifying event parameters by using flags
$ kn func emit --type <event_type> --source <event_source> --data <event_data> --content-type <content_type> -i <event_ID>
$ kn func emit --type ping --source example-ping --data "Hello world!" --content-type "text/plain" -i example-ID
Example commands specifying a file on disk that contains the event parameters
$ kn func emit --file <path>
$ kn func emit --file ./test.json
Example commands specifying a path to the function

You can specify a path to the function project by using the --path flag, or specify an endpoint for the function by using the --sink flag:

$ kn func emit --path <path_to_function>
$ kn func emit --path ./example/example-function
Example commands specifying a function deployed as a Knative service (sink)
$ kn func emit --sink <service_URL>
$ kn func emit --sink "http://example.function.com"

The --sink flag also accepts the special value local to send an event to a function running locally:

$ kn func emit --sink 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.