Knative CLI

Prerequisites

• OpenShift Serverless Operator and Knative Serving are installed on your 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.

Procedure

• Create a Knative service:

  $ kn service create <service-name> --image <image> --tag <tag-value>

  Where:

  • --image is the URI of the image for the application.

  • --tag is an optional flag that can be used to add a tag to the initial revision that is created with the service.

    Example command

    $ kn service create showcase \
        --image quay.io/openshift-knative/showcase

    Example output

    Creating service 'showcase' in namespace 'default':
    
      0.271s The Route is still working to reflect the latest desired specification.
      0.580s Configuration "showcase" is waiting for a Revision to become ready.
      3.857s ...
      3.861s Ingress has not yet been reconciled.
      4.270s Ready to serve.
    
    Service 'showcase' created with latest revision 'showcase-00001' and URL:
    http://showcase-default.apps-crc.testing

Example commands

• Update a service by adding a new environment variable:

  $ kn service update <service_name> --env <key>=<value>

• Update a service by adding a new port:

  $ kn service update <service_name> --port 80

• Update a service by adding new request and limit parameters:

  $ kn service update <service_name> --request cpu=500m --limit memory=1024Mi --limit cpu=1000m

• Assign the latest tag to a revision:

  $ kn service update <service_name> --tag <revision_name>=latest

• Update a tag from testing to staging for the latest READY revision of a service:

  $ kn service update <service_name> --untag testing --tag @latest=staging

• Add the test tag to a revision that receives 10% of traffic, and send the rest of the traffic to the latest READY revision of a service:

  $ kn service update <service_name> --tag <revision_name>=test --traffic test=10,@latest=90

Example commands

• Create a service:

  $ kn service apply <service_name> --image <image>

• Add an environment variable to a service:

  $ kn service apply <service_name> --image <image> --env <key>=<value>

• Read the service declaration from a JSON or YAML file:

  $ kn service apply <service_name> -f <filename>

Example commands

• Describe a service:

  $ kn service describe --verbose <service_name>

  The --verbose flag is optional but can be included to provide a more detailed description. The difference between a regular and verbose output is shown in the following examples:

  Example output without --verbose flag

  Name:       showcase
  Namespace:  default
  Age:        2m
  URL:        http://showcase-default.apps.ocp.example.com
  
  Revisions:
    100%  @latest (showcase-00001) [1] (2m)
          Image:  quay.io/openshift-knative/showcase (pinned to aaea76)
  
  Conditions:
    OK TYPE                   AGE REASON
    ++ Ready                   1m
    ++ ConfigurationsReady     1m
    ++ RoutesReady             1m

  Example output with --verbose flag

  Name:         showcase
  Namespace:    default
  Annotations:  serving.knative.dev/creator=system:admin
                serving.knative.dev/lastModifier=system:admin
  Age:          3m
  URL:          http://showcase-default.apps.ocp.example.com
  Cluster:      http://showcase.default.svc.cluster.local
  
  Revisions:
    100%  @latest (showcase-00001) [1] (3m)
          Image:  quay.io/openshift-knative/showcase (pinned to aaea76)
          Env:    GREET=Bonjour
  
  Conditions:
    OK TYPE                   AGE REASON
    ++ Ready                   3m
    ++ ConfigurationsReady     3m
    ++ RoutesReady             3m

• Describe a service in YAML format:

  $ kn service describe <service_name> -o yaml

• Describe a service in JSON format:

  $ kn service describe <service_name> -o json

• Print the service URL only:

  $ kn service describe <service_name> -o url

• You can manually modify the descriptor file before using it to make changes on the cluster.
• You can locally track the descriptor file of a service in a version control system. This enables you to reuse the descriptor file in places other than the target cluster, for example in continuous integration (CI) pipelines, development environments, or demos.
• You can examine the created descriptor files to learn about Knative services. In particular, you can see how the resulting service is influenced by the different arguments passed to the kn command.

Prerequisites

• OpenShift Serverless Operator and Knative Serving are installed on your cluster.
• You have installed the Knative (kn) CLI.

• Add a container from an image and print it to standard output:

  $ kn container add <container_name> --image <image_uri>

  Example command

  $ kn container add sidecar --image docker.io/example/sidecar

  Example output

  containers:
  - image: docker.io/example/sidecar
    name: sidecar
    resources: {}

• Chain two kn container add commands together, and then pass them to a kn service create command to create a Knative service with two containers:

  $ kn container add <first_container_name> --image <image_uri> | \
  kn container add <second_container_name> --image <image_uri> | \
  kn service create <service_name> --image <image_uri> --extra-containers -

  --extra-containers - specifies a special case where kn reads the pipe input instead of a YAML file.

  Example command

  $ kn container add sidecar --image docker.io/example/sidecar:first | \
  kn container add second --image docker.io/example/sidecar:second | \
  kn service create my-service --image docker.io/example/my-app:latest --extra-containers -

  The --extra-containers flag can also accept a path to a YAML file:

  $ kn service create <service_name> --image <image_uri> --extra-containers <filename>

  Example command

  $ kn service create my-service --image docker.io/example/my-app:latest --extra-containers my-extra-containers.yaml

