Chapter 4. Knative CLI

Procedure

1. In offline mode, create a local Knative service descriptor file:

   Copy to Clipboard Toggle word wrap

   $ kn service create event-display \
       --image quay.io/openshift-knative/knative-eventing-sources-event-display:latest \
       --target ./ \
       --namespace test

   Example output

   Copy to Clipboard Toggle word wrap

   Service 'event-display' created in namespace 'test'.

   • The --target ./ flag enables offline mode and specifies ./ as the directory for storing the new directory tree.

     If you do not specify an existing directory, but use a filename, such as --target my-service.yaml, then no directory tree is created. Instead, only the service descriptor file my-service.yaml is created in the current directory.

     The filename can have the .yaml, .yml, or .json extension. Choosing .json creates the service descriptor file in the JSON format.

   • The --namespace test option places the new service in the test namespace.

     If you do not use --namespace, and you are logged in to an OpenShift Container Platform cluster, the descriptor file is created in the current namespace. Otherwise, the descriptor file is created in the default namespace.

2. Examine the created directory structure:

   Copy to Clipboard Toggle word wrap

   $ tree ./

   Example output

   Copy to Clipboard Toggle word wrap

   ./
   └── test
       └── ksvc
           └── event-display.yaml
   
   2 directories, 1 file

   • The current ./ directory specified with --target contains the new test/ directory that is named after the specified namespace.
   • The test/ directory contains the ksvc directory, named after the resource type.
   • The ksvc directory contains the descriptor file event-display.yaml, named according to the specified service name.

3. Examine the generated service descriptor file:

   Copy to Clipboard Toggle word wrap

   $ cat test/ksvc/event-display.yaml

   Example output

   Copy to Clipboard Toggle word wrap

   apiVersion: serving.knative.dev/v1
   kind: Service
   metadata:
     creationTimestamp: null
     name: event-display
     namespace: test
   spec:
     template:
       metadata:
         annotations:
           client.knative.dev/user-image: quay.io/openshift-knative/knative-eventing-sources-event-display:latest
         creationTimestamp: null
       spec:
         containers:
         - image: quay.io/openshift-knative/knative-eventing-sources-event-display:latest
           name: ""
           resources: {}
   status: {}

4. List information about the new service:

   Copy to Clipboard Toggle word wrap

   $ kn service describe event-display --target ./ --namespace test

   Example output

   Copy to Clipboard Toggle word wrap

   Name:       event-display
   Namespace:  test
   Age:
   URL:
   
   Revisions:
   
   Conditions:
     OK TYPE    AGE REASON

   • The --target ./ option specifies the root directory for the directory structure containing namespace subdirectories.

     Alternatively, you can directly specify a YAML or JSON filename with the --target option. The accepted file extensions are .yaml, .yml, and .json.

   • The --namespace option specifies the namespace, which communicates to kn the subdirectory that contains the necessary service descriptor file.

     If you do not use --namespace, and you are logged in to an OpenShift Container Platform cluster, kn searches for the service in the subdirectory that is named after the current namespace. Otherwise, kn searches in the default/ subdirectory.

5. Use the service descriptor file to create the service on the cluster:

   Copy to Clipboard Toggle word wrap

   $ kn service create -f test/ksvc/event-display.yaml

   Example output

   Copy to Clipboard Toggle word wrap

   Creating service 'event-display' in namespace 'test':
   
     0.058s The Route is still working to reflect the latest desired specification.
     0.098s ...
     0.168s Configuration "event-display" is waiting for a Revision to become ready.
    23.377s ...
    23.419s Ingress has not yet been reconciled.
    23.534s Waiting for load balancer to be ready
    23.723s Ready to serve.
   
   Service 'event-display' created to latest revision 'event-display-00001' is available at URL:
   http://event-display-test.apps.example.com

Procedure

1. List the available event source types in the terminal:

   Copy to Clipboard Toggle word wrap

   $ kn source list-types

   Example output

   Copy to Clipboard Toggle word wrap

   TYPE              NAME                                            DESCRIPTION
   ApiServerSource   apiserversources.sources.knative.dev            Watch and send Kubernetes API events to a sink
   PingSource        pingsources.sources.knative.dev                 Periodically send ping events to a sink
   SinkBinding       sinkbindings.sources.knative.dev                Binding for connecting a PodSpecable to a sink

2. Optional: You can also list the available event source types in YAML format:

   Copy to Clipboard Toggle word wrap

   $ kn source list-types -o yaml