Prerequisites

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

• You have created a Knative service or route, and control a custom domain that you want to map to that CR.

  Note

  Your custom domain must point to the DNS of the OpenShift Container Platform 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.

Procedure

• Map a domain to a CR in the current namespace:

  $ kn domain create <domain_mapping_name> --ref <target_name>

  Example command

  $ kn domain create example.com --ref showcase

  The --ref flag specifies an Addressable target CR for domain mapping.

  If a prefix is not provided when using the --ref flag, it is assumed that the target is a Knative service in the current namespace.

• Map a domain to a Knative service in a specified namespace:

  $ kn domain create <domain_mapping_name> --ref <ksvc:service_name:service_namespace>

  Example command

  $ kn domain create example.com --ref ksvc:showcase:example-namespace

• Map a domain to a Knative route:

  $ kn domain create <domain_mapping_name> --ref <kroute:route_name>

  Example command

  $ kn domain create example.com --ref kroute:example-route

Prerequisites

• The OpenShift Serverless Operator and Knative Serving are installed on your cluster.
• You have created at least one DomainMapping CR.
• You have installed the Knative (kn) CLI tool.
• 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.

Procedure

• List existing DomainMapping CRs:

  $ kn domain list -n <domain_mapping_namespace>

• View details of an existing DomainMapping CR:

  $ kn domain describe <domain_mapping_name>

• Update a DomainMapping CR to point to a new target:

  $ kn domain update --ref <target>

• Delete a DomainMapping CR:

  $ kn domain delete <domain_mapping_name>

Prerequisites

• The OpenShift Serverless Operator and Knative Eventing are installed on the cluster.
• You have installed the Knative (kn) CLI.

Prerequisites

• The OpenShift Serverless Operator and Knative Eventing are installed on the cluster.
• 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 have installed the OpenShift CLI (oc).
• You have installed the Knative (kn) CLI.

• To view the events in a web browser, open the link returned by the following command:

  $ kn service describe event-display -o url

  Figure 4.1. Example browser page

  

• Alternatively, to see the logs in the terminal, view the event-display logs for the pods by entering the following command:

  $ oc logs $(oc get pod -o name | grep event-display) -c user-container

  Example output

  ☁️  cloudevents.Event
  Validation: valid
  Context Attributes,
    specversion: 1.0
    type: dev.knative.apiserver.resource.update
    datacontenttype: application/json
    ...
  Data,
    {
      "apiVersion": "v1",
      "involvedObject": {
        "apiVersion": "v1",
        "fieldPath": "spec.containers{event-origin}",
        "kind": "Pod",
        "name": "event-origin",
        "namespace": "default",
         .....
      },
      "kind": "Event",
      "message": "Started container",
      "metadata": {
        "name": "event-origin.159d7608e3a3572c",
        "namespace": "default",
        ....
      },
      "reason": "Started",
      ...
    }

Prerequisites

• The OpenShift Serverless Operator, Knative Serving and Knative Eventing 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.
• Optional: If you want to use the verification steps for this procedure, install the OpenShift CLI (oc).

Deleting the ping source

• Delete the ping source:

  $ kn delete pingsources.sources.knative.dev <ping_source_name>

Prerequisites

• The OpenShift Serverless Operator, Knative Eventing, Knative Serving, and the KnativeKafka custom resource (CR) are installed on your cluster.
• 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 have access to a Red Hat AMQ Streams (Kafka) cluster that produces the Kafka messages you want to import.
• You have installed the Knative (kn) CLI.
• Optional: You have installed the OpenShift CLI (oc) if you want to use the verification steps in this procedure.

Prerequisites

• The OpenShift Serverless Operator and Knative Serving are installed on the cluster.
• You have installed the Knative (kn) CLI.

Procedure

• Create a function project:

  $ kn func create -r <repository> -l <runtime> -t <template> <path>

  • Accepted runtime values include quarkus, node, typescript, go, python, springboot, and rust.

  • Accepted template values include http and cloudevents.

    Example command

    $ kn func create -l typescript -t cloudevents examplefunc

    Example output

    Created typescript function in /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

    Created node function in /home/user/demo/examplefunc

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.

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

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

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 deployed the function that you want to invoke.

Procedure

• Invoke a function:

  $ kn func invoke

  • The kn func invoke command only works when there is either a local container image currently running, or when there is a function deployed in the cluster.
  • The kn func invoke command executes on the local directory by default, and assumes that this directory is a function project.

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.