1. Create a service account, role, and role binding for the event source as a YAML file:

   Copy to Clipboard Toggle word wrap

   apiVersion: v1
   kind: ServiceAccount
   metadata:
     name: events-sa
     namespace: default 

   1

   
   
   ---
   apiVersion: rbac.authorization.k8s.io/v1
   kind: Role
   metadata:
     name: event-watcher
     namespace: default 

   2

   
   rules:
     - apiGroups:
         - ""
       resources:
         - events
       verbs:
         - get
         - list
         - watch
   
   ---
   apiVersion: rbac.authorization.k8s.io/v1
   kind: RoleBinding
   metadata:
     name: k8s-ra-event-watcher
     namespace: default 

   3

   
   roleRef:
     apiGroup: rbac.authorization.k8s.io
     kind: Role
     name: event-watcher
   subjects:
     - kind: ServiceAccount
       name: events-sa
       namespace: default 

   4

   1 2 3 4

   Change this namespace to the namespace that you have selected for installing the event source.

2. Apply the YAML file:

   Copy to Clipboard Toggle word wrap

   $ oc apply -f <filename>

3. Create an API server source that has an event sink. In the following example, the sink is a broker:

   Copy to Clipboard Toggle word wrap

   $ kn source apiserver create <event_source_name> --sink broker:<broker_name> --resource "event:v1" --service-account <service_account_name> --mode Resource

4. To check that the API server source is set up correctly, create a Knative service that dumps incoming messages to its log:

   Copy to Clipboard Toggle word wrap

   $ kn service create <service_name> --image quay.io/openshift-knative/knative-eventing-sources-event-display:latest

5. If you used a broker as an event sink, create a trigger to filter events from the default broker to the service:

   Copy to Clipboard Toggle word wrap

   $ kn trigger create <trigger_name> --sink ksvc:<service_name>

6. Create events by launching a pod in the default namespace:

   Copy to Clipboard Toggle word wrap

   $ oc create deployment hello-node --image quay.io/openshift-knative/knative-eventing-sources-event-display:latest

7. Check that the controller is mapped correctly by inspecting the output generated by the following command:

   Copy to Clipboard Toggle word wrap

   $ kn source apiserver describe <source_name>

   Example output

   Copy to Clipboard Toggle word wrap

   Name:                mysource
   Namespace:           default
   Annotations:         sources.knative.dev/creator=developer, sources.knative.dev/lastModifier=developer
   Age:                 3m
   ServiceAccountName:  events-sa
   Mode:                Resource
   Sink:
     Name:       default
     Namespace:  default
     Kind:       Broker (eventing.knative.dev/v1)
   Resources:
     Kind:        event (v1)
     Controller:  false
   Conditions:
     OK TYPE                     AGE REASON
     ++ Ready                     3m
     ++ Deployed                  3m
     ++ SinkProvided              3m
     ++ SufficientPermissions     3m
     ++ EventTypesProvided        3m

1. Get the pods:

   Copy to Clipboard Toggle word wrap

   $ oc get pods

2. View the message dumper function logs for the pods:

   Copy to Clipboard Toggle word wrap

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

   Example output

   Copy to Clipboard Toggle word wrap

   ☁️  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{hello-node}",
         "kind": "Pod",
         "name": "hello-node",
         "namespace": "default",
          .....
       },
       "kind": "Event",
       "message": "Started container",
       "metadata": {
         "name": "hello-node.159d7608e3a3572c",
         "namespace": "default",
         ....
       },
       "reason": "Started",
       ...
     }

Deleting the API server source

1. Delete the trigger:

   Copy to Clipboard Toggle word wrap

   $ kn trigger delete <trigger_name>

2. Delete the event source:

   Copy to Clipboard Toggle word wrap

   $ kn source apiserver delete <source_name>

3. Delete the service account, cluster role, and cluster binding:

   Copy to Clipboard Toggle word wrap

   $ oc delete -f authentication.yaml

Procedure

1. To verify that the ping source is working, create a simple Knative service that dumps incoming messages to the service logs:

   Copy to Clipboard Toggle word wrap

   $ kn service create event-display \
       --image quay.io/openshift-knative/knative-eventing-sources-event-display:latest

2. For each set of ping events that you want to request, create a ping source in the same namespace as the event consumer:

   Copy to Clipboard Toggle word wrap

   $ kn source ping create test-ping-source \
       --schedule "*/2 * * * *" \
       --data '{"message": "Hello world!"}' \
       --sink ksvc:event-display

3. Check that the controller is mapped correctly by entering the following command and inspecting the output:

   Copy to Clipboard Toggle word wrap

   $ kn source ping describe test-ping-source

   Example output

   Copy to Clipboard Toggle word wrap

   Name:         test-ping-source
   Namespace:    default
   Annotations:  sources.knative.dev/creator=developer, sources.knative.dev/lastModifier=developer
   Age:          15s
   Schedule:     */2 * * * *
   Data:         {"message": "Hello world!"}
   
   Sink:
     Name:       event-display
     Namespace:  default
     Resource:   Service (serving.knative.dev/v1)
   
   Conditions:
     OK TYPE                 AGE REASON
     ++ Ready                 8s
     ++ Deployed              8s
     ++ SinkProvided         15s
     ++ ValidSchedule        15s
     ++ EventTypeProvided    15s
     ++ ResourcesCorrect     15s

1. Watch for new pods created:

   Copy to Clipboard Toggle word wrap

   $ watch oc get pods

2. Cancel watching the pods using Ctrl+C, then look at the logs of the created pod:

   Copy to Clipboard Toggle word wrap

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

   Example output

   Copy to Clipboard Toggle word wrap

   ☁️  cloudevents.Event
   Validation: valid
   Context Attributes,
     specversion: 1.0
     type: dev.knative.sources.ping
     source: /apis/v1/namespaces/default/pingsources/test-ping-source
     id: 99e4f4f6-08ff-4bff-acf1-47f61ded68c9
     time: 2020-04-07T16:16:00.000601161Z
     datacontenttype: application/json
   Data,
     {
       "message": "Hello world!"
     }

Procedure

1. To verify that the Kafka event source is working, create a Knative service that dumps incoming events into the service logs:

   Copy to Clipboard Toggle word wrap

   $ kn service create event-display \
       --image quay.io/openshift-knative/knative-eventing-sources-event-display

2. Create a KafkaSource CR:

   Copy to Clipboard Toggle word wrap

   $ kn source kafka create <kafka_source_name> \
       --servers <cluster_kafka_bootstrap>.kafka.svc:9092 \
       --topics <topic_name> --consumergroup my-consumer-group \
       --sink event-display

   Note

   Replace the placeholder values in this command with values for your source name, bootstrap servers, and topics.

   The --servers, --topics, and --consumergroup options specify the connection parameters to the Kafka cluster. The --consumergroup option is optional.

3. Optional: View details about the KafkaSource CR you created:

   Copy to Clipboard Toggle word wrap

   $ kn source kafka describe <kafka_source_name>

   Example output

   Copy to Clipboard Toggle word wrap

   Name:              example-kafka-source
   Namespace:         kafka
   Age:               1h
   BootstrapServers:  example-cluster-kafka-bootstrap.kafka.svc:9092
   Topics:            example-topic
   ConsumerGroup:     example-consumer-group
   
   Sink:
     Name:       event-display
     Namespace:  default
     Resource:   Service (serving.knative.dev/v1)
   
   Conditions:
     OK TYPE            AGE REASON
     ++ Ready            1h
     ++ Deployed         1h
     ++ SinkProvided     1h

Verification steps

1. Trigger the Kafka instance to send a message to the topic:

   Copy to Clipboard Toggle word wrap

   $ oc -n kafka run kafka-producer \
       -ti --image=quay.io/strimzi/kafka:latest-kafka-2.7.0 --rm=true \
       --restart=Never -- bin/kafka-console-producer.sh \
       --broker-list <cluster_kafka_bootstrap>:9092 --topic my-topic

   Enter the message in the prompt. This command assumes that:

   • The Kafka cluster is installed in the kafka namespace.
   • The KafkaSource object has been configured to use the my-topic topic.

2. Verify that the message arrived by viewing the logs:

   Copy to Clipboard Toggle word wrap

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

   Example output

   Copy to Clipboard Toggle word wrap

   ☁️  cloudevents.Event
   Validation: valid
   Context Attributes,
     specversion: 1.0
     type: dev.knative.kafka.event
     source: /apis/v1/namespaces/default/kafkasources/example-kafka-source#example-topic
     subject: partition:46#0
     id: partition:46/offset:0
     time: 2021-03-10T11:21:49.4Z
   Extensions,
     traceparent: 00-161ff3815727d8755848ec01c866d1cd-7ff3916c44334678-00
   Data,
     Hello